update python wrapper/examples/doc (#967)

- expose selected `RF24_DRIVER` in the python wrapper (for programmatically specifying the right pins) - update for the python examples - interrupt_configure.py usees gpiod instead of RPi.GPIO - removed argparse from examples for simplicity - use the appropriate pin numbers for the selected `RF24_DRIVER` - revised the python wrapper's install doc
nRF24 · Mar 26, 2024 · 7441eef · 7441eef
1 parent a6eae52
commit 7441eef
Show file tree

Hide file tree

Showing 21 changed files with 603 additions and 608 deletions.
diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml
@@ -40,4 +40,5 @@ jobs:
     uses: nRF24/.github/.github/workflows/build_docs.yaml@main
     with:
       deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }}
+      doxygen-version: '1.10.0'
     secrets: inherit
diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -332,14 +332,15 @@ HTML_EXTRA_STYLESHEET  = doxygen-custom.css
 
 HTML_COLORSTYLE = TOGGLE
 
-# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
-# page will contain the date and time when the page was generated. Setting this
-# to YES can help to show when doxygen was last run and thus if the
-# documentation is up to date.
+# If the TIMESTAMP tag is set different from NO then each generated page will contain
+# the date or date and time when the page was generated. Setting this to NO can help
+# when comparing the output of multiple runs.
+#
+# Possible values are: YES, NO, DATETIME and DATE.
+#
 # The default value is: NO.
-# This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_TIMESTAMP         = YES
+TIMESTAMP         = DATE
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that

diff --git a/docs/doxygen-custom.css b/docs/doxygen-custom.css
@@ -1,3 +1,107 @@
 table.markdownTable th {
   color: unset;
 }
