Expose old open pipe funcs (#12)

* expose deprecated open*ingPipe(uint64_t)

   - change wrapper functions that take buffers from
     py::object args into py::buffer args.
   - make RF24NetworkWrapper c'tor explicitly
     cast the _radio arg as a RF24 obj.
* remove musllinux wheels from releases
* doc updates
* include bdist wheels for Linux x86_64 on release
* revise README
* remove scikit-build from build deps
* upgrade setuptools req to v61+
* augment prompt in multicieiver_demo
* init ReadTheDocs config
* update CI workflow and stubs

.github/workflows/build.yml

@@ -1,6 +1,10 @@
 name: Build CI
 
-on: [pull_request, push, workflow_dispatch]
+on: 
+  pull_request:
+    types: [opened, reopened]
+  push:
+  workflow_dispatch:
 
 jobs:
   test:
@@ -21,8 +25,21 @@ jobs:
         # cmake ships with the ubuntu-latest runner
         run: |
           sudo apt-get install python3-dev graphviz
-          python3 -m pip install --upgrade pip pylint mypy
-          python3 -m pip install -r docs/requirements.txt -r requirements.txt
+          python3 -m pip install -r docs/requirements.txt -r requirements.txt -r requirements-dev.txt
+
+      - name: Run cpp-linter as a py pkg
+        id: linter
+        run: |
+          cpp-linter \
+          --version=12 \
+          --style=file \
+          --tidy-checks='-*' \
+          --files-changed-only='false' \
+          --ignore='!src|'
+
+      - name: C++ Linter checks failed?
+        if: steps.linter.outputs.checks-failed > 0
+        run: exit 1
 
       - name: Build package for docs extraction and linting examples
         run: |
@@ -50,8 +67,7 @@ jobs:
           path: ${{ github.workspace }}/docs/_build/html
 
       - name: upload to github pages
-        # only publish doc changes from main branch
-        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        if: github.event_name !='pull_request'
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -63,22 +79,7 @@ jobs:
           name: "pyRF24_pkg_dist"
           path: ${{ github.workspace }}/dist
 
-      - name: Create sdist for testPyPi
-        # Doing this again to ensure a fresh build env.
-        # We don't need to upload a bdist as we can check that locally, but
-        # sdist is used by the piwheels project to create a bdist for RPi OS
-        run: |
-          rm -r dist/ _skbuild
-          python3 setup.py sdist
-
       - name: Validate distribution
         run: |
           python3 -m pip install twine
           python3 -m twine check dist/*
-
-      - name: upload to test PyPi
-        if: github.event_name == 'push' && github.repository == 'nRF24/pyRF24' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.test_pypi_token }}
-        run: python3 -m twine upload -r testpypi dist/*

.github/workflows/release.yml

@@ -35,15 +35,15 @@ jobs:
       - name: Build wheels with cibuildwheels
         uses: pypa/[email protected]
         env:
-          CIBW_ARCHS_LINUX: aarch64
-          CIBW_SKIP: cp36* pp* cp311*
+          CIBW_ARCHS_LINUX: aarch64 native
+          CIBW_SKIP: cp36* pp* cp311* *musllinux*
 
       - name: Move cross-compiled wheels to dist folder
         run: |
           mkdir -p dist
           mv ./wheelhouse/*.whl ${{ github.workspace }}/dist/
 
-      - name: build binary distributable wheel
+      - name: build source distributable wheel
         # sdist for non-supprted platforms will serve as a stub lib install
         run: python setup.py sdist
 
@@ -53,6 +53,13 @@ jobs:
           name: "pyRF24_pkg_dist"
           path: ${{ github.workspace }}/dist
 
+      - name: Publish package (to TestPyPI)
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_TOKEN }}
+        run: twine upload --repository testpypi dist/*
+
       - name: Publish to PyPi
         # only upload distributions to PyPi when triggered by a published release
         if: github.event_name == 'release'

.gitignore

@@ -24,6 +24,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+wheelhouse/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+submodules:
+  include: all
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  apt_packages:
+    - python3-dev
+    - graphviz
+    - cmake
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt
+    - requirements: requirements.txt

CMakeLists.txt

@@ -14,7 +14,7 @@ add_subdirectory(RF24/utility) # configure the RF24_DRIVER
 
 ################################# RF24 #############################
 
-pybind11_add_module(rf24 src/pyrf24/pyRF24.cpp)
+pybind11_add_module(rf24 src/pyRF24.cpp)
 target_include_directories(rf24 PUBLIC
     RF24
     RF24/utility
@@ -31,7 +31,7 @@ apply_flags(rf24)
 
 ################################# RF24NETWORK #############################
 
-pybind11_add_module(rf24_network src/pyrf24/pyRF24Network.cpp)
+pybind11_add_module(rf24_network src/pyRF24Network.cpp)
 target_include_directories(rf24_network PUBLIC
     RF24
     RF24Network
@@ -55,7 +55,7 @@ apply_flags(rf24_network)
 
 ################################# RF24MESH #############################
 
-pybind11_add_module(rf24_mesh src/pyrf24/pyRF24Mesh.cpp)
+pybind11_add_module(rf24_mesh src/pyRF24Mesh.cpp)
 target_include_directories(rf24_mesh PUBLIC
     RF24
     RF24Network

MANIFEST.in

@@ -1,10 +1,13 @@
 recursive-include RF24* *
 recursive-include cmake *
-recursive-include src/pyrf24 *.cpp *.typed
+recursive-include src *.cpp *.typed
 recursive-include pybind11 *
 recursive-exclude */.github *
 recursive-exclude */docs *
 recursive-exclude */examples* *
+recursive-exclude .github *
+recursive-exclude docs *
+recursive-exclude examples* *
 recursive-exclude */images *
 recursive-exclude */tests *
 recursive-exclude */build *

README.rst

@@ -1,3 +1,16 @@
+.. image:: https://img.shields.io/piwheels/v/pyrf24?color=informational
+    :target: https://www.piwheels.org/project/pyrf24/
+    :alt: piwheels
+.. image:: https://img.shields.io/readthedocs/pyrf24?label=ReadTheDocs&logo=readthedocs&logoColor=white
+    :target: https://pyrf24.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+.. image:: https://static.pepy.tech/personalized-badge/pyrf24?period=total&units=none&left_color=grey&right_color=blue&left_text=PyPI%20Downloads
+    :target: https://pepy.tech/project/pyrf24
+    :alt: PyPI Downloads
+.. image:: https://github.com/nRF24/pyRF24/actions/workflows/build.yml/badge.svg
+    :target: https://github.com/nRF24/pyRF24/actions/workflows/build.yml
+    :alt: Build CI
+
 Introduction
 ============
 
@@ -48,7 +61,30 @@ The IRQ pin is not typically connected, and it is only used in the interrupt_con
 
         sudo apt install python3-rpi.gpio
 
-Installing from Source
+Installing from PyPI
+~~~~~~~~~~~~~~~~~~~~
+
+Simply use:
+
+.. code-block:: python
+
+    python -m pip install pyrf24
+
+We have distributed binary wheels to pypi.org for easy installation and automated dependency.
+These wheels specifically target any Linux platform on ``aarch64`` architecture.
+If you're using Raspberry Pi OS (32 bit), then the above command will fetch ``armv7l`` binary
+wheels from the piwheels index (which is already configured for use in the Raspberry Pi OS).
+
+.. note::
+    If you're installing from a Linux machine that is not using an architecture ``aarch64``
+    or ``armv7l``, then pip may try to build the package from source code.
+    In this case, you'll likely need to install some extra build dependencies:
+
+    .. code-block:: bash
+
+        sudo apt install python3-dev cmake
+
+Installing from Github
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Installing from source will require CMake and CPython headers:
@@ -71,7 +107,7 @@ To build this python package locally, you need to have cloned this library's rep
 
     .. code-block:: bash
 
-        rm -r _skbuild/ dist/
+        rm -r build/ dist/
 
 .. note::
     The ``-v`` is optional. Here, we use it to show that pip isn't frozen during the
@@ -81,19 +117,6 @@ To build this python package locally, you need to have cloned this library's rep
     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).
 
