Bump the rf24-submodules group with 2 updates (#100)

* Bump the rf24-submodules group with 2 updates Bumps the rf24-submodules group with 2 updates: [RF24](https://github.com/nRF24/RF24) and [RF24Network](https://github.com/nRF24/RF24Network). Updates `RF24` from `ce9bbb8` to `6f3da43` - [Release notes](https://github.com/nRF24/RF24/releases) - [Commits](nRF24/RF24@ce9bbb8...6f3da43) Updates `RF24Network` from `551461f` to `731a368` - [Release notes](https://github.com/nRF24/RF24Network/releases) - [Commits](nRF24/RF24Network@551461f...731a368) --- updated-dependencies: - dependency-name: RF24 dependency-type: direct:production dependency-group: rf24-submodules - dependency-name: RF24Network dependency-type: direct:production dependency-group: rf24-submodules ... Signed-off-by: dependabot[bot] <support@github.com> * add new enum about FIFO state Includes various typing fixes and spelling corrections in examples. Updated docs with deprecation admonitions about deprecated parameters. Renamed requirements-build.txt as these dependencies are only needed to build the package and are already specified in pyproject.toml. * use `ruff format --check` in CI --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Brendan <2bndy5@gmail.com>
nRF24 · Jan 31, 2025 · 3da148e · 3da148e
1 parent 5d946da
commit 3da148e
Show file tree

Hide file tree

Showing 17 changed files with 106 additions and 48 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -26,7 +26,7 @@ jobs:
         # cmake ships with the ubuntu-latest runner
         run: |
           sudo apt-get install python3-dev
-          python3 -m pip install -r docs/requirements.txt -r requirements.txt -r requirements-dev.txt
+          python3 -m pip install -r docs/requirements.txt -r requirements-build.txt -r requirements-dev.txt
 
       - name: Run cpp-linter as a py pkg
         env:
@@ -51,7 +51,7 @@ jobs:
       - name: Build package for docs extraction and linting examples
         run: |
           python -m pip install build
-          python -m build 
+          python -m build
           python -m pip install dist/pyrf24-*.whl
 
       - name: check python typing
@@ -61,7 +61,7 @@ jobs:
         run: ruff check examples/*.py src/pyrf24/*.py* setup.py docs/conf.py
 
       - name: format python sources
-        run: ruff format examples/*.py src/pyrf24/*.py* setup.py docs/conf.py
+        run: ruff format --check examples/*.py src/pyrf24/*.py* setup.py docs/conf.py
 
       - name: Get doc dependencies
         run: |-

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -31,7 +31,7 @@ jobs:
         run: |
           sudo apt install python3-dev
           python3 -m pip install --upgrade pip
-          python3 -m pip install -r requirements.txt
+          python3 -m pip install -r requirements-build.txt
 
       - name: Set up QEMU
         if: matrix.platform != 'native'

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -27,4 +27,3 @@ python:
     - method: pip
       path: .
     - requirements: docs/requirements.txt
-    - requirements: requirements.txt
diff --git a/README.rst b/README.rst
@@ -129,13 +129,13 @@ Building a somewhat portable binary distribution for python packages involves bu
 .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.
 
-1. Because building wheels is not done in an isolated build environment, it is advised that
+1. If 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:
 
    .. code-block:: bash
 
-       python -m pip install -r requirements.txt
+       python -m pip install -r requirements-build.txt
 
    .. note::
        This step only needs to be done once.

diff --git a/RF24 b/RF24
diff --git a/RF24Network b/RF24Network
diff --git a/docs/rf24_api.rst b/docs/rf24_api.rst
@@ -30,6 +30,9 @@ Enum classes
 .. autoclass:: pyrf24.rf24_pa_dbm_e
     :members: RF24_PA_MIN, RF24_PA_LOW, RF24_PA_HIGH, RF24_PA_MAX
 
+.. autoclass:: pyrf24.rf24_fifo_state_e
+    :members: RF24_FIFO_OCCUPIED, RF24_FIFO_EMPTY, RF24_FIFO_FULL, RF24_FIFO_INVALID
+
 RF24 class
 ----------
 

diff --git a/examples/acknowledgement_payloads.py b/examples/acknowledgement_payloads.py
@@ -88,8 +88,8 @@ def master(count: int = 5):  # count = 5 will only transmit 5 packets
             )
             if radio.available():
                 # print the received ACK that was automatically sent
-                result = radio.read(radio.get_dynamic_payload_size())
-                print(f" Received: {result[:6].decode('utf-8')}{result[7:8][0]}")
+                payload = radio.read(radio.get_dynamic_payload_size())
+                print(f" Received: {payload[:6].decode('utf-8')}{payload[7:8][0]}")
                 counter[0] += 1  # increment payload counter
             else:
                 print(" Received an empty ACK packet")

diff --git a/examples/fake_ble_test.py b/examples/fake_ble_test.py
@@ -93,7 +93,7 @@ def master(count=50):
 
 # create an object for manipulating temperature measurements
 temperature_service = TemperatureServiceData()
-# temperature's float data has up to 2 decimal places of percision
+# temperature's float data has up to 2 decimal places of precision
 temperature_service.data = 42.0
 
 

diff --git a/examples/interrupt_configure.py b/examples/interrupt_configure.py
@@ -6,11 +6,11 @@
 """
 
 import time
-from pyrf24 import RF24, RF24_PA_LOW, RF24_DRIVER
+from pyrf24 import RF24, RF24_PA_LOW, RF24_DRIVER, RF24_FIFO_FULL
 
 try:
-    import gpiod
-    from gpiod.line import Edge
+    import gpiod  # type: ignore[import-untyped]
+    from gpiod.line import Edge  # type: ignore[import-untyped]
 except ImportError as exc:
     raise ImportError(
         "This script requires gpiod installed for observing the IRQ pin. Please run\n"
@@ -192,8 +192,8 @@ def slave(timeout=6):  # will listen for 6 seconds before timing out
     radio.write_ack_payload(1, ack_payloads[1])
     radio.write_ack_payload(1, ack_payloads[2])
     radio.listen = True  # start listening & clear irq_dr flag
-    start_timer = time.monotonic()  # start timer now
-    while not radio.is_fifo(False, False) and time.monotonic() - start_timer < timeout:
+    end_time = time.monotonic() + timeout  # start timer now
+    while radio.is_fifo(False) != RF24_FIFO_FULL and time.monotonic() < end_time:
         # if RX FIFO is not full and timeout is not reached, then keep waiting
         pass
     time.sleep(0.5)  # wait for last ACK payload to transmit

diff --git a/examples/multiceiver_demo.py b/examples/multiceiver_demo.py
@@ -85,7 +85,7 @@ def master(node_number: int = 0, count: int = 6):
         if report:
             print(
                 f"Transmission of payloadID {counter} as node {node_number}",
-                f"successfull! Transmission time: {(end_timer - start_timer) / 1000}",
+                f"successful! Transmission time: {(end_timer - start_timer) / 1000}",
                 "us",
             )
         else:

diff --git a/examples/scanner.py b/examples/scanner.py
@@ -7,7 +7,8 @@
 """
 
 import time
-from pyrf24 import RF24, RF24_CRC_DISABLED, address_repr, RF24_DRIVER
+from typing import Optional
+from pyrf24 import RF24, RF24_CRC_DISABLED, address_repr, RF24_DRIVER, RF24_FIFO_EMPTY
 
 print(__file__)  # print example name
 
@@ -70,13 +71,13 @@ def scan(timeout: int = 30):
     signals = [0] * 126  # store the signal count for each channel
     sweeps = 0  # keep track of the number of sweeps made through all channels
     curr_channel = 0
-    start_timer = time.monotonic()  # start the timer
-    while time.monotonic() - start_timer < timeout:
+    end_time = time.monotonic() + timeout  # start the timer
+    while time.monotonic() < end_time:
         radio.channel = curr_channel
-        radio.listen = 1  # start a RX session
+        radio.listen = True  # start a RX session
         time.sleep(0.00013)  # wait 130 microseconds
         found_signal = radio.rpd
-        radio.listen = 0  # end the RX session
+        radio.listen = False  # end the RX session
         found_signal = found_signal or radio.rpd or radio.available()
 
         # count signal as interference
@@ -110,7 +111,7 @@ def scan(timeout: int = 30):
     print("")
 
 
-def noise(timeout: int = 1, channel: int = None):
+def noise(timeout: int = 1, channel: Optional[int] = None):
     """print a stream of detected noise for duration of time.
 
     :param int timeout: The number of seconds to scan for ambient noise.
@@ -120,15 +121,15 @@ def noise(timeout: int = 1, channel: int = None):
     if channel is not None:
         radio.channel = channel
     radio.listen = True
-    timeout += time.monotonic()
-    while time.monotonic() < timeout:
+    end_time = timeout + time.monotonic()
+    while time.monotonic() < end_time:
         signal = radio.read(radio.payload_size)
         if signal:
             print(address_repr(signal, False, " "))
     radio.listen = False
-    while not radio.is_fifo(False, True):
+    while radio.is_fifo(False) != RF24_FIFO_EMPTY:
         # dump the left overs in the RX FIFO
-        print(address_repr(radio.read(), False, " "))
+        print(address_repr(radio.read(32), False, " "))
 
 
 def set_role():

diff --git a/examples/scanner_curses.py b/examples/scanner_curses.py
@@ -8,7 +8,7 @@
 
 import curses
 import time
-from typing import List, Tuple, Any
+from typing import List, Tuple, Any, cast, Optional
 from pyrf24 import RF24, RF24_1MBPS, RF24_2MBPS, RF24_250KBPS, RF24_DRIVER
 
 print(__file__)  # print example name
@@ -75,7 +75,7 @@ def __init__(  # pylint: disable=too-many-arguments,invalid-name
         x: int,
         y: int,
         cols: int,
-        std_scr: Any,  # type: curses.window,
+        std_scr: Any,  # type is actually curses.window,
         label: str,
         color: int,
     ):
@@ -109,7 +109,7 @@ def update(self, completed: int, signal_count: int):
 
 def init_display(window) -> List[ProgressBar]:
     """Creates a table of progress bars (1 for each channel)."""
-    progress_bars: List[ProgressBar] = [None] * TOTAL_CHANNELS
+    progress_bars: List[Optional[ProgressBar]] = [None] * TOTAL_CHANNELS
     bar_w = int(curses.COLS / 6)
     for i in range(21):  # 21 rows
         for j in range(i, i + (21 * 6), 21):  # 6 columns
@@ -122,7 +122,7 @@ def init_display(window) -> List[ProgressBar]:
                 label=f"{2400 + (j)} ",
                 color=color,
             )
-    return progress_bars
+    return cast(List[ProgressBar], progress_bars)
 
 
 def init_radio():

diff --git a/requirements.txt → requirements-build.txt b/requirements.txt → requirements-build.txt
diff --git a/src/pyRF24.cpp b/src/pyRF24.cpp
@@ -65,6 +65,21 @@ void init_rf24(py::module& m)
         )docstr")
         .export_values();
 
+    py::enum_<rf24_fifo_state_e>(m, "rf24_fifo_state_e")
+        .value("RF24_FIFO_OCCUPIED", RF24_FIFO_OCCUPIED, R"docstr(
+            The FIFO is not full nor empty, but it is occupied with 1 or 2 payloads.
+        )docstr")
+        .value("RF24_FIFO_EMPTY", RF24_FIFO_EMPTY, R"docstr(
+            The FIFO is empty.
+        )docstr")
+        .value("RF24_FIFO_FULL", RF24_FIFO_FULL, R"docstr(
+            The FIFO is full.
+        )docstr")
+        .value("RF24_FIFO_INVALID", RF24_FIFO_INVALID, R"docstr(
+            Represents corruption of data over SPI (when observed).
+        )docstr")
+        .export_values();
+
     py::enum_<rf24_pa_dbm_e>(m, "rf24_pa_dbm_e")
         .value("RF24_PA_MIN", RF24_PA_MIN, R"docstr(
             +----------------------+--------------------+--------------------+
@@ -711,6 +726,12 @@ void init_rf24(py::module& m)
 
             :param int pipe_number: The pipe number to use for receiving transmissions. This value should be in range [0, 5].
             :param bytes,bytearray,int address: The address assigned to the specified data pipe for receiving transmissions.
+
+                .. deprecated:: 0.2.1
+                    Use `bytes` or `bytearray` to specify address.
+
+                    Using an `int` to specify the address has been deprecated because of
+                    inconsistent endianess and needless memory consumption.
         )docstr",
              py::arg("pipe_number"), py::arg("address"))
 
@@ -739,6 +760,12 @@ void init_rf24(py::module& m)
             Open data pipe 0 for transmitting to a specified address.
 
             :param bytes,bytearray,int address: The address assigned to data pipe 0 for outgoing transmissions.
+
+                .. deprecated:: 0.2.1
+                    Use `bytes` or `bytearray` to specify address.
+
+                    Using an `int` to specify the address has been deprecated because of
+                    inconsistent endianess and needless memory consumption.
         )docstr",
              py::arg("address"))
 
@@ -834,7 +861,7 @@ void init_rf24(py::module& m)
 
         .def("is_fifo", static_cast<bool (RF24Wrapper::*)(bool, bool)>(&RF24Wrapper::isFifo), R"docstr(
             is_fifo(about_tx: bool, check_empty: bool) -> bool \
-            is_fifo(about_tx: bool) -> int
+            is_fifo(about_tx: bool) -> rf24_fifo_state_e
 
 
             Get information about a specified FIFO buffers.
@@ -843,6 +870,13 @@ void init_rf24(py::module& m)
                 to make returned data describe the RX FIFO.
             :param bool check_empty: Check if the specified FIFO is empty. Set this to `False` to
                 check if the specified FIFO is full.
+
+                .. deprecated:: 0.4.4
+                    Use ``is_fifo(about_tx: bool)`` for better precision.
+
+                    The ``is_fifo(about_tx: bool, check_empty: bool)`` signature may yield
+                    inaccurate information when data suffers corruption over the SPI bus'
+                    MISO line.
         )docstr",
              py::arg("about_tx"), py::arg("check_empty"))
 
@@ -853,19 +887,17 @@ void init_rf24(py::module& m)
 
         // *****************************************************************************
 
-        .def("is_fifo", static_cast<uint8_t (RF24Wrapper::*)(bool)>(&RF24Wrapper::isFifo), R"docstr(
+        .def("is_fifo", static_cast<rf24_fifo_state_e (RF24Wrapper::*)(bool)>(&RF24Wrapper::isFifo), R"docstr(
             :Returns:
-                - A `bool` describing if the specified FIFO is empty or full.
-                - An `int` if the ``check_empty`` parameter was unspecified. In which case, the return integer is
-
-                  - ``0`` if the specified FIFO is neither full nor empty.
-                  - ``1`` if the specified FIFO is empty.
-                  - ``2`` if the specified FIFO is full.
+                - A `bool` describing if the specified FIFO is empty or full
+                  if the ``check_empty`` parameter was specified.
+                - An enumeration of `rf24_fifo_state_e` describing the specifed FIFO's state
+                  if the ``check_empty`` parameter was unspecified.
         )docstr",
              py::arg("about_tx"))
 
-        .def("isFifo", static_cast<uint8_t (RF24Wrapper::*)(bool)>(&RF24Wrapper::isFifo), R"docstr(
-            isFifo(about_tx: bool) -> int
+        .def("isFifo", static_cast<rf24_fifo_state_e (RF24Wrapper::*)(bool)>(&RF24Wrapper::isFifo), R"docstr(
+            isFifo(about_tx: bool) -> rf24_fifo_state_e
         )docstr",
              py::arg("about_tx"))
 

diff --git a/src/pyrf24/__init__.py b/src/pyrf24/__init__.py
@@ -14,6 +14,11 @@
     RF24_PA_HIGH,
     RF24_PA_MAX,
     RF24_DRIVER,
+    rf24_fifo_state_e,
+    RF24_FIFO_OCCUPIED,
+    RF24_FIFO_EMPTY,
+    RF24_FIFO_FULL,
+    RF24_FIFO_INVALID,
     RF24Network,
     RF24NetworkHeader,
     # RF24NetworkFrame,
@@ -72,6 +77,11 @@
     "RF24_PA_HIGH",
     "RF24_PA_MAX",
     "RF24_DRIVER",
+    "rf24_fifo_state_e",
+    "RF24_FIFO_OCCUPIED",
+    "RF24_FIFO_EMPTY",
+    "RF24_FIFO_FULL",
+    "RF24_FIFO_INVALID",
     "RF24Network",
     "RF24NetworkHeader",
     "MAX_USER_DEFINED_HEADER_TYPE",

diff --git a/src/pyrf24/pyrf24.pyi b/src/pyrf24/pyrf24.pyi
@@ -33,6 +33,17 @@ RF24_PA_LOW: rf24_pa_dbm_e = rf24_pa_dbm_e.RF24_PA_LOW
 RF24_PA_HIGH: rf24_pa_dbm_e = rf24_pa_dbm_e.RF24_PA_HIGH
 RF24_PA_MAX: rf24_pa_dbm_e = rf24_pa_dbm_e.RF24_PA_MAX
 
+class rf24_fifo_state_e:
+    RF24_FIFO_OCCUPIED: rf24_fifo_state_e
+    RF24_FIFO_EMPTY: rf24_fifo_state_e
+    RF24_FIFO_FULL: rf24_fifo_state_e
+    RF24_FIFO_INVALID: rf24_fifo_state_e
+
+RF24_FIFO_OCCUPIED: rf24_fifo_state_e = rf24_fifo_state_e.RF24_FIFO_OCCUPIED
+RF24_FIFO_EMPTY: rf24_fifo_state_e = rf24_fifo_state_e.RF24_FIFO_EMPTY
+RF24_FIFO_FULL: rf24_fifo_state_e = rf24_fifo_state_e.RF24_FIFO_FULL
+RF24_FIFO_INVALID: rf24_fifo_state_e = rf24_fifo_state_e.RF24_FIFO_INVALID
+
 class RF24:
     @overload
     def __init__(
@@ -69,12 +80,14 @@ class RF24:
     def isChipConnected(self) -> bool: ...
     def isPVariant(self) -> bool: ...
     def isValid(self) -> bool: ...
-    def is_fifo(
-        self, about_tx: bool, check_empty: Optional[bool] = None
-    ) -> Union[bool, int]: ...
-    def isFifo(
-        self, about_tx: bool, check_empty: Optional[bool] = None
-    ) -> Union[bool, int]: ...
+    @overload
+    def is_fifo(self, about_tx: bool) -> rf24_fifo_state_e: ...
+    @overload
+    def is_fifo(self, about_tx: bool, check_empty: bool) -> bool: ...
+    @overload
+    def isFifo(self, about_tx: bool) -> rf24_fifo_state_e: ...
+    @overload
+    def isFifo(self, about_tx: bool, check_empty: bool) -> bool: ...
     def mask_irq(self, tx_ok: bool, tx_fail: bool, rx_ready: bool) -> None: ...
     def maskIRQ(self, tx_ok: bool, tx_fail: bool, rx_ready: bool) -> None: ...
     def open_tx_pipe(self, address: Union[bytes, bytearray, int]) -> None: ...
+34 −2		CHANGELOG.md
+10 −15		RF24.cpp
+26 −4		RF24.h
+0 −3		RF24_config.h
+1 −1		library.json
+1 −1		library.properties
+8 −1		pyRF24/pyRF24.cpp
+19 −0		CHANGELOG.md
+1 −1		library.json
+1 −1		library.properties