+
+/* overrides from default CSSS for some admonitions */
+dl.note, dl.remark,
+dl.warning, dl.attention {
+  color: unset;
+}
+dl.remark {
+	background: var(--remark-color-bg);
+	border-left: 8px solid var(--remark-color-hl);
+}
+dl.remark dt {
+	color: var(--remark-color-hl);
+}
+
+/* special rules to accent `/see` or `/sa` command output */
+dl.see {
+	background: var(--seealso-color-bg);
+	border-left: 8px solid var(--seealso-color-hl);
+}
+dl.see dt {
+	color: var(--seealso-color-hl);
+}
+dl.see {
+  padding: 10px;
+	margin: 10px 0px;
+	overflow: hidden;
+	margin-left: 0;
+	border-radius: 4px;
+}
+
+/* admonition icons */
+dl.note dt::before {
+  background-color: var(--note-color-hl);
+  mask-image: var(--note-icon);
+}
+dl.see dt::before {
+  background-color: var(--seealso-color-hl);
+  mask-image: var(--seealso-icon);
+}
+dl.remark dt::before {
+  background-color: var(--remark-color-hl);
+  mask-image: var(--remark-icon);
+}
+dl.warning dt::before {
+  background-color: var(--warning-color-hl);
+  mask-image: var(--warning-icon);
+}
+dl.deprecated dt::before {
+  background-color: var(--deprecated-color-hl);
+  mask-image: var(--deprecated-icon);
+}
+dl.note dt::before,
+dl.see dt::before,
+dl.warning dt::before,
+dl.remark dt::before,
+dl.deprecated dt::before {
+	vertical-align: middle;
+	background-repeat: no-repeat;
+	content: "";
+	display: inline-block;
+	height: 2em;
+	width: 2em;
+  margin-right: 0.25rem;
+}
+dl.note dt,
+dl.see dt,
+dl.warning dt,
+dl.remark dt,
+dl.deprecated dt {
+  margin-top: -0.35em;
+  margin-bottom: 0.5em;
+}
+
+/* icon SVG data */
+*:root {
+  --note-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M200-200h57l391-391-57-57-391 391v57Zm-80 80v-170l528-527q12-11 26.5-17t30.5-6q16 0 31 6t26 18l55 56q12 11 17.5 26t5.5 30q0 16-5.5 30.5T817-647L290-120H120Zm640-584-56-56 56 56Zm-141 85-28-29 57 57-29-28Z"/></svg>');
+  --seealso-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-320q75 0 127.5-52.5T660-500q0-75-52.5-127.5T480-680q-75 0-127.5 52.5T300-500q0 75 52.5 127.5T480-320Zm0-72q-45 0-76.5-31.5T372-500q0-45 31.5-76.5T480-608q45 0 76.5 31.5T588-500q0 45-31.5 76.5T480-392Zm0 192q-146 0-266-81.5T40-500q54-137 174-218.5T480-800q146 0 266 81.5T920-500q-54 137-174 218.5T480-200Zm0-300Zm0 220q113 0 207.5-59.5T832-500q-50-101-144.5-160.5T480-720q-113 0-207.5 59.5T128-500q50 101 144.5 160.5T480-280Z"/></svg>');
+  --warning-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="m40-120 440-760 440 760H40Zm138-80h604L480-720 178-200Zm302-40q17 0 28.5-11.5T520-280q0-17-11.5-28.5T480-320q-17 0-28.5 11.5T440-280q0 17 11.5 28.5T480-240Zm-40-120h80v-200h-80v200Zm40-100Z"/></svg>');
+  --remark-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M382-240 154-468l57-57 171 171 367-367 57 57-424 424Z"/></svg>');
+  --deprecated-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M280-120q-33 0-56.5-23.5T200-200v-520h-40v-80h200v-40h240v40h200v80h-40v520q0 33-23.5 56.5T680-120H280Zm400-600H280v520h400v-520ZM360-280h80v-360h-80v360Zm160 0h80v-360h-80v360ZM280-720v520-520Z"/></svg>');
+}
+
+/* color overrides */
+html {
+  /* light theme CSS variables */
+  --note-color-bg: hsla(47.6, 77.3%, 91.4%, 65%);
+  --warning-color-bg: hsla(6.8, 75.9%, 88.6%, 65%);
+  --deprecated-color-bg: hsla(205.7, 22.6%, 93.9%, 65%);
+  --seealso-color-bg: hsla(215, 76%, 89%, 65%);
+  --seealso-color-hl: hsl(215, 98%, 48%);
+  --remark-color-bg: hsla(133, 75%, 89%, 65%);
+  --remark-color-hl: hsl(133, 98.9%, 35.3%);
+}
+
+html.dark-mode {
+  /* dark theme CSS variables */
+  --note-color-bg: hsla(45.8, 87.3%, 12.4%, 65%);
+  --warning-color-bg: hsla(5.2, 33.3%, 13.5%, 65%);
+  --deprecated-color-bg: hsla(221.5, 12.4%, 20.6%, 65%);
+  --seealso-color-bg: hsla(215, 33%, 14%, 0.65);
+  --seealso-color-hl: hsl(215, 98%, 48%);
+  --remark-color-bg: hsla(133, 32%, 14%, 65%);
+  --remark-color-hl: hsl(133, 98%, 48%);
+}
diff --git a/docs/python_wrapper.md b/docs/python_wrapper.md
@@ -2,22 +2,41 @@
 
 @tableofcontents
 
