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
nRF24 · Apr 6, 2024 · c200b7c · c200b7c
1 parent 5d645ae
commit c200b7c
Show file tree

Hide file tree

Showing 11 changed files with 86 additions and 66 deletions.
diff --git 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.
  * <br>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.
  * <br>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.
  * <br>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.
  * <br>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.
  * <br>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.
  * <br>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
@@ -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
@@ -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=<driver> to set a driver explicitly." 1
     fi

diff --git 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
@@ -4,7 +4,7 @@
 
 <!-- markdownlint-disable MD031 -->
 @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
@@ -2,18 +2,14 @@
 
 @tableofcontents
 
-<!-- markdownlint-disable MD031 -->
 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\<a\>.\<b\> is present
 2. Manual Install using SPIDEV:

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -5,7 +5,7 @@
 <!-- markdownlint-disable MD031 -->
 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