From c200b7cc8e13e70a2ae40bed8e4364de35c891d9 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Sat, 6 Apr 2024 00:53:01 -0700 Subject: [PATCH] disable auto-detect driver and default to SPIDEV (#973) in preparation for #971 - affects CMake and configure scripts - adds warnings to docs with reference to #971 - removes docs' note about pigpio needed for IRQ support - fix cross-links in docs (probably a doxygen v1.10.0 difference) * set doxygen favicon * don't override user input about RF24_DRIVER in cmake when not using an env var to set RF24_DRIVER --- RF24.h | 16 ++++++------ cmake/AutoConfig_RF24_DRIVER.cmake | 42 ++++++++++++++++-------------- configure | 5 +++- docs/Doxyfile | 2 ++ docs/cross_compile.md | 2 +- docs/linux_install.md | 37 +++++++++++++++++--------- docs/main_page.md | 14 +++++----- docs/mraa.md | 2 +- docs/python_wrapper.md | 4 +-- docs/rpi_general.md | 2 +- docs/using_cmake.md | 26 +++++++++--------- 11 files changed, 86 insertions(+), 66 deletions(-) diff --git a/RF24.h b/RF24.h index c029c8e85..4505c0281 100644 --- a/RF24.h +++ b/RF24.h @@ -252,7 +252,7 @@ class RF24 * @param spiBus A pointer or reference to an instantiated SPI bus object. * The `_SPI` datatype is a "wrapped" definition that will represent * various SPI implementations based on the specified platform. - * @see Review the [Arduino support page](md_docs_arduino.html). + * @see Review the [Arduino support page](arduino.md). * * @return same result as begin() */ @@ -275,7 +275,7 @@ class RF24 * - For the Arduino Due board, the [Arduino Due extended SPI feature](https://www.arduino.cc/en/Reference/DueExtendedSPI) * is not supported. This means that the Due's pins 4, 10, or 52 are not mandated options (can use any digital output pin) for the radio's CSN pin. * - * @see Review the [Arduino support page](md_docs_arduino.html). + * @see Review the [Arduino support page](arduino.md). * * @return same result as begin() */ @@ -2233,7 +2233,7 @@ class RF24 * * This is a simple example of using the RF24 class on a Raspberry Pi. * - * Remember to install the [Python wrapper](md_docs_python_wrapper.html), then + * Remember to install the [Python wrapper](python_wrapper.md), then * navigate to the "RF24/examples_linux" folder. *
To run this example, enter * @code{.sh}python3 getting_started.py @endcode and follow the prompts. @@ -2249,7 +2249,7 @@ class RF24 * This is a simple example of using the RF24 class on a Raspberry Pi to * transmit and retrieve custom automatic acknowledgment payloads. * - * Remember to install the [Python wrapper](md_docs_python_wrapper.html), then + * Remember to install the [Python wrapper](python_wrapper.md), then * navigate to the "RF24/examples_linux" folder. *
To run this example, enter * @code{.sh}python3 acknowledgement_payloads.py @endcode and follow the prompts. @@ -2268,7 +2268,7 @@ class RF24 * payloads because automatic ACK payloads' data will always be outdated by 1 * transmission. Instead, this example uses a call and response paradigm. * - * Remember to install the [Python wrapper](md_docs_python_wrapper.html), then + * Remember to install the [Python wrapper](python_wrapper.md), then * navigate to the "RF24/examples_linux" folder. *
To run this example, enter * @code{.sh}python3 manual_acknowledgements.py @endcode and follow the prompts. @@ -2284,7 +2284,7 @@ class RF24 * This is a simple example of using the RF24 class on a Raspberry Pi for * streaming multiple payloads. * - * Remember to install the [Python wrapper](md_docs_python_wrapper.html), then + * Remember to install the [Python wrapper](python_wrapper.md), then * navigate to the "RF24/examples_linux" folder. *
To run this example, enter * @code{.sh}python3 streaming_data.py @endcode and follow the prompts. @@ -2300,7 +2300,7 @@ class RF24 * This is a simple example of using the RF24 class on a Raspberry Pi to * detecting (and verifying) the IRQ (interrupt) pin on the nRF24L01. * - * Remember to install the [Python wrapper](md_docs_python_wrapper.html), then + * Remember to install the [Python wrapper](python_wrapper.md), then * navigate to the "RF24/examples_linux" folder. *
To run this example, enter * @code{.sh}python3 interrupt_configure.py @endcode and follow the prompts. @@ -2317,7 +2317,7 @@ class RF24 * using 1 nRF24L01 to receive data from up to 6 other transceivers. This * technique is called "multiceiver" in the datasheet. * - * Remember to install the [Python wrapper](md_docs_python_wrapper.html), then + * Remember to install the [Python wrapper](python_wrapper.md), then * navigate to the "RF24/examples_linux" folder. *
To run this example, enter * @code{.sh}python3 multiceiver_demo.py @endcode and follow the prompts. diff --git a/cmake/AutoConfig_RF24_DRIVER.cmake b/cmake/AutoConfig_RF24_DRIVER.cmake index 6e942caff..88fb7ddea 100644 --- a/cmake/AutoConfig_RF24_DRIVER.cmake +++ b/cmake/AutoConfig_RF24_DRIVER.cmake @@ -26,31 +26,33 @@ else() endif() -if(${RF24_DRIVER} STREQUAL "UNKNOWN") # invokes automatic configuration - if("${SOC}" STREQUAL "BCM2708" OR "${SOC}" STREQUAL "BCM2709" OR "${SOC}" STREQUAL "BCM2835") - set(RF24_DRIVER RPi CACHE STRING "using folder /utility/RPi" FORCE) - elseif(NOT "${LibPIGPIO}" STREQUAL "LibPIGPIO-NOTFOUND") - message(STATUS "Found pigpio library: ${LibPIGPIO}") - set(RF24_DRIVER pigpio CACHE STRING "using folder /utility/pigpio" FORCE) - elseif(NOT "${LibWiringPi}" STREQUAL "LibWiringPi-NOTFOUND") - message(STATUS "Found wiringPi library: ${LibWiringPi}") - set(RF24_DRIVER wiringPi CACHE STRING "using folder /utility/wiringPi" FORCE) - elseif(NOT "${LibLittleWire}" STREQUAL "LibLittleWire-NOTFOUND") - message(STATUS "Found LittleWire library: ${LibLittleWire}") - set(RF24_DRIVER LittleWire CACHE STRING "using folder /utility/LittleWire" FORCE) - elseif(NOT "${LibMRAA}" STREQUAL "LibMRAA-NOTFOUND") - message(STATUS "Found MRAA library: ${LibMRAA}") - set(RF24_DRIVER MRAA CACHE STRING "using folder /utility/MRAA" FORCE) - elseif(SPIDEV_EXISTS) # should be a non-empty string if SPI is enabled - message(STATUS "detected that SPIDEV is enabled: ${SPIDEV_EXISTS}") - set(RF24_DRIVER SPIDEV CACHE STRING "using folder /utility/SPIDEV" FORCE) - endif() -endif() +# if(${RF24_DRIVER} STREQUAL "UNKNOWN") # invokes automatic configuration +# if("${SOC}" STREQUAL "BCM2708" OR "${SOC}" STREQUAL "BCM2709" OR "${SOC}" STREQUAL "BCM2835") +# set(RF24_DRIVER RPi CACHE STRING "using folder /utility/RPi" FORCE) +# elseif(NOT "${LibPIGPIO}" STREQUAL "LibPIGPIO-NOTFOUND") +# message(STATUS "Found pigpio library: ${LibPIGPIO}") +# set(RF24_DRIVER pigpio CACHE STRING "using folder /utility/pigpio" FORCE) +# elseif(NOT "${LibWiringPi}" STREQUAL "LibWiringPi-NOTFOUND") +# message(STATUS "Found wiringPi library: ${LibWiringPi}") +# set(RF24_DRIVER wiringPi CACHE STRING "using folder /utility/wiringPi" FORCE) +# elseif(NOT "${LibLittleWire}" STREQUAL "LibLittleWire-NOTFOUND") +# message(STATUS "Found LittleWire library: ${LibLittleWire}") +# set(RF24_DRIVER LittleWire CACHE STRING "using folder /utility/LittleWire" FORCE) +# elseif(NOT "${LibMRAA}" STREQUAL "LibMRAA-NOTFOUND") +# message(STATUS "Found MRAA library: ${LibMRAA}") +# set(RF24_DRIVER MRAA CACHE STRING "using folder /utility/MRAA" FORCE) +# elseif(SPIDEV_EXISTS) # should be a non-empty string if SPI is enabled +# message(STATUS "detected that SPIDEV is enabled: ${SPIDEV_EXISTS}") +# set(RF24_DRIVER SPIDEV CACHE STRING "using folder /utility/SPIDEV" FORCE) +# endif() +# endif() # override the auto-detect if RF24_DRIVER is defined in an env var if(DEFINED ENV{RF24_DRIVER}) message(STATUS "RF24_DRIVER (set from env var) = $ENV{RF24_DRIVER}") set(RF24_DRIVER $ENV{RF24_DRIVER} CACHE STRING "" FORCE) +elseif(${RF24_DRIVER} STREQUAL "UNKNOWN") + set(RF24_DRIVER SPIDEV CACHE STRING "using folder /utility/SPIDEV" FORCE) endif() message(STATUS "Using driver: ${RF24_DRIVER}") diff --git a/configure b/configure index 418bbb680..78b9c62a8 100755 --- a/configure +++ b/configure @@ -174,6 +174,8 @@ function gcc_cpu_flags { echo ${flags} } +# no longer used. This should be removed when resolving +# https://github.com/nRF24/RF24/issues/971 function detect_driver { if [[ $(execute_check "cat /proc/cpuinfo | grep Hardware | grep 'BCM2708\|BCM2709\|BCM2835'") ]]; then result=RPi @@ -391,7 +393,8 @@ fi # DRIVER detection if [ -z "${DRIVER}" ]; then echo "[SECTION] Detecting DRIVER" - DRIVER=$(detect_driver) + # DRIVER=$(detect_driver) + DRIVER=SPIDEV if [ -z "${DRIVER}" ]; then die "No supported driver detected. Run configure with --driver= to set a driver explicitly." 1 fi diff --git a/docs/Doxyfile b/docs/Doxyfile index de8a00450..0d76981f6 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -15,6 +15,8 @@ # Project related configuration options #--------------------------------------------------------------------------- +PROJECT_ICON = sphinx/_static/new_favicon.ico + # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by # double-quotes, unless you are using Doxywizard) that should identify the # project for which the documentation is generated. This name is used in the diff --git a/docs/cross_compile.md b/docs/cross_compile.md index 9d9bd59c7..f30d394bd 100644 --- a/docs/cross_compile.md +++ b/docs/cross_compile.md @@ -4,7 +4,7 @@ @warning These instructions are no longer recommended because they involve disabling security measures -for the target system. Please try the [instructions using CMake](md_docs_using_cmake.html). +for the target system. Please try the [instructions using CMake](using_cmake.md). RF24 library supports cross-compilation. Advantages of cross-compilation: diff --git a/docs/linux_install.md b/docs/linux_install.md index 790ed5a0f..7ce6d6ff4 100644 --- a/docs/linux_install.md +++ b/docs/linux_install.md @@ -2,18 +2,14 @@ @tableofcontents - Generic Linux devices are supported via SPIDEV, PiGPIO, MRAA, RPi native via BCM2835, or using LittleWire. @note The SPIDEV option should work with most Linux systems supporting spi userspace device. -@note Since wiringPi is no longer maintained or distributed (as of RPi OS 11 bullseye), -pigpio is now required for using the radio's IRQ pin. This applies to RPi, SPIDEV, and pigpio drivers. The MRAA driver may provide its own IRQ implementation. Remember that the RPi OS lite variant does not ship with pigpio installed. - ### Automatic Installation (New) -Using CMake: (See the [instructions using CMake](md_docs_using_cmake.html) for more information and options) +Using CMake: (See the [instructions using CMake](using_cmake.md) for more information and options) 1. Download the install.sh file from [https://github.com/nRF24/.github/blob/main/installer/install.sh](https://github.com/nRF24/.github/blob/main/installer/install.sh) ```shell @@ -27,7 +23,11 @@ Using CMake: (See the [instructions using CMake](md_docs_using_cmake.html) for m ```shell ./install.sh ``` - The script will detect needed dependencies and install what it needs according to the user input. + + @warning + `SPIDEV` is now always selected as the default driver because + all other Linux drivers are being removed in the future. + See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. It will also ask to install a python package named [pyRF24](https://github.com/nRF24/pyRF24). This is not the same as the traditionally provided python wrappers as the pyRF24 package can be @@ -56,9 +56,9 @@ Using CMake: (See the [instructions using CMake](md_docs_using_cmake.html) for m sudo ./gettingstarted ``` -See the [instructions using CMake](md_docs_using_cmake.html) for more information and options +See the [instructions using CMake](using_cmake.md) for more information and options -## Automated Install (Deprecated) +## Automated Install (Deprecated - 32 bit only) **Designed & Tested on RPi** - Defaults to SPIDEV on devices supporting it @@ -75,6 +75,12 @@ See the [instructions using CMake](md_docs_using_cmake.html) for more informatio ```shell ./install.sh ``` + + @warning + `SPIDEV` is now always selected as the default driver because + all other Linux drivers are being removed in the future. + See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. + 5. Run an example from one of the libraries ```shell cd rf24libs/RF24/examples_linux @@ -86,7 +92,7 @@ See the [instructions using CMake](md_docs_using_cmake.html) for more informatio sudo ./gettingstarted ``` -## Manual Install (Deprecated) +## Manual Install (Deprecated - 32 bit only) 1. Install prerequisites if there are any (pigpio, MRAA, LittleWire libraries, setup SPI device etc) @note See the [MRAA](http://iotdk.intel.com/docs/master/mraa/index.html) documentation for more info on installing MRAA @@ -103,13 +109,18 @@ See the [instructions using CMake](md_docs_using_cmake.html) for more informatio ```shell cd RF24 ``` -5. Configure build environment using +5. Configure build environment using the command: ```shell ./configure ``` - script. It auto detectes device and build environment. + It automatically detects device and build environment. + + @warning + `SPIDEV` is now always selected as the default driver because + all other Linux drivers are being removed in the future. + See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. - For overriding autodetections, use command-line switches, see + For overriding automatic detections, use command-line arguments, see ```shell ./configure --help ``` @@ -129,7 +140,7 @@ See the [instructions using CMake](md_docs_using_cmake.html) for more informatio sudo ./gettingstarted ``` -### Build using SPIDEV (Deprecated) +### Build using SPIDEV (Deprecated - 32 bit only) 1. Make sure that spi device support is enabled and /dev/spidev\.\ is present 2. Manual Install using SPIDEV: diff --git a/docs/main_page.md b/docs/main_page.md index cb386f5b2..6da4e811d 100644 --- a/docs/main_page.md +++ b/docs/main_page.md @@ -48,13 +48,13 @@ changes. ## Platform Support Pages -- [Arduino](md_docs_arduino.html) (Uno, Nano, Mega, Due, Galileo, etc) -- [ATTiny](md_docs_attiny.html) -- [Pico SDK support](md_docs_pico_sdk.html) -- [Linux Installation](md_docs_linux_install.html) (or the alternative [instructions using CMake](md_docs_using_cmake.html)), - ([Linux/RPi General](md_docs_rpi_general.html), [MRAA](md_docs_mraa.html) supported boards (Galileo, Edison, etc), LittleWire) -- [Cross-compilation](md_docs_cross_compile.html) for linux devices -- [Python wrapper](md_docs_python_wrapper.html) available for Linux devices +- [Arduino](arduino.md) (Uno, Nano, Mega, Due, Galileo, etc) +- [ATTiny](attiny.md) +- [Pico SDK support](pico_sdk.md) +- [Linux Installation](linux_install.md) (or the alternative [instructions using CMake](using_cmake.md)), + ([Linux/RPi General](rpi_general.md), [MRAA](mraa.md) supported boards (Galileo, Edison, etc), LittleWire) +- [Cross-compilation](cross_compile.md) for linux devices +- [Python wrapper](python_wrapper.md) available for Linux devices ### General µC Pin layout diff --git a/docs/mraa.md b/docs/mraa.md index d13310287..175b7b481 100644 --- a/docs/mraa.md +++ b/docs/mraa.md @@ -39,4 +39,4 @@ MRAA is not included. ``` 3. Install RF24, using MRAA - See [Linux Install instructions](md_docs_linux_install.html) + See [Linux Install instructions](linux_install.md) diff --git a/docs/python_wrapper.md b/docs/python_wrapper.md index 60e73a42c..0b83e92de 100644 --- a/docs/python_wrapper.md +++ b/docs/python_wrapper.md @@ -28,7 +28,7 @@ These instructions work for the RF24, RF24Network, and RF24Mesh libraries, but the C++ source code needs to be built and installed for the corresponding python wrapper(s) to work. -@see Review [installing with CMake](md_docs_using_cmake.html) and [Linux/RPi General](md_docs_rpi_general.html). +@see Review [installing with CMake](using_cmake.md) and [Linux/RPi General](rpi_general.md). @note The interrupt_configure.py example uses the [gpiod library](https://pypi.org/project/gpiod) to watch the radio's IRQ pin. @@ -101,7 +101,7 @@ to each library. ```shell cd ../examples_linux ``` - Edit the getting_started.py example to configure the appropriate pins per the [Linux/RPi General](md_docs_rpi_general.html) documentation. + Edit the getting_started.py example to configure the appropriate pins per the [Linux/RPi General](rpi_general.md) documentation. ```shell nano getting_started.py ``` diff --git a/docs/rpi_general.md b/docs/rpi_general.md index cb6bde505..68b18bcac 100644 --- a/docs/rpi_general.md +++ b/docs/rpi_general.md @@ -26,7 +26,7 @@ sudo raspi-config The default build on Raspberry Pi utilizes the included **BCM2835** driver from [the BCM2835 Library](http://www.airspayce.com/mikem/bcm2835) -1. See [the Linux section for automated installation](md_docs_linux_install.html). +1. See [the Linux section for automated installation](linux_install.md). 2. Manual install: ```shell make diff --git a/docs/using_cmake.md b/docs/using_cmake.md index 20c9585e7..94708a9f8 100644 --- a/docs/using_cmake.md +++ b/docs/using_cmake.md @@ -5,7 +5,7 @@ A more modern approach instead of using hand-crafted _Makefiles_ & _configure_ scripts to build & install software. Please note that these instructions are not needed if you -have already installed the library using [these older instructions](md_docs_linux_install.html) +have already installed the library using [these older instructions](linux_install.md) ## Installing the library @@ -15,7 +15,7 @@ You can install the library in a few different ways. - Installing the library (via a package manager) from a pre-built package is mostly for cross-compiling purposes, but it can be useful for environments that don't have all the build-time dependencies (namely CMake). @warning If you have previously installed the library from source code using the -[the older instructions](md_docs_linux_install.html), then you will need to +[the older instructions](linux_install.md), then you will need to uninstall it manually to avoid runtime conflicts. ```shell sudo rm /usr/local/lib/librf24.* @@ -25,9 +25,6 @@ sudo rm -r /usr/local/include/RF24 The _librf24-bcm.so_ file may not exist if you used CMake to install the library. -@note Since wiringPi is no longer maintained or distributed (as of RPi OS 11 bullseye), -pigpio is now required for using the radio's IRQ pin. This applies to RPi, SPIDEV, and pigpio drivers. The MRAA driver may provide its own IRQ implementation. Remember that the RPi OS lite variant does not ship with pigpio installed. - ### Automatic Installation There is a newer automatic install script that makes use of the CMake approach. @@ -44,7 +41,11 @@ There is a newer automatic install script that makes use of the CMake approach. ```shell ./install.sh ``` - The script will detect needed dependencies and install what it needs according to the user input. + + @warning + `SPIDEV` is now always selected as the default driver because + all other Linux drivers are being removed in the future. + See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. It will also ask to install a python package named [pyRF24](https://github.com/nRF24/pyRF24). This is not the same as the traditionally provided python wrappers as the pyRF24 package can be @@ -75,13 +76,13 @@ There is a newer automatic install script that makes use of the CMake approach. ### Building from source code -1. Install prerequisites if there are any (pigpio, wiringPi, MRAA, LittleWire libraries, setup SPI device etc) +1. Install prerequisites if there are any (PiGPIO, WiringPi, MRAA, LittleWire libraries, and enable the SPI bus(es) in the OS). CMake may need to be installed ```shell sudo apt-get install cmake ``` - @note See the [MRAA documentation](http://iotdk.intel.com/docs/master/mraa/index.html) for more information on installing MRAA + @note See the [MRAA documentation](http://iotdk.intel.com/docs/master/mraa/index.html) for more information on installing MRAA. 2. Make a directory to contain the RF24 library and possibly other RF24\* libraries and enter it ```shell mkdir ~/rf24libs @@ -119,9 +120,10 @@ There is a newer automatic install script that makes use of the CMake approach. Instead of using `SPIDEV` driver (recommended), you can also specify the `RPi`, `wiringPi`, `MRAA`, or `LittleWire` as alternative drivers. - If the `RF24_DRIVER` option is not specified (and it is not set as an environment variable), then - it will be automatically configured based on the detected CPU or installed libraries (which - defaults to `SPIDEV` when auto-detection fails). + @warning + `SPIDEV` is now always selected as the default driver because + all other Linux drivers are being removed in the future. + See [RF24 issue #971](https://github.com/nRF24/RF24/issues/971) for rationale. 6. Build and install the library ```shell make @@ -137,7 +139,7 @@ There is a newer automatic install script that makes use of the CMake approach. ```shell nano gettingstarted.cpp ``` - and edit the pin numbers as directed in the [linux/RPi general documation](md_docs_rpi_general.html). + and edit the pin numbers as directed in the [linux/RPi general documation](rpi_general.md). Create a build directory in the examples_linux directory and navigate to it. ```shell mkdir build