-Using a specific RF24 driver
-----------------------------
-
-If you want to build the package using a different RF24 driver (like MRAA, RPi, wiringPi, etc), then
-it is appropriate to pass an additional argument to the install command:
-
-.. note::
-    This approach cannot be done with the ``pip install .`` command.
-
-.. code-block:: bash
-
-    python setup.py bdist_wheel -DRF24_DRIVER=RPi
-
 Building a wheel
 -----------------
 
@@ -109,19 +132,22 @@ same version of CPython, CPU architecture, and C standard lib.
 
        python -m pip install -r requirements.txt
 
+   .. note::
+       This step only needs to be done once.
+
 2. Using the same directory that you cloned the pyrf24 library into:
 
    .. code-block:: bash
 
-       python setup.py bdist_wheel
+       python -m pip wheel -w dist .
 
 
    .. important::
        It is recommended to purge any previous build artifacts before re-building the package.
 
        .. code-block:: bash
 
-           rm -r _skbuild/ dist/
+           rm -r build/ dist/
 
 3. To install a built wheel, simply pass the wheel's path and file name to ``pip install``:
 
@@ -132,7 +158,7 @@ same version of CPython, CPU architecture, and C standard lib.
    Where the following would be replaced accordingly:
 
    - ``MAJOR.MINOR.PATCH`` is 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.dev3`` is
        the third commit (``dev3``) since the first "post release" (``post1``) after the
@@ -142,6 +168,35 @@ same version of CPython, CPU architecture, and C standard lib.
    - ``ARCH`` is the architecture type of the CPU. This corresponds to the compiler used.
      On Raspberry Pi OS (32 bit), this will be ``armv7l``.
 
+Using a specific RF24 driver
+----------------------------
+
+By default, this package is built using the RF24 driver SPIDEV. If you want to build the
+package using a different RF24 driver (like ``RPi``, ``MRAA``, ``wiringPi``, etc), then
+it is necessary to use an environment variable containing additional arguments for CMake:
+
+.. code-block:: bash
+
+    export CMAKE_ARGS="-DRF4_DRIVER=RPi"
+
+.. hint::
+    You 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 in
+    `this repository's cmake/using_flags.cmake <https://github.com/nRF24/pyRF24/blob/main/cmake/using_flags.cmake>`_.
+
+    The following value will turn on debug output for the RF24Mesh and RF24Network
+    classes (respectively).
+
+    .. code-block:: bash
+
+        export CMAKE_ARGS="-DMESH_DEBUG=ON -DSERIAL_DEBUG=ON"
+
+Then just build and install the package from source as usual.
+
+.. code-block:: bash
+
+    python -m pip install . -v
+
 Differences in API
 ~~~~~~~~~~~~~~~~~~
 
@@ -172,6 +227,41 @@ style functions are still exposed. For example:
     # is equivalent to
     radio.startListening()  # not documented
 
+Migrating to pyrf24
+-------------------
+
+If 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 the ``pyrf24`` package.
+
+.. list-table::
+    :header-rows: 1
+
+    * - Using the old individual wrappers
+      - Using the pyrf24 package
+    * - .. code-block:: python
+
+            from RF24 import RF24, RF24_PA_LOW
+      - .. code-block:: python
+
+            from pyrf24 import RF24, RF24_PA_LOW
+    * - .. code-block:: python
+
+            from RF24 import RF24
+            from RF24Network import RF24Network, RF24NetworkHeader
+      - .. code-block:: python
+
+            from pyrf24 import RF24, RF24Network, RF24NetworkHeader
+    * - .. code-block:: python
+
+            from RF24 import RF24
+            from RF24Network import RF24Network
+            from RF24Mesh import RF24Mesh
+      - .. code-block:: python
+
+            from pyrf24 import RF24, RF24Network, RF24Mesh
+
 Python Type Hints
 -----------------