Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

disable auto-detect driver and default to SPIDEV #973

Merged
merged 4 commits into from
Apr 6, 2024
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions RF24.h
Original file line number Diff line number Diff line change
Expand Up @@ -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()
*/
Expand All @@ -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()
*/
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down
42 changes: 22 additions & 20 deletions cmake/AutoConfig_RF24_DRIVER.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -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}")
5 changes: 4 additions & 1 deletion configure
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/cross_compile.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
37 changes: 24 additions & 13 deletions docs/linux_install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
```
Expand All @@ -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:
Expand Down
14 changes: 7 additions & 7 deletions docs/main_page.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.html) (or the alternative [instructions using CMake](using_cmake.md)),
([Linux/RPi General](rpi_general.html), [MRAA](mraa.md) supported boards (Galileo, Edison, etc), LittleWire)
2bndy5 marked this conversation as resolved.
Show resolved Hide resolved
- [Cross-compilation](cross_compile.md) for linux devices
- [Python wrapper](python_wrapper.md) available for Linux devices

### General µC Pin layout

Expand Down
2 changes: 1 addition & 1 deletion docs/mraa.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
4 changes: 2 additions & 2 deletions docs/python_wrapper.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.html) and [Linux/RPi General](rpi_general.md).
2bndy5 marked this conversation as resolved.
Show resolved Hide resolved

@note The interrupt_configure.py example uses the
[gpiod library](https://pypi.org/project/gpiod) to watch the radio's IRQ pin.
Expand Down Expand Up @@ -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
```
Expand Down
2 changes: 1 addition & 1 deletion docs/rpi_general.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
26 changes: 14 additions & 12 deletions docs/using_cmake.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.*
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down