From 3f54a0aec951426cc66046ccd8f4dccaab657635 Mon Sep 17 00:00:00 2001 From: mz-fuzzy Date: Tue, 28 Jun 2016 22:09:43 -0700 Subject: [PATCH] Documentation update: - update for makefile improvements - python wrapper updates - cross compilation - duplications removed - minor doc fixes --- RF24.h | 256 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 135 insertions(+), 121 deletions(-) diff --git a/RF24.h b/RF24.h index 6b5b080e7..d56dd56e1 100644 --- a/RF24.h +++ b/RF24.h @@ -112,7 +112,7 @@ class RF24 //#if defined (RF24_LINUX) /** - * Optional Raspberry Pi Constructor + * Optional Linux Constructor * * Creates a new instance of this driver. Before using, you create an instance * and send in the unique pins that this chip is connected to. @@ -1135,8 +1135,8 @@ s * */ /** - * @example GettingStarted.cpp - * For Raspberry Pi
+ * @example gettingstarted.cpp + * For Linux
* Updated: TMRh20 2014
* * This is an example of how to use the RF24 class to communicate on a basic level. Configure and write this sketch to two @@ -1159,8 +1159,8 @@ s * */ /** - * @example GettingStarted_Call_Response.cpp - * For Raspberry Pi
+ * @example gettingstarted_call_response.cpp + * For Linux
* New: TMRh20 2014
* * This example continues to make use of all the normal functionality of the radios including @@ -1190,8 +1190,8 @@ s * */ /** - * @example Transfer.cpp - * For Raspberry Pi
+ * @example transfer.cpp + * For Linux
* This example demonstrates half-rate transfer using the FIFO buffers
* * It is an example of how to use the RF24 class. Write this sketch to two @@ -1282,7 +1282,7 @@ s * /** * @example pingpair_dyn.cpp * - * This is an example of how to use payloads of a varying (dynamic) size on Raspberry Pi. + * This is an example of how to use payloads of a varying (dynamic) size on Linux. */ /** @@ -1291,18 +1291,6 @@ s * * This is a python example for RPi of how to use payloads of a varying (dynamic) size. */ -/** - * @example pingpair_dyn.ino - * - * This is an example of how to use payloads of a varying (dynamic) size. - */ - - /** - * @example pingpair_dyn.ino - * - * This is an example of how to use payloads of a varying (dynamic) size. - */ - /** * @example scanner.ino * @@ -1341,7 +1329,7 @@ s * * - Uses SPI transactions on Arduino * - New layout for easier portability: Break out defines & includes for individual platforms to RF24/utility * - MRAA support added ( Galileo, Edison, etc) - * - BBB/Generic Linux support via spidev & MRAA + * - Generic Linux support (SPIDEV) support * - Support for RPi 2 added * - Major Documentation cleanup & update (Move all docs to github.io) * @@ -1384,8 +1372,9 @@ s * * * @li Arduino (Uno, Nano, Mega, Due, Galileo, etc) * @li ATTiny - * @li Linux ( RPi , BBB, MRAA supported boards ( Galileo, Edison, etc)) - * @li Python wrapper available for RPi + * @li Linux devices( RPi , Linux SPI userspace device, MRAA supported boards ( Galileo, Edison, etc), LittleWire) + * @li Cross-compilation for linux devices + * @li Python wrapper available for Linux devices * *
* **General µC Pin layout** (See the individual board support pages for more info) @@ -1559,25 +1548,25 @@ s * * * * - * @page BBB BeagleBone Black + * @page Linux Linux devices * - * BeagleBone Black is supported via MRAA or SPIDEV. + * Generic Linux devices are supported via SPIDEV, MRAA, RPi native via BCM2835, or using LittleWire. * - * @note The SPIDEV option should work with most Linux systems supporting SPIDEV.
- * Users may need to edit the RF24/utility/BBB/spi.cpp file to configure the spi device. (Defaults: "/dev/spidev1.0"; or "/dev/spidev1.1"; ) + * @note The SPIDEV option should work with most Linux systems supporting spi userspace device.
* *
* @section AutoInstall Automated Install - *(**Designed & Tested on RPi** - Defaults to SPIDEV on BBB) + *(**Designed & Tested on RPi** - Defaults to SPIDEV on devices supporting it) * * - * 1. Download the install.sh file from http://tmrh20.github.io/RF24Installer/RPi/install.sh + * 1. Install prerequisites if there are any (MRAA, LittleWire libraries, setup SPI device etc) + * 2. Download the install.sh file from http://tmrh20.github.io/RF24Installer/RPi/install.sh * @code wget http://tmrh20.github.io/RF24Installer/RPi/install.sh @endcode - * 2. Make it executable: + * 3. Make it executable * @code chmod +x install.sh @endcode - * 3. Run it and choose your options + * 4. Run it and choose your options * @code ./install.sh @endcode - * 4. Run an example from one of the libraries + * 5. Run an example from one of the libraries * @code * cd rf24libs/RF24/examples_linux * @endcode @@ -1589,18 +1578,20 @@ s * * *
* @section ManInstall Manual Install - * 1. Make a directory to contain the RF24 and possibly RF24Network lib and enter it: + * 1. Install prerequisites if there are any (MRAA, LittleWire libraries, setup SPI device etc) + * @note See the MRAA documentation for more info on installing MRAA
+ * 2. Make a directory to contain the RF24 and possibly RF24Network lib and enter it * @code * mkdir ~/rf24libs * cd ~/rf24libs * @endcode - * 2. Clone the RF24 repo: + * 3. Clone the RF24 repo * @code git clone https://github.com/tmrh20/RF24.git RF24 @endcode - * 3. Change to the new RF24 directory + * 4. Change to the new RF24 directory * @code cd RF24 @endcode - * 4. Build the library, and run an example file: - * **Note:** See the MRAA documentation for more info on installing MRAA - * @code sudo make install OR sudo make install RF24_MRAA=1 @endcode + * 5. Configure build environment using @code ./configure @endcode script. It auto detectes device and build environment. For overriding autodetections, use command-line switches, see @code ./configure --help @endcode for description. + * 6. Build the library, and run an example file + * @code sudo make install @endcode * @code * cd examples_linux * @endcode @@ -1620,33 +1611,11 @@ s * * RF24 supports all MRAA supported platforms, but might not be tested on each individual platform due to the wide range of hardware support:
* Report an RF24 bug or issue * - * @section Setup Setup + * @section Setup Setup and installation * 1. Install the MRAA lib * 2. As per your device, SPI may need to be enabled + * 3. Follow Linux installation steps to install RF24 libraries * - * @section MRAA_Install Install - * - * 1. Make a directory to contain the RF24 and possibly RF24Network lib and enter it: - * @code - * mkdir ~/rf24libs - * cd ~/rf24libs -* @endcode - * 2. Clone the RF24 repo: - * @code git clone https://github.com/tmrh20/RF24.git RF24 @endcode - * 3. Change to the new RF24 directory - * @code cd RF24 @endcode - * 4. Build the library: - * @code sudo make install -B RF24_MRAA=1 @endcode - * 5. Configure the correct pins in gettingstarted.cpp (See http://iotdk.intel.com/docs/master/mraa/index.html ) - * @code - * cd examples_linux - * nano gettingstarted.cpp - * @endcode - * 6. Build an example - * @code - * make - * sudo ./gettingstarted - * @endcode * *


* @@ -1665,43 +1634,11 @@ s * * @code sudo raspi-config @endcode * A. Update the tool via the menu as required
* B. Select **Advanced** and **enable the SPI kernel module**
- * C. Update other software and libraries: + * C. Update other software and libraries * @code sudo apt-get update @endcode * @code sudo apt-get upgrade @endcode - *
- * @section AutoInstall Automated Install - * - * 1. Download the install.sh file from http://tmrh20.github.io/RF24Installer/RPi/install.sh - * @code wget http://tmrh20.github.io/RF24Installer/RPi/install.sh @endcode - * 2. Make it executable: - * @code chmod +x install.sh @endcode - * 3. Run it and choose your options - * @code ./install.sh @endcode - * 4. Run an example from one of the libraries - * @code - * cd rf24libs/RF24/examples_linux - * make - * sudo ./gettingstarted - * @endcode *

- * @section ManInstall Manual Install - * 1. Make a directory to contain the RF24 and possibly RF24Network lib and enter it: - * @code - * mkdir ~/rf24libs - * cd ~/rf24libs -* @endcode - * 2. Clone the RF24 repo: - * @code git clone https://github.com/tmrh20/RF24.git RF24 @endcode - * 3. Change to the new RF24 directory - * @code cd RF24 @endcode - * 4. Build the library, and run an example file: - * @code sudo make install - * cd examples_linux - * make - * sudo ./gettingstarted - * @endcode * - *

* @section Build Build Options * The default build on Raspberry Pi utilizes the included **BCM2835** driver from http://www.airspayce.com/mikem/bcm2835 * 1. @code sudo make install -B @endcode @@ -1709,7 +1646,7 @@ s * * Build using the **MRAA** library from http://iotdk.intel.com/docs/master/mraa/index.html
* MRAA is not included. See the MRAA platform page for more information. * - * 1. Install, and build MRAA: + * 1. Install, and build MRAA * @code * git clone https://github.com/intel-iot-devkit/mraa.git * cd mraa @@ -1725,15 +1662,21 @@ s * * Run @code sudo ldconfig @endcode * * 3. Install RF24, using MRAA - * @code sudo make install -B RF24_MRAA=1 @endcode + * @code + * ./configure --driver=MRAA + * sudo make install -B + * @endcode * See the gettingstarted example for an example of pin configuration * - * Build using **spidev**: + * Build using **SPIDEV** * - * 1. Edit the RF24/utility/BBB/spi.cpp file - * 2. Change the default device definition to @code this->device = "/dev/spidev0.0";; @endcode - * 3. Run @code sudo make install -B RF24_SPIDEV=1 @endcode - * 4. See the gettingstarted example for an example of pin configuration + * 1. Make sure that spi device support is enabled and /dev/spidev\.\ is present + * 2. Install RF24, using SPIDEV + * @code + * ./configure --driver=SPIDEV + * sudo make install -B + * @endcode + * 3. See the gettingstarted example for an example of pin configuration * *
* @section Pins Connections and Pin Configuration @@ -1774,6 +1717,7 @@ s * * **SPI_DEV Constructor** * * @code RF24 radio(22,0); @endcode + * In general, use @code RF24 radio(, *10+); @endcode for proper SPIDEV constructor to address correct spi device at /dev/spidev\.\ * * See http://pi.gadgetoid.com/pinout * @@ -1809,45 +1753,115 @@ s * * * * @page Python Python Wrapper (by https://github.com/mz-fuzzy) - * + * + * @note Both python2 and python3 are supported. + * * @section Install Installation: - * - * Install the boost libraries: (Note: Only the python libraries should be needed, this is just for simplicity) * - * @code sudo apt-get install libboost1.50-all @endcode + * 1. Install the python-dev (or python3-dev) and boost libraries + * @code sudo apt-get install python-dev libboost-python-dev @endcode + * @note For python3 in Raspbian, it's needed to manually link python boost library, like this: + * @code sudo ln -s /usr/lib/arm-linux-gnueabihf/libboost_python-py34.so /usr/lib/arm-linux-gnueabihf/libboost_python3.so @endcode * - * Build the library: + * 2. Install python-setuptools (or python3-setuptools) + * @code sudo apt-get install python-setuptools @endcode * + * 3. Build the library * @code ./setup.py build @endcode + * @note Build takes several minutes on arm-based machines. Machines with RAM <1GB may need to increase amount of swap for build. * - * Install the library - * + * 4. Install the library * @code sudo ./setup.py install @endcode - * - * * See the additional Platform Support pages for information on connecting your hardware
* See the included example for usage information. * - * Running the Example: - * + * 5. Running the Example * Edit the pingpair_dyn.py example to configure the appropriate pins per the above documentation: - * * @code nano pingpair_dyn.py @endcode - * - * Configure another device, Arduino or RPi with the pingpair_dyn example - * + * Configure another device, Arduino or RPi with the pingpair_dyn example
* Run the example - * * @code sudo ./pingpair_dyn.py @endcode * *


* + * @page CrossCompile Linux cross-compilation * + * RF24 library supports cross-compilation. Advantages of cross-compilation: + * - development tools don't have to be installed on target machine + * - resources of target machine don't have to be sufficient for compilation + * - compilation time can be reduced for large projects + * + * Following prerequisites need to be assured: + * - ssh passwordless access to target machine (https://linuxconfig.org/passwordless-ssh) + * - sudo of a remote user without password (http://askubuntu.com/questions/334318/sudoers-file-enable-nopasswd-for-user-all-commands) + * - cross-compilation toolchain for your target machine; for RPi + * @code git clone https://github.com/raspberrypi/tools rpi_tools @endcode + * and cross-compilation tools must be in PATH, for example + * @code export PATH=$PATH:/your/dir/rpi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin @endcode + * + * @section CxSteps Cross compilation steps: + * 1. clone RF24 to a machine for cross-compilation + * @code + * git clone https://github.com/TMRh20/RF24 + * cd RF24 + * @endcode + * 2. configure for cross compilation + * @code ./configure --remote=pi@target_linux_host @endcode + * eventually + * @code ./configure --remote=pi@target_linux_host --driver= @endcode + * 3. build + * @code make @endcode + * 4. (opt) install library to cross-compilation machine into cross-exvironment - important for compilation of examples + * @code sudo make install @endcode + * 5. upload library to target machine + * @code make upload @endcode + * 6. (opt) compile examples + * @code + * cd examples_linux + * make + * @endcode + * 7. (opt) upload examples to target machine + * @code make upload @endcode + * + * @section CxStepsPython Cross comilation steps for python wrapper + * + * Prerequisites: + * - Python setuptools must be installed on both target and cross-compilation machines + * @code sudo pip install setuptools @endcode + * or + * @code sudo apt-get install python-setuptools @endcode + * + * Installation steps: + * 1. Assure having libboost-python-dev library in your cross-compilation environment. Alternatively, you can install it into your target machine and copy /usr and /lib directories to the cross-compilation machine. + * For example + * @code + * mkdir -p rpi_root && rsync -a pi@target_linux_host:/usr :/lib rpi_root + * export CFLAGS="--sysroot=/your/dir/rpi_root -I/your/dir/rpi_root/usr/include/python2.7/" + * @endcode + * + * 2. Build the python wrapper + * @code + * cd pyRF24 + * ./setup.py build --compiler=crossunix + * @endcode + * + * 3. Make the egg package + * @code ./setup.py bdist_egg --plat-name=cross @endcode + * dist/RF24--cross.egg should be created. + * + * 4. Upload it to the target machine and install there: + * @code + * scp dist/RF24-*-cross.egg pi@target_linux_host: + * ssh pi@target_linux_host 'sudo easy_install RF24-*-cross.egg' + * @endcode + * + *


+ * * @page ATXMEGA ATXMEGA * * The RF24 driver can be build as a static library with Atmel Studio 7 in order to be included as any other library in another program for the XMEGA family. * - * Currently only the ATXMEGA D3 family is implemented. + * Currently only the ATXMEGA D3 family is implemented. * * @section Preparation * @@ -1876,7 +1890,7 @@ s * * * @section Usage * - * Add the library to your project!
+ * Add the library to your project!
* In the file where the **main()** is put the following in order to update the millisecond functionality: * * @code @@ -1929,7 +1943,7 @@ s * *
* @section Device_Detection Device Detection * - * 1. The main detection for Linux devices is done in the Makefile, with the includes.h from the proper hardware directory copied to RF24/utility/includes.h
+ * 1. The main detection for Linux devices is done in the configure script, with the includes.h from the proper hardware directory copied to RF24/utility/includes.h
* 2. Secondary detection is completed in RF24_config.h, causing the include.h file to be included for all supported Linux devices
* 3. RF24.h contains the declaration for SPI and GPIO objects 'spi' and 'gpio' to be used for porting-in related functions. *