Python wrapper¶

Remark

We recommend using the newer pyRF24 package available from pypi because

it is practically drop-in compatible
easier to install or get updates with popular package managers like pip
does not require the C++ libraries to be installed — it uses its own isolated binaries
includes wrappers for RF24, RF24Network, RF24Mesh libraries
includes a new fake BLE implementation
has its own dedicated documentation
is compatible with python’s builtin help()
includes typing stub files for type checking tools like mypy

The only reason that you should need to keep using these older individual python wrappers is if you must to use python v3.6 or older.

You cannot use these individual wrappers in combination with the pyRF24 package.

Python Wrapper Prerequisites¶

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.

Python2¶

sudo apt-get install python-dev libboost-python-dev python-pip

Next, install some up-to-date python packages.

python -m pip install --upgrade pip setuptools

Python3¶

sudo apt-get install python3-dev libboost-python-dev python3-pip

Next, install some up-to-date python3 packages.

python3 -m pip install --upgrade pip setuptools

Installation¶

For python3, setup.py needs a manually created symlink for the boost.python library:

sudo ln -s $(ls /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3*.so | tail -1) /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3.so

Install the library.

This step needs to be executed from the appropriate directory of the cloned RF24* repository:
- navigate to pyRF24 directory in the RF24 cloned repository
- navigate to RPi/pyRF24Network directory in the RF24Network cloned repository
- navigate to pyRF24Mesh directory in the RF24Mesh cloned repository
When in the correct directory, run the following command:
```
python setup.py install
```
or for python3
```
python3 -m pip install -v .
```
See the additional Platform Support pages for information on connecting your hardware.

See the included *.py files in the “examples_linux” folder for usage information.
Running the Example

The python examples location differ for each RF24* resopitories.
- navigate to examples_linux directory in the RF24 cloned repository
- navigate to RPi/pyRF24Network/examples directory in the RF24Network cloned repository
- navigate to examples_RPi directory in the RF24Mesh cloned repository
Navigate to the examples_linux directory
```
cd ../examples_linux
```
Edit the getting_started.py example to configure the appropriate pins per the Linux/RPi General documentation.
```
nano getting_started.py
```
Configure another device, Arduino or RPi with the same example code. It could be C++ or python (see the list of available examples), but we’ll use the same example file on a different device in this tutorial.

Run the example
```
python getting_started.py
```
or for python3
```
python3 getting_started.py
```

Note

The interrupt_configure.py example uses the gpiod library to watch the radio’s IRQ pin.

Note

Only step 2 has to be repeated if installing the python wrappers for RF24Network and RF24Mesh libraries. The prerequisites stated above still apply to each library.

Note

Building/installing takes several minutes on arm-based machines. Machines with RAM less than 1GB may need to increase amount of swap for build. The -v option enables pip’s verbose output to show that the process has not frozen.

Note

Running the python wrappers built with ‘pigpio’ or ‘RPi’ drivers requires sudo permission.

If you are working in a python virtual environment (aka “venv”), then the virtual environment’s python executable must be specified after sudo. Otherwise, sudo may invoke the system-installed python executable which can lead to errors.

Assuming the python virtual environment is located in ~/venv, use the following command:

sudo ~/venv/bin/python getting_started.py

This sudo advice must be observed even while the virtual environment is activated.

See more information about python virtual environments in the python documentation.