-<!-- markdownlint-disable MD031 -->
-By [mz-fuzzy](https://github.com/mz-fuzzy)
+@remark
+@parblock
+We recommend using the newer [pyRF24 package](https://github.com/nRF24/pyRF24)
+[available from pypi](https://pypi.org/project/pyrf24/) because
+
+1. it is [practically drop-in compatible](https://nrf24.github.io/pyRF24/#migrating-to-pyrf24)
+2. easier to install or get updates with popular package managers like pip
+3. does not require the C++ libraries to be installed -- it uses its own isolated binaries
+4. includes wrappers for RF24, RF24Network, RF24Mesh libraries
+5. includes a new [fake BLE implementation](https://nrf24.github.io/pyRF24/ble_api.html)
+6. has its own [dedicated documentation](https://nRF24.github.io/pyRF24)
+7. is compatible with python's builtin `help()`
+8. 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.
+@endparblock
 
 ## Python Wrapper Prerequisites
 
-### RF24
+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.
 
-The RF24 lib needs to be built in C++ & installed for the python wrapper to wrap it.
+@see Review [installing with CMake](md_docs_using_cmake.html) and [Linux/RPi General](md_docs_rpi_general.html).
 
-See [Linux Installation](md_docs_linux_install.html) (or [installing with CMake](md_docs_using_cmake.html)
-alternatively) and [Linux/RPi General](md_docs_rpi_general.html)
+@note The interrupt_configure.py example uses the
+[gpiod library](https://pypi.org/project/gpiod) to watch the radio's IRQ pin.
 
 ### Python2
 
 ```shell
-sudo apt-get install python-dev libboost-python-dev python-pip python-rpi.gpio
+sudo apt-get install python-dev libboost-python-dev python-pip
 ```
 
 Next, install some up-to-date python packages.
@@ -29,7 +48,7 @@ python -m pip install --upgrade pip setuptools
 ### Python3
 
 ```shell
-sudo apt-get install python3-dev libboost-python-dev python3-pip python3-rpi.gpio
+sudo apt-get install python3-dev libboost-python-dev python3-pip
 ```
 
 Next, install some up-to-date python3 packages.
@@ -40,43 +59,38 @@ python3 -m pip install --upgrade pip setuptools
 
 ## Installation
 
-@note Steps 2 and 3 have to be repeated if installing the python wrappers for
+@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.
 
 1. For python3, setup.py needs a manually created symlink for the boost.python library:
    ```shell
    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
    ```
-2. Build the library.
+2. Install the library.
 
-   This step and the next step need to be executed from the appropriate directory of
+   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:
    ```shell
-   ./setup.py build
+   python setup.py install
    ```
    or for python3
    ```shell
-   python3 setup.py build
-   ```
-   @note Build takes several minutes on arm-based machines. Machines with RAM less than 1GB may need to increase amount of swap for build.
-3. Install the library
-   ```shell
-   sudo ./setup.py install
-   ```
-   or for python3
-   ```shell
-   sudo python3 setup.py install
+   python3 -m pip install -v .
    ```
+   @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.
+
    See the additional [Platform Support pages](pages.html) for information on connecting your hardware.
 
    See the included [\*.py files in the "examples_linux" folder](examples.html) for usage information.
-4. Running the Example
+3. Running the Example
 
    The python examples location differ for each RF24* resopitories.
    - navigate to *examples_linux* directory in the RF24 cloned repository
@@ -95,9 +109,27 @@ to each library.
 
    Run the example
    ```shell
-   sudo python getting_started.py
+   python getting_started.py
    ```
    or for python3
    ```shell
-   sudo python3 getting_started.py
+   python3 getting_started.py
    ```
+
+   @note
+   @parblock
+   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](https://docs.python.org/3/library/venv.html).
+   @endparblock
diff --git a/examples_linux/acknowledgementPayloads.cpp b/examples_linux/acknowledgementPayloads.cpp
@@ -36,7 +36,7 @@ using namespace std;
 RF24 radio(CE_PIN, CSN_PIN);
 /****************** Linux (BBB,x86,etc) ***********************/
 // See http://nRF24.github.io/RF24/pages.html for more information on usage
-// See http://iotdk.intel.com/docs/master/mraa/ for more information on MRAA
+// See https://github.com/eclipse/mraa/ for more information on MRAA
 // See https://www.kernel.org/doc/Documentation/spi/spidev for more information on SPIDEV
 
 // For this example, we'll be using a payload containing