Package: pyrf24
IntroductionThis is the official home of the python wrappers for the RF24 stack. It is meant for Linux-based
SoC boards like the Raspberry Pi. Documentation is hosted athttp://pyrf24.rtfd.io/.PinoutThe nRF24L01’s CE and IRQ pins can be connected to other GPIO pins on the SoC. The MISO, MOSI, SCK
are limited to the corresponding counterparts on the SoC’s SPI bus. The CSN pin is limited to the
chosen SPI bus’s “Chip Select” options (also labeled as “CE” pins on many Raspberry Pi pinout
diagrams). The following table shows the default pins used in all theexamplesfor this package.nRF24L01Raspberry PiGNDGNDVCC3VCEGPIO22CSNGPIO8 (CE0)SCKGPIO11 (SCK)MOSIGPIO10 (MOSI)MISOGPIO9 (MISO)IRQGPIO12The IRQ pin is not typically connected, and it is only used in the interrupt_configure example.WarningIf connecting a nRF24L01+PA+LNA module to the Raspberry Pi, you MUST use a external 3V
power supply because the Raspberry Pi (all models) do not provide enough power for the
nRF24L01+PA+LNA modules.ImportantIt is highly recommended that the nRF24L01’s VCC and GND pins have a parallel
capacitor to stabilize the power supply. Usually 100 microfarad is enough, but the capacitance
ultimately depends on the nature of your power supply’s stability.NoteNotice that RPi.GPIO (for python) is used to manage the GPIO pins on the Raspberry Pi
(exclusively during theinterrupt_configure.pyexample).RPi.GPIO is not required for normal usage (when not using the radio’s IRQ pin).sudoaptinstallpython3-rpi.gpioInstalling from PyPISimply use:python-mpipinstallpyrf24We have distributed binary wheels to pypi.org for easy installation and automated dependency.
These wheels specifically target any Linux platform onaarch64architecture.
If you’re using Raspberry Pi OS (32 bit), then the above command will fetcharmv7lbinary
wheels from the piwheels index (which is already configured for use in the Raspberry Pi OS).NoteIf you’re installing from a Linux machine that is not using an architectureaarch64orarmv7l, then pip may try to build the package from source code.
In this case, you’ll likely need to install some extra build dependencies:sudoaptinstallpython3-devcmakeInstalling from GithubInstalling from source will require CMake and CPython headers:sudoaptinstallpython3-devcmakeTo build this python package locally, you need to have cloned this library’s repository with its submodules.gitclone--recurse-submoduleshttps://github.com/nRF24/pyRF24.gitcdpyRF24python-mpipinstall.-vHintFor consecutive build attempts, it is recommended to delete any previous build artifacts
before attempting to build again.rm-rbuild/dist/NoteThe-vis optional. Here, we use it to show that pip isn’t frozen during the
build process.Installing the package can take a long time, and you might think that pip is frozen
on the step labeled “Building wheel for pyrf24 (pyproject.toml)”. Just wait for about
5 minutes (maybe longer on older/slower variants of Raspberry Pi).Building a wheelBuilding a somewhat portable binary distribution for python packages involves building a
.whl file known as a wheel. This wheel can be used to install the pyrf24 package on systems using the
same version of CPython, CPU architecture, and C standard lib.Because building wheels is not done in an isolated build environment, it is advised that
some build-time dependencies be installed manually to ensure up-to-date stable releases are used.
Execute the following from the root directory of this repo:python-mpipinstall-rrequirements.txtNoteThis step only needs to be done once.Using the same directory that you cloned the pyrf24 library into:python-mpipwheel-wdist.ImportantIt is recommended to purge any previous build artifacts before re-building the package.rm-rbuild/dist/To install a built wheel, simply pass the wheel’s path and file name topip install:python-mpipinstalldist/pyrf24-MAJOR.MINOR.PATCH-cp3X-cp3X-linux_ARCH.whlWhere the following would be replaced accordingly:MAJOR.MINOR.PATCHis the current version of the pyrf24 package.If not building a tagged commit, then the version will describe the commit relative to
the number of commits since the latest tag. For example,0.1.1.post1.dev3is
the third commit (dev3) since the first “post release” (post1) after the
tagged version0.1.1. This adhere’s toPEP440.cp3Xis the version of python used to build the wheel (iecp39for CPython 3.9)
The second occurrence ofcp3Xdescribes the CPython ABI compatibility.ARCHis the architecture type of the CPU. This corresponds to the compiler used.
On Raspberry Pi OS (32 bit), this will bearmv7l.Using a specific RF24 driverBy default, this package is built using the RF24 driver SPIDEV. If you want to build the
package using a different RF24 driver (likeRPi,MRAA,wiringPi, etc), then
it is necessary to use an environment variable containing additional arguments for CMake:exportCMAKE_ARGS="-DRF24_DRIVER=RPi"HintYou can also use this environment variable to enable debug output from different
layers of the RF24 stack. For a list of supported options, look at the script inthis repository’s cmake/using_flags.cmake.The following value will turn on debug output for the RF24Mesh and RF24Network
classes (respectively).exportCMAKE_ARGS="-DMESH_DEBUG=ON -DSERIAL_DEBUG=ON"Then just build and install the package from source as usual.python-mpipinstall.-vDifferences in APIThis package intentionally adheres toPEP8standards as much as possible.
This means that class members’ names use snake casing  (eg.get_dynamic_payload_size())
instead of using the C++ conventional camel casing (eg.getDynamicPayloadSize()). However,
the older python wrappers provided with each C++ library (RF24, RF24Network, & RF24Mesh) had used
camel casing. So, the API provided by this package exposes both snake cased and camel cased
versions of the API. The camel cased API is not documented to avoid duplicate and
complicated documentation.radio.print_details()# documented# can also be invoked asradio.printDetails()# not documentedSome of the C++ functions that do not accept arguments are wrapped as a class property. But, the C++
style functions are still exposed. For example:radio.listen=False# is equivalent toradio.stopListening()# not documentedradio.listen=True# is equivalent toradio.startListening()# not documentedMigrating to pyrf24If you have a project that uses code from the older individually installed wrappers,
then you can use this package as a drop-in replacement. You only need to change the
import statements in your project’s source. Everything from the old individual wrappers
is exposed through thepyrf24package.Using the old individual wrappersUsing the pyrf24 packagefromRF24importRF24,RF24_PA_LOWfrompyrf24importRF24,RF24_PA_LOWfromRF24importRF24fromRF24NetworkimportRF24Network,RF24NetworkHeaderfrompyrf24importRF24,RF24Network,RF24NetworkHeaderfromRF24importRF24fromRF24NetworkimportRF24NetworkfromRF24MeshimportRF24Meshfrompyrf24importRF24,RF24Network,RF24MeshPython Type HintsThis package is designed to only function on Linux devices. But, it is possible to install this
package on non-Linux devices to get the stub files which help auto-completion and type checking
in various development environments.DocumentationEach release has corresponding documentation hosted athttp://pyrf24.rtfd.io/.Before submitting contributions, you should make sure that any documentation changes build
successfully. This can be done locally buton Linux only. The documentation of API requires
this package (& all its latest changes) be installed.This package’s documentation is built with the python package Sphinx and the sphinx-immaterial theme.
It also uses the dot tool provided by the graphviz software to generate graphs.Install Graphvizsudoapt-getinstallgraphvizInstalling Sphinx necessitiesNoteIf you installed sphinx usingapt, then it is likely out-of-date and will override any virtual
python environments installation of Sphinx. Simply uninstall sphinx (usingapt) will remedy
this problem.python-mpipinstall-rdocs/requirements.txtImportantIf pip outputs a warning about yourpath/to/Python/Python3x/Scriptsfolder not
added to your OS environment variablePATH, then you will likely get an error message likesphinx-buildcommand not foundwhen building the documentation. For more information on
installing sphinx, see theofficial Sphinx install instructions.WarningThis documentation’s theme requires Sphinx v4.0+. So, it is not recommended to install
sphinx fromapton Linux because the version distributed with the OS’s PPA repository
may not be the most recent version of Sphinx.Building the DocumentationTo build the documentation locally, the pyrf24 package needs to be installed first. Then run:cddocssphinx-build-E-W._buildThedocs/_buildfolder should now contain the html files that would be hosted on deployment.
Direct your internet browser to the html files in this folder to make sure your changes have been
rendered correctly.NoteThe flags-Eand-Wwill ensure the docs fail to build on any error or warning
(just like it does when deploying the docs online).