Krolyxon
Commit 3120783

Branches

Tags

Refs →

orion-rf.piolibdepsesp32-s3-n16r8RF24docspython_wrapper.md

138 lines · 5.4 KB · Markdown

Raw Blame History Download
1# Python Wrapper
2
3@tableofcontents
4
5@remark
6@parblock
7We recommend using the newer [pyRF24 package](https://github.com/nRF24/pyRF24)
8[available from pypi](https://pypi.org/project/pyrf24/) because
9
101. it is [practically drop-in compatible](https://nrf24.github.io/pyRF24/#migrating-to-pyrf24)
112. easier to install or get updates with popular package managers like pip
123. does not require the C++ libraries to be installed -- it uses its own isolated binaries
134. includes wrappers for RF24, RF24Network, RF24Mesh libraries
145. includes a new [fake BLE implementation](https://nrf24.github.io/pyRF24/ble_api.html)
156. has its own [dedicated documentation](https://nRF24.github.io/pyRF24)
167. is compatible with python's builtin `help()`
178. includes typing stub files for type checking tools like mypy
18
19The only reason that you should need to keep using these older individual python
20wrappers is if you must use python v3.6 or older.
21
22You **cannot** use these individual wrappers in combination with the pyRF24 package.
23@endparblock
24
25## Python Wrapper Prerequisites
26
27These instructions work for the RF24, RF24Network, and RF24Mesh libraries, but
28the C++ source code needs to be built and installed for the corresponding
29python wrapper(s) to work.
30
31@see Review [installing with CMake](using_cmake.md) and [Linux/RPi General](rpi_general.md).
32
33@note The interrupt_configure.py example uses the
34[gpiod library](https://pypi.org/project/gpiod) to watch the radio's IRQ pin.
35
36> [!warning]
37> Recent updates to pip mandate that users manage a python virtual environment.
38> This is good practice because it avoids the risk that installing a package with pip will
39> mess up a system-installed package.
40>
41> For information about using up a python virtual environment, see the official
42> [instructions using the python standard library `venv`](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
43> (which is a minimized variant of
44> [the `virtualenv` library](https://virtualenv.pypa.io/en/stable/index.html)).
45>
46> There's also a note at the end of these instructions that talks about
47> using `sudo` within a python virtual environment.
48
49### Python2
50
51```shell
52sudo apt-get install python-dev libboost-python-dev python-pip
53```
54
55Next, install some up-to-date python packages.
56
57```shell
58python -m pip install --upgrade pip setuptools
59```
60
61### Python3
62
63```shell
64sudo apt-get install python3-dev libboost-python-dev python3-pip
65```
66
67## Installation
68
69> [!note]
70> If using **older versions of RF24* libraries** with python3,
71> the setup.py script needed a manually created symlink for the boost.python library.
72> ```shell
73> 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
74> ```
75> This is no longer needed with the latest versions of RF24 libraries.
76
771. Install the library.
78
79 This step needs to be executed from the appropriate directory of
80 the cloned RF24* repository:
81 - navigate to *pyRF24* directory in the RF24 cloned repository
82 - navigate to *RPi/pyRF24Network* directory in the RF24Network cloned repository
83 - navigate to *pyRF24Mesh* directory in the RF24Mesh cloned repository
84
85 When in the correct directory, run the following command:
86 ```shell
87 python3 -m pip install -v .
88 ```
89 @note Building/installing takes several minutes on arm-based machines.
90 Machines with RAM less than 1GB may need to increase amount of swap for build.
91 The `-v` option enables pip's verbose output to show that the process has not frozen.
92
93 See the additional [Platform Support pages](pages.html) for information on connecting your hardware.
94
95 See the included [\*.py files in the "examples_linux" folder](examples.html) for usage information.
962. Running the Example
97
98 The python examples location differ for each RF24* repositories.
99 - navigate to *examples_linux* directory in the RF24 cloned repository
100 - navigate to *RPi/pyRF24Network/examples* directory in the RF24Network cloned repository
101 - navigate to *examples_RPi* directory in the RF24Mesh cloned repository
102
103 Navigate to the examples_linux directory
104 ```shell
105 cd ../examples_linux
106 ```
107 Edit the getting_started.py example to configure the appropriate pins per the [Linux/RPi General](rpi_general.md) documentation.
108 ```shell
109 nano getting_started.py
110 ```
111 Configure another device, Arduino or RPi with the same example code. It could be C++ or python (see the [list of available examples](examples.html)), but we'll use the same example file on a different device in this tutorial.
112
113 Run the example
114 ```shell
115 python getting_started.py
116 ```
117 or for python3
118 ```shell
119 python3 getting_started.py
120 ```
121
122 @note
123 @parblock
124 Running the python wrappers built with 'pigpio' or 'RPi' drivers requires `sudo` permission.
125
126 If you are working in a python virtual environment (aka "venv"), then the
127 virtual environment's python executable must be specified after `sudo`. Otherwise,
128 `sudo` may invoke the system-installed python executable which can lead to errors.
129
130 Assuming the python virtual environment is located in `~/venv`, use the following command:
131 ```
132 sudo ~/venv/bin/python getting_started.py
133 ```
134 This `sudo` advice must be observed even while the virtual environment is activated.
135
136 See more information about python virtual environments in the
137 [python documentation](https://docs.python.org/3/library/venv.html).
138 @endparblock