From 0aa6818b87b325d70daa211a07c79190cadbe9cf Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Sat, 15 Jun 2024 04:41:25 -0700 Subject: [PATCH] fix docs --- docs/ble_api.rst | 16 +++++++------- docs/conf.py | 2 +- docs/rf24_api.rst | 28 ++++++++++++------------ docs/rf24_mesh_api.rst | 14 ++++++------ docs/rf24_network_api.rst | 38 ++++++++++++++++---------------- docs/topology.rst | 14 ++++++------ src/pyRF24.cpp | 46 +++++++++++++++++++-------------------- src/pyRF24Mesh.cpp | 18 +++++++-------- src/pyRF24Network.cpp | 30 ++++++++++++------------- src/pyrf24/__init__.py | 6 +++++ src/pyrf24/fake_ble.py | 22 +++++++++---------- 11 files changed, 120 insertions(+), 114 deletions(-) diff --git a/docs/ble_api.rst b/docs/ble_api.rst index b1929fd..801e671 100644 --- a/docs/ble_api.rst +++ b/docs/ble_api.rst @@ -38,14 +38,14 @@ Restricted RF24 functionality The following `RF24` functionality should not be used when `FakeBLE` objects are instantiated with an `RF24` object: -- :py:attr:`~pyrf24.rf24.RF24.dynamic_payloads` -- :py:attr:`~pyrf24.rf24.RF24.data_rate` -- :py:attr:`~pyrf24.rf24.RF24.address_width` -- :py:meth:`~pyrf24.rf24.RF24.set_auto_ack()` -- :py:attr:`~pyrf24.rf24.RF24.ack_payloads` -- :py:attr:`~pyrf24.rf24.RF24.crc_length` -- :py:meth:`~pyrf24.rf24.RF24.open_rx_pipe()` -- :py:meth:`~pyrf24.rf24.RF24.open_tx_pipe()` +- :py:attr:`~pyrf24.RF24.dynamic_payloads` +- :py:attr:`~pyrf24.RF24.data_rate` +- :py:attr:`~pyrf24.RF24.address_width` +- :py:meth:`~pyrf24.RF24.set_auto_ack()` +- :py:attr:`~pyrf24.RF24.ack_payloads` +- :py:attr:`~pyrf24.RF24.crc_length` +- :py:meth:`~pyrf24.RF24.open_rx_pipe()` +- :py:meth:`~pyrf24.RF24.open_tx_pipe()` Service related classes diff --git a/docs/conf.py b/docs/conf.py index f878872..bdaf813 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -175,7 +175,7 @@ ] python_type_aliases = { - "pyrf24.rf24.rf24_datarate_e": "rf24_datarate_e", + "pyrf24.rf24_datarate_e": "rf24_datarate_e", } # Set link name generated in the top bar. diff --git a/docs/rf24_api.rst b/docs/rf24_api.rst index 4b3d467..279ceac 100644 --- a/docs/rf24_api.rst +++ b/docs/rf24_api.rst @@ -3,37 +3,37 @@ RF24 API ======== -.. automodule:: pyrf24.rf24 +.. currentmodule:: pyrf24 - .. autoattribute:: pyrf24.rf24.RF24_DRIVER +.. autoattribute:: pyrf24.RF24_DRIVER - This `str` describes the backend driver used to build the pyrf24 package. - If installed from pypi, then this value should be ``"SPIDEV"``. - - All other drivers imply that the pyrf24 package was built from source - :ref:`using-specific-driver`. + This `str` describes the backend driver used to build the pyrf24 package. + If installed from pypi, then this value should be ``"SPIDEV"``. + + All other drivers imply that the pyrf24 package was built from source + :ref:`using-specific-driver`. - .. hint:: + .. hint:: - Use this attribute to determine programmatically which pin numbers to use. - Drivers like ``wiringPi`` and ``MRAA`` use their own pin numbering scheme. + Use this attribute to determine programmatically which pin numbers to use. + Drivers like ``wiringPi`` and ``MRAA`` use their own pin numbering scheme. Enum classes ------------ -.. autoclass:: pyrf24.rf24.rf24_crclength_e +.. autoclass:: pyrf24.rf24_crclength_e :members: RF24_CRC_DISABLED, RF24_CRC_8, RF24_CRC_16 -.. autoclass:: pyrf24.rf24.rf24_datarate_e +.. autoclass:: pyrf24.rf24_datarate_e :members: RF24_1MBPS, RF24_2MBPS, RF24_250KBPS -.. autoclass:: pyrf24.rf24.rf24_pa_dbm_e +.. autoclass:: pyrf24.rf24_pa_dbm_e :members: RF24_PA_MIN, RF24_PA_LOW, RF24_PA_HIGH, RF24_PA_MAX RF24 class ---------- -.. autoclass:: pyrf24.rf24.RF24 +.. autoclass:: pyrf24.RF24 Basic RF24 API ************** diff --git a/docs/rf24_mesh_api.rst b/docs/rf24_mesh_api.rst index bc51e2f..528c14d 100644 --- a/docs/rf24_mesh_api.rst +++ b/docs/rf24_mesh_api.rst @@ -3,12 +3,12 @@ RF24Mesh API ============ -.. automodule:: pyrf24.rf24_mesh +.. currentmodule:: pyrf24 RF24Mesh class ************** -.. autoclass:: pyrf24.rf24_mesh.RF24Mesh +.. autoclass:: pyrf24.RF24Mesh Basic RF24Mesh API ------------------ @@ -43,7 +43,7 @@ successful connection to a child node. The `AddrListStruct` class supports the python "magic method" :py:func:`repr()`. So, you can easily pass an instantiated `AddrListStruct` object to the :py:func:`print()` function. -.. autoclass:: pyrf24.rf24_mesh.AddrListStruct +.. autoclass:: pyrf24.AddrListStruct .. autoattribute:: node_id .. autoattribute:: address @@ -53,14 +53,14 @@ Mesh Constants These are the pre-defined constants provided for convenience and code readability. -.. autoattribute:: pyrf24.rf24_mesh.MESH_DEFAULT_ADDRESS +.. autoattribute:: pyrf24.MESH_DEFAULT_ADDRESS A reserved valid address for use with RF24Mesh (when a mesh node requests an assigned address) Reserved System Message Types ----------------------------- -.. autoattribute:: pyrf24.rf24_mesh.MESH_ADDR_LOOKUP +.. autoattribute:: pyrf24.MESH_ADDR_LOOKUP This message type is used to fetch (from the master node) an allocated Logical Address (`mesh_address`) corresponding to specified a mesh node's @@ -68,7 +68,7 @@ Reserved System Message Types This is exclusively used by `get_address()`. -.. autoattribute:: pyrf24.rf24_mesh.MESH_ID_LOOKUP +.. autoattribute:: pyrf24.MESH_ID_LOOKUP This message type is used to fetch (from the master node) a mesh node's :py:attr:`~RF24Mesh.node_id` corresponding to an specified Logical Address @@ -76,7 +76,7 @@ Reserved System Message Types This is exclusively used by `get_node_id()`. -.. autoattribute:: pyrf24.rf24_mesh.MESH_ADDR_RELEASE +.. autoattribute:: pyrf24.MESH_ADDR_RELEASE This message type is used when mesh nodes are consciously disconnecting from the network. It is used to unassign the Logical Address allocated the mesh node's diff --git a/docs/rf24_network_api.rst b/docs/rf24_network_api.rst index b99db96..053ebc3 100644 --- a/docs/rf24_network_api.rst +++ b/docs/rf24_network_api.rst @@ -3,13 +3,13 @@ RF24Network API =============== -.. automodule:: pyrf24.rf24_network +.. currentmodule:: pyrf24 RF24Network class ----------------- -.. autoclass:: pyrf24.rf24_network.RF24Network +.. autoclass:: pyrf24.RF24Network Basic RF24Network API ********************* @@ -36,8 +36,8 @@ RF24Network class External Systems or Applications ******************************** -.. autoattribute:: pyrf24.rf24_network.RF24Network.return_sys_msgs -.. autoattribute:: pyrf24.rf24_network.RF24Network.network_flags +.. autoattribute:: pyrf24.RF24Network.return_sys_msgs +.. autoattribute:: pyrf24.RF24Network.network_flags RF24NetworkHeader class ----------------------- @@ -46,7 +46,7 @@ RF24NetworkHeader class The `RF24NetworkHeader` class supports the python "magic method" :py:func:`repr()`. So, you can easily pass an instantiated `RF24NetworkHeader` object to the :py:func:`print()` function. -.. autoclass:: pyrf24.rf24_network.RF24NetworkHeader +.. autoclass:: pyrf24.RF24NetworkHeader .. autoattribute:: to_node .. autoattribute:: type @@ -66,11 +66,11 @@ Constants The following are predefined module-level constants that can be used for comparisons and code readability. -.. autoattribute:: pyrf24.rf24_network.MAX_USER_DEFINED_HEADER_TYPE +.. autoattribute:: pyrf24.MAX_USER_DEFINED_HEADER_TYPE The maximum of user defined message types. -.. autoattribute:: pyrf24.rf24_network.MAX_PAYLOAD_SIZE +.. autoattribute:: pyrf24.MAX_PAYLOAD_SIZE Maximum size of fragmented network frames and fragmentation cache. @@ -87,7 +87,7 @@ The network will determine whether to automatically acknowledge payloads based o System types can also contain message data. -.. autoattribute:: pyrf24.rf24_network.NETWORK_ADDR_RESPONSE +.. autoattribute:: pyrf24.NETWORK_ADDR_RESPONSE A ``NETWORK_ADDR_RESPONSE`` type is utilized to manually route custom messages containing a single RF24Network address. @@ -100,32 +100,32 @@ System types can also contain message data. This allows nodes to forward multicast messages to the master node, receive a response, and forward it back to the requester. -.. autoattribute:: pyrf24.rf24_network.NETWORK_PING +.. autoattribute:: pyrf24.NETWORK_PING Messages of type ``NETWORK_PING`` will be dropped automatically by the recipient. A `NETWORK_ACK` or automatic radio-ack will indicate to the sender whether the payload was successful. The time it takes to successfully send a ``NETWORK_PING`` is the round-trip-time. -.. autoattribute:: pyrf24.rf24_network.EXTERNAL_DATA_TYPE +.. autoattribute:: pyrf24.EXTERNAL_DATA_TYPE External data types are used to define messages that will be passed to an external data system. This allows RF24Network to route and pass any type of data, such as TCP/IP frames, while still being able to utilize standard RF24Network messages etc. -.. autoattribute:: pyrf24.rf24_network.NETWORK_FIRST_FRAGMENT +.. autoattribute:: pyrf24.NETWORK_FIRST_FRAGMENT Messages of this type designate the first of two or more message fragments, and will be re-assembled automatically. -.. autoattribute:: pyrf24.rf24_network.NETWORK_MORE_FRAGMENTS +.. autoattribute:: pyrf24.NETWORK_MORE_FRAGMENTS Messages of this type indicate a fragmented payload with two or more message fragments. -.. autoattribute:: pyrf24.rf24_network.NETWORK_LAST_FRAGMENT +.. autoattribute:: pyrf24.NETWORK_LAST_FRAGMENT Messages of this type indicate the last fragment in a sequence of message fragments. Messages of this type do not receive a `NETWORK_ACK`. -.. autoattribute:: pyrf24.rf24_network.NETWORK_ACK +.. autoattribute:: pyrf24.NETWORK_ACK Messages of this type signal the sender that a network-wide transmission has been completed. @@ -161,7 +161,7 @@ System types can also contain message data. ie: When node ``0o0`` sends an instigating message to node ``0o11``, node ``0o1`` will send the ``NETWORK_ACK`` message to ``0o0`` upon successful delivery of instigating message to node ``0o11``. -.. autoattribute:: pyrf24.rf24_network.NETWORK_POLL +.. autoattribute:: pyrf24.NETWORK_POLL Used by RF24Mesh. @@ -169,7 +169,7 @@ System types can also contain message data. Any node receiving a NETWORK_POLL sent to a multicast address will respond directly to the sender with a blank message, indicating the address of the available node via the header. -.. autoattribute:: pyrf24.rf24_network.NETWORK_REQ_ADDRESS +.. autoattribute:: pyrf24.NETWORK_REQ_ADDRESS Used by RF24Mesh @@ -179,13 +179,13 @@ System types can also contain message data. Network flag mnemonics *********************** -.. autoattribute:: pyrf24.rf24_network.FLAG_FAST_FRAG +.. autoattribute:: pyrf24.FLAG_FAST_FRAG This flag (when asserted in :py:attr:`~RF24Network.network_flags`) prevents repetitively configuring the radio during transmission of fragmented messages. -.. autoattribute:: pyrf24.rf24_network.FLAG_NO_POLL +.. autoattribute:: pyrf24.FLAG_NO_POLL This flag (when asserted in :py:attr:`~RF24Network.network_flags`) prevents a node from responding to - mesh nodes looking to connect to the network. Calling :py:func:`~pyrf24.rf24_mesh.RF24Mesh.set_child()` uses this flag + mesh nodes looking to connect to the network. Calling :py:func:`~pyrf24.RF24Mesh.set_child()` uses this flag accordingly. diff --git a/docs/topology.rst b/docs/topology.rst index 29945df..1383e0b 100644 --- a/docs/topology.rst +++ b/docs/topology.rst @@ -113,7 +113,7 @@ For a message to travel from node ``0o124`` to node ``0o3``, it must be passed t network levels. So, the message flows ``0o124`` -> ``0o24`` -> ``0o4`` -> ``0o0`` -> ``0o3``. A single network can potentially have a maximum of 781 nodes (all operating on the same -:attr:`~pyrf24.rf24.RF24.channel`), but for readability reasons, the following +:attr:`~pyrf24.RF24.channel`), but for readability reasons, the following graph only demonstrates - the master node (level 0) and it's 5 children (level 1) @@ -216,7 +216,7 @@ Physical addresses vs Logical addresses number ``0`` .. tip:: - Use the :py:meth:`~pyrf24.rf24_network.RF24Network.is_address_valid()` + Use the :py:meth:`~pyrf24.RF24Network.is_address_valid()` function to programmatically check a Logical Address for validity. .. note:: @@ -295,7 +295,7 @@ RF24Mesh connecting process As noted above, a single network *can* have up to 781 nodes. This number also includes up to 255 RF24Mesh nodes. The key difference from the user's perspective is that RF24Mesh API does not publicly use a `Logical Address `. Instead the RF24Mesh API -relies on a :attr:`~pyrf24.rf24_mesh.RF24Mesh.node_id` number to identify a RF24Mesh node +relies on a :attr:`~pyrf24.RF24Mesh.node_id` number to identify a RF24Mesh node that may use a different `Logical Address ` (which can change based on the node's physical location). @@ -305,17 +305,17 @@ the node's physical location). is layered on top of the RF24Network API. To better explain the difference between a node's `mesh_address` vs a node's -:attr:`~pyrf24.rf24_mesh.RF24Mesh.node_id`, we will examine the connecting process for a +:attr:`~pyrf24.RF24Mesh.node_id`, we will examine the connecting process for a RF24Mesh node. These are the steps performed when calling `renew_address()`: 1. Any RF24Mesh node not connected to a network will use the `Logical Address ` ``0o4444`` (that's ``2340`` in decimal). It is up to the network administrator to ensure that - each RF24Mesh node has a unique :attr:`~pyrf24.rf24_mesh.RF24Mesh.node_id` (which is limited + each RF24Mesh node has a unique :attr:`~pyrf24.RF24Mesh.node_id` (which is limited to the range [0, 255]). .. hint:: Remember that ``0`` is reserved the master node's - :attr:`~pyrf24.rf24_mesh.RF24Mesh.node_id`. + :attr:`~pyrf24.RF24Mesh.node_id`. 2. To get assigned a `Logical Address `, an unconnected node must poll the network for a response (using a `NETWORK_POLL` message). Initially this happens on the network level 0, but consecutive attempts will poll higher network levels (in order of low to @@ -329,7 +329,7 @@ RF24Mesh node. These are the steps performed when calling `renew_address()`: respond with an invalid `Logical Address `. 5. Once the requesting node receives the address response (and the assigned address is valid), it assumes that as the `mesh_address` while maintaining its - :attr:`~pyrf24.rf24_mesh.RF24Mesh.node_id`. + :attr:`~pyrf24.RF24Mesh.node_id`. - The connecting node will verify its new address by calling `check_connection()`. - If the assigned address is invalid or `check_connection()` returns `False`, then diff --git a/src/pyRF24.cpp b/src/pyRF24.cpp index 14c5f81..79b0627 100644 --- a/src/pyRF24.cpp +++ b/src/pyRF24.cpp @@ -135,7 +135,7 @@ void init_rf24(py::module& m) // ***************************************************************************** .def("getCRCLength", &RF24Wrapper::getCRCLength, R"docstr( - getCRCLength() -> pyrf24.rf24.rf24_crclength_e + getCRCLength() -> pyrf24.rf24_crclength_e Get the current setting of the radio's CRC Length. )docstr") @@ -151,7 +151,7 @@ void init_rf24(py::module& m) // ***************************************************************************** .def("getDataRate", &RF24Wrapper::getDataRate, R"docstr( - getDataRate() -> pyrf24.rf24.rf24_datarate_e + getDataRate() -> pyrf24.rf24_datarate_e Get the current setting of the radio's Data Rate. )docstr") @@ -171,7 +171,7 @@ void init_rf24(py::module& m) // ***************************************************************************** .def("getPALevel", &RF24Wrapper::getPALevel, R"docstr( - getPALevel() -> pyrf24.rf24.rf24_pa_dbm_e + getPALevel() -> pyrf24.rf24_pa_dbm_e Get the current setting of the radio's Power Amplitude Level. )docstr") @@ -334,7 +334,7 @@ void init_rf24(py::module& m) Verify the configured pin numbers are indeed valid. :Returns: `True` if the radio's CE & CSN pins have been configured (using the - RF24 class' constructor or :py:meth:`~pyrf24.rf24.RF24.begin()` function) + RF24 class' constructor or :py:meth:`~pyrf24.RF24.begin()` function) )docstr") // ***************************************************************************** @@ -380,7 +380,7 @@ void init_rf24(py::module& m) Calling this function also clears all status flags and resets the IRQ pin to inactive high. .. seealso:: - :py:meth:`~pyrf24.rf24.RF24.mask_irq()` + :py:meth:`~pyrf24.RF24.mask_irq()` )docstr") .def("whatHappened", &RF24Wrapper::what_happened, R"docstr( @@ -392,7 +392,7 @@ void init_rf24(py::module& m) .def("available_pipe", &RF24Wrapper::available_pipe, R"docstr( available_pipe() -> Tuple[bool, int] - Similar to :py:meth:`~pyrf24.rf24.RF24.available()`, but additionally returns the pipe + Similar to :py:meth:`~pyrf24.RF24.available()`, but additionally returns the pipe number that received the next available payload. :Returns: A 2-tuple in which @@ -437,9 +437,9 @@ void init_rf24(py::module& m) .. seealso:: - - :py:meth:`~pyrf24.rf24.RF24.set_pa_level()` - - :py:attr:`~pyrf24.rf24.RF24.pa_level` - - :py:attr:`~pyrf24.rf24.RF24.data_rate` + - :py:meth:`~pyrf24.RF24.set_pa_level()` + - :py:attr:`~pyrf24.RF24.pa_level` + - :py:attr:`~pyrf24.RF24.data_rate` )docstr", py::arg("level"), py::arg("speed"), py::arg("lna_enable") = true) @@ -635,9 +635,9 @@ void init_rf24(py::module& m) .. seealso:: - - :py:attr:`~pyrf24.rf24.RF24.payload_size` - - :py:meth:`~pyrf24.rf24.RF24.get_dynamic_payload_size()` - - :py:meth:`~pyrf24.rf24.RF24.available()` + - :py:attr:`~pyrf24.RF24.payload_size` + - :py:meth:`~pyrf24.RF24.get_dynamic_payload_size()` + - :py:meth:`~pyrf24.RF24.available()` )docstr", py::arg("length") = 0) @@ -663,7 +663,7 @@ void init_rf24(py::module& m) configured, the ``ce_pin`` and ``csn_pin`` parameters can be omitted. .. important:: If dynamically configuring the pin numbers, then they must be set using - the overloaded :py:meth:`~pyrf24.rf24.RF24.begin()` function. + the overloaded :py:meth:`~pyrf24.RF24.begin()` function. )docstr", py::arg("spi_speed") = 10000000) @@ -698,7 +698,7 @@ void init_rf24(py::module& m) :Returns: `True` if there is a payload in the radio's RX FIFO, otherwise `False`. .. seealso:: - Use :py:meth:`~pyrf24.rf24.RF24.available_pipe()` to get the pipe number that received the + Use :py:meth:`~pyrf24.RF24.available_pipe()` to get the pipe number that received the next available payload. )docstr") @@ -932,18 +932,18 @@ void init_rf24(py::module& m) .. hint:: - 1. Be sure to call :py:meth:`~pyrf24.rf24.RF24.open_rx_pipe()` before - setting :py:attr:`~pyrf24.rf24.RF24.listen` to `True`. - 2. Do not call :py:meth:`~pyrf24.rf24.RF24.write()` while in RX mode, without - first setting :py:attr:`~pyrf24.rf24.RF24.listen` to `False`. - 3. Call :py:meth:`~pyrf24.rf24.RF24.available()` to check for incoming traffic, - and use :py:meth:`~pyrf24.rf24.RF24.read()` to get it. + 1. Be sure to call :py:meth:`~pyrf24.RF24.open_rx_pipe()` before + setting :py:attr:`~pyrf24.RF24.listen` to `True`. + 2. Do not call :py:meth:`~pyrf24.RF24.write()` while in RX mode, without + first setting :py:attr:`~pyrf24.RF24.listen` to `False`. + 3. Call :py:meth:`~pyrf24.RF24.available()` to check for incoming traffic, + and use :py:meth:`~pyrf24.RF24.read()` to get it. .. important:: - If there was a call to :py:meth:`~pyrf24.rf24.RF24.open_rx_pipe()` + If there was a call to :py:meth:`~pyrf24.RF24.open_rx_pipe()` about pipe 0 prior to setting this attribute to `False`, then this attribute will re-write the address that was last set to RX pipe 0. - This is because :py:meth:`~pyrf24.rf24.RF24.open_tx_pipe()` + This is because :py:meth:`~pyrf24.RF24.open_tx_pipe()` will overwrite the address to RX pipe 0 for proper auto-ack functionality. .. note:: @@ -1043,7 +1043,7 @@ void init_rf24(py::module& m) .def_property_readonly("is_chip_connected", &RF24Wrapper::isChipConnected, R"docstr( Check if the SPI bus is working with the radio. This read-only `bool` attribute assumes that - :py:meth:`~pyrf24.rf24.RF24.begin()` returned `True`. + :py:meth:`~pyrf24.RF24.begin()` returned `True`. )docstr") .def("isChipConnected", &RF24Wrapper::isChipConnected, R"docstr( diff --git a/src/pyRF24Mesh.cpp b/src/pyRF24Mesh.cpp index b2dcac0..3979b10 100644 --- a/src/pyRF24Mesh.cpp +++ b/src/pyRF24Mesh.cpp @@ -36,10 +36,10 @@ void init_rf24mesh(py::module& m) // ***************************************************************************** .def("begin", &RF24MeshWrapper::begin, R"docstr( - begin(channel: int = 97, data_rate: pyrf24.rf24.rf24_datarate_e = RF24_1MBPS, timeout: int = 7500) -> bool + begin(channel: int = 97, data_rate: pyrf24.rf24_datarate_e = RF24_1MBPS, timeout: int = 7500) -> bool - :param int channel: The :py:attr:`~pyrf24.rf24.RF24.channel` to use for the network. - :param ~pyrf24.rf24.rf24_datarate_e data_rate: The :py:attr:`~pyrf24.rf24.RF24.data_rate` + :param int channel: The :py:attr:`~pyrf24.RF24.channel` to use for the network. + :param ~pyrf24.rf24_datarate_e data_rate: The :py:attr:`~pyrf24.RF24.data_rate` to use for the network. :param int timeout: The timeout to use when connecting to the mesh network. This value is equivalent to the ``timeout`` parameter in `renew_address()` @@ -60,7 +60,7 @@ void init_rf24mesh(py::module& m) Keep the mesh network layer current. This function should be called regularly in the application. For applications that have a long-running operations in 1 "loop"/iteration, then it is advised to call this function more than once. - :Returns: the `int` of the last received header's :py:attr:`~pyrf24.rf24_network.RF24NetworkHeader.type` + :Returns: the `int` of the last received header's :py:attr:`~pyrf24.RF24NetworkHeader.type` )docstr") // ***************************************************************************** @@ -70,7 +70,7 @@ void init_rf24mesh(py::module& m) write(to_node_address: int, buf: Union[bytes, bytearray], message_type: int) -> bool :param bytes,bytearray buf: The message to transmit. - :param int message_type: The :py:attr:`~pyrf24.rf24_network.RF24NetworkHeader.type` to + :param int message_type: The :py:attr:`~pyrf24.RF24NetworkHeader.type` to be used in the frame's header. :Returns: `True` if the message was successfully sent, otherwise `False` @@ -99,7 +99,7 @@ void init_rf24mesh(py::module& m) Only call this function on a mesh network's master node to manually assign a logical address to a unique `node_id`. This function is meant to include RF24Network nodes in - mesh networks' :attr:`~pyrf24.rf24_mesh.RF24Mesh.addr_list` list. + mesh networks' :attr:`~pyrf24.RF24Mesh.addr_list` list. .. code-block:: py @@ -171,7 +171,7 @@ void init_rf24mesh(py::module& m) Keep the master node's list of assigned addresses up-to-date. .. tip:: This function should be called on a mesh network's master node immediately - after calling :py:meth:`~pyrf24.rf24_mesh.RF24Mesh.update()`. + after calling :py:meth:`~pyrf24.RF24Mesh.update()`. )docstr") .def("DHCP", &RF24MeshWrapper::DHCP, R"docstr( @@ -305,7 +305,7 @@ void init_rf24mesh(py::module& m) Translates a `node_id` into the corresponding `mesh_address` :param int node_id: The identifying number of the mesh node for which to fetch the - corresponding :py:attr:`~pyrf24.rf24_network.RF24Network.node_address`. + corresponding :py:attr:`~pyrf24.RF24Network.node_address`. :Returns: @@ -328,7 +328,7 @@ void init_rf24mesh(py::module& m) set_channel(channel: int) This function controls the radio's configured `channel` (AKA frequency). - :param int channel: The desired :py:attr:`~pyrf24.rf24.RF24.channel` to be used for the network. + :param int channel: The desired :py:attr:`~pyrf24.RF24.channel` to be used for the network. )docstr", py::arg("channel")) diff --git a/src/pyRF24Network.cpp b/src/pyRF24Network.cpp index fb9d05f..fab7308 100644 --- a/src/pyRF24Network.cpp +++ b/src/pyRF24Network.cpp @@ -123,7 +123,7 @@ void init_rf24network(py::module& m) // ***************************************************************************** .def_readwrite("header", &RF24NetworkFrameWrapper::header, R"docstr( - The :py:class:`~pyrf24.rf24_network.RF24NetworkHeader` object about the frame's message. + The :py:class:`~pyrf24.RF24NetworkHeader` object about the frame's message. )docstr") // ***************************************************************************** @@ -136,7 +136,7 @@ void init_rf24network(py::module& m) .def_readonly("message_size", &RF24NetworkFrameWrapper::message_size, R"docstr( A read-only attribute that returns the length of the message. This is set accordingly - when the :py:attr:`~pyrf24.rf24_network.RF24NetworkFrame.message_buffer` is changed. + when the :py:attr:`~pyrf24.RF24NetworkFrame.message_buffer` is changed. )docstr"); */ @@ -178,7 +178,7 @@ void init_rf24network(py::module& m) :param int channel: The desired channel used by the network. Using this parameter is the deprecated form of this function. - .. seealso:: Use :py:attr:`~pyrf24.rf24.RF24.channel` attribute to change the radio + .. seealso:: Use :py:attr:`~pyrf24.RF24.channel` attribute to change the radio channel. )docstr", py::arg("channel"), py::arg("node_address")) @@ -211,7 +211,7 @@ void init_rf24network(py::module& m) :param int maxlen: The maximum length of the frame's message to be returned. If this parameter is unspecified or greater than the actual frame's message size, then only the frame's full message size is used. Defaults to - :py:attr:`~pyrf24.rf24_network.MAX_PAYLOAD_SIZE`. + :py:attr:`~pyrf24.MAX_PAYLOAD_SIZE`. :Returns: A `tuple` in which @@ -239,7 +239,7 @@ void init_rf24network(py::module& m) :param int maxlen: The maximum length of the message to fetch. If this parameter is unspecified or greater than the actual frame's message size, then only the frame's full message size is used. Defaults to - :py:attr:`~pyrf24.rf24_network.MAX_PAYLOAD_SIZE`. + :py:attr:`~pyrf24.MAX_PAYLOAD_SIZE`. :Returns: A 2-tuple containing the frame's header (of type `RF24NetworkHeader`) and the frame's message (of type `bytearray`). )docstr", @@ -253,7 +253,7 @@ void init_rf24network(py::module& m) Keep the network layer current. This function should be called regularly in the application. For applications that have a long-running operations in 1 "loop"/iteration, then it is advised to call this function more than once. - :Returns: The `int` of the last received header's :py:attr:`~pyrf24.rf24_network.RF24NetworkHeader.type` + :Returns: The `int` of the last received header's :py:attr:`~pyrf24.RF24NetworkHeader.type` )docstr") // ***************************************************************************** @@ -358,7 +358,7 @@ void init_rf24network(py::module& m) // ***************************************************************************** .def_readwrite("return_sys_msgs", &RF24Network::returnSysMsgs, R"docstr( - This `bool` attribute is used by RF24Mesh to force :py:meth:`~pyrf24.rf24_network.RF24Network.update()` + This `bool` attribute is used by RF24Mesh to force :py:meth:`~pyrf24.RF24Network.update()` to return when handling a frame containing a system message. When this attribute is enabled, the following system messages are not returned because they are handled @@ -367,11 +367,11 @@ void init_rf24network(py::module& m) .. csv-table:: :header: Message Name, Numeric Value, Additional Context - :py:attr:`~pyrf24.rf24_network.NETWORK_ADDR_RESPONSE`, 128, - :py:attr:`~pyrf24.rf24_network.NETWORK_ACK`, 193, - :py:attr:`~pyrf24.rf24_network.NETWORK_PING`, 130, - :py:attr:`~pyrf24.rf24_network.NETWORK_POLL`, 194, With multicast enabled (which is enabled by default) - :py:attr:`~pyrf24.rf24_network.NETWORK_REQ_ADDRESS`, 195, + :py:attr:`~pyrf24.NETWORK_ADDR_RESPONSE`, 128, + :py:attr:`~pyrf24.NETWORK_ACK`, 193, + :py:attr:`~pyrf24.NETWORK_PING`, 130, + :py:attr:`~pyrf24.NETWORK_POLL`, 194, With multicast enabled (which is enabled by default) + :py:attr:`~pyrf24.NETWORK_REQ_ADDRESS`, 195, .. seealso:: There's a more complete list (with behavioral descriptions) of the :ref:`reserved_sys_msgs`. @@ -383,7 +383,7 @@ void init_rf24network(py::module& m) /// TODO: need to write a custom type caster for std::queue to expose the external_queue member // .def_readwrite("external_queue", &RF24NetworkWrapper::external_queue, R"docstr( - // Data with a header type of :py:attr:`~pyrf24.rf24_network.EXTERNAL_DATA_TYPE` will be loaded into a separate queue. + // Data with a header type of :py:attr:`~pyrf24.EXTERNAL_DATA_TYPE` will be loaded into a separate queue. // )docstr") // ***************************************************************************** @@ -398,8 +398,8 @@ void init_rf24network(py::module& m) .. csv-table:: :header: Flags, Value, Description - :py:attr:`~pyrf24.rf24_network.FLAG_FAST_FRAG`, 4 (bit 2 asserted), INTERNAL: Allows for faster transfers between directly connected nodes. - :py:attr:`~pyrf24.rf24_network.FLAG_NO_POLL`, 8 (bit 3 asserted), EXTERNAL/USER: Disables :py:attr:`~pyrf24.rf24_network.NETWORK_POLL` responses on a node-by-node basis. + :py:attr:`~pyrf24.FLAG_FAST_FRAG`, 4 (bit 2 asserted), INTERNAL: Allows for faster transfers between directly connected nodes. + :py:attr:`~pyrf24.FLAG_NO_POLL`, 8 (bit 3 asserted), EXTERNAL/USER: Disables :py:attr:`~pyrf24.NETWORK_POLL` responses on a node-by-node basis. )docstr") .def_readwrite("networkFlags", &RF24Network::networkFlags); diff --git a/src/pyrf24/__init__.py b/src/pyrf24/__init__.py index 76c6df2..a283007 100644 --- a/src/pyrf24/__init__.py +++ b/src/pyrf24/__init__.py @@ -1,11 +1,14 @@ from .pyrf24 import ( # type: ignore RF24, + rf24_crclength_e, RF24_CRC_DISABLED, RF24_CRC_8, RF24_CRC_16, + rf24_datarate_e, RF24_1MBPS, RF24_2MBPS, RF24_250KBPS, + rf24_pa_dbm_e, RF24_PA_MIN, RF24_PA_LOW, RF24_PA_HIGH, @@ -55,12 +58,15 @@ __all__ = [ "RF24", + "rf24_crclength_e", "RF24_CRC_DISABLED", "RF24_CRC_8", "RF24_CRC_16", + "rf24_datarate_e", "RF24_1MBPS", "RF24_2MBPS", "RF24_250KBPS", + "rf24_pa_dbm_e", "RF24_PA_MIN", "RF24_PA_LOW", "RF24_PA_HIGH", diff --git a/src/pyrf24/fake_ble.py b/src/pyrf24/fake_ble.py index 499ea55..d132208 100644 --- a/src/pyrf24/fake_ble.py +++ b/src/pyrf24/fake_ble.py @@ -50,23 +50,23 @@ GHz, 2.426 GHz, and 2.480 GHz. We have provided a tuple of these specific channels for convenience (See `BLE_FREQ` and :py:func:`~pyrf24.fake_ble.FakeBLE.hop_channel()`). - 3. :py:attr:`~pyrf24.rf24.RF24.crc_length` is disabled in the + 3. :py:attr:`~pyrf24.RF24.crc_length` is disabled in the nRF24L01 firmware because BLE specifications require 3 bytes (:py:func:`~pyrf24.fake_ble.crc24_ble()`), and the nRF24L01 firmware can only handle a maximum of 2. Thus, we have appended the required 3 bytes of CRC24 into the payload. - 4. :py:attr:`~pyrf24.rf24.RF24.address_width` of BLE + 4. :py:attr:`~pyrf24.RF24.address_width` of BLE packet only uses 4 bytes, so we have set that accordingly. 5. The auto-ack (automatic acknowledgment) feature of the nRF24L01 is useless when transmitting to BLE devices, thus it is disabled as well as automatic - re-transmit (:py:meth:`~pyrf24.rf24.RF24.get_arc()`) and custom ACK - payloads (:py:attr:`~pyrf24.rf24.RF24.ack_payloads`) features + re-transmit (:py:meth:`~pyrf24.RF24.get_arc()`) and custom ACK + payloads (:py:attr:`~pyrf24.RF24.ack_payloads`) features which both depend on the automatic acknowledgments feature. - 6. The :py:attr:`~pyrf24.rf24.RF24.dynamic_payloads` + 6. The :py:attr:`~pyrf24.RF24.dynamic_payloads` feature of the nRF24L01 isn't compatible with BLE specifications. Thus, we have disabled it. 7. BLE specifications only allow using 1 Mbps RF - :py:attr:`~pyrf24.rf24.RF24.data_rate`, so that too has + :py:attr:`~pyrf24.RF24.data_rate`, so that too has been hard coded. 8. Only the "on data sent" & "on data ready" events will have an effect on the interrupt (IRQ) pin. The "on data fail" is never @@ -77,7 +77,7 @@ from os import urandom import struct from typing import Union, List, Optional -from .pyrf24 import ( +from .pyrf24 import ( # type: ignore RF24, RF24_CRC_DISABLED, RF24_PA_HIGH, @@ -341,7 +341,7 @@ class FakeBLE: """A class to implement BLE advertisements using the nRF24L01. Per the limitations of this technique, only some of underlying - :py:class:`~pyrf24.rf24.RF24` functionality is + :py:class:`~pyrf24.RF24` functionality is available for configuration when implementing BLE transmissions. See the `Restricted RF24 functionality`_ for more details. @@ -349,7 +349,7 @@ class FakeBLE: hardware. .. seealso:: - See the :py:class:`~pyrf24.rf24.RF24` class' constructor documentation. + See the :py:class:`~pyrf24.RF24` class' constructor documentation. """ def __init__(self, radio: RF24): @@ -386,7 +386,7 @@ def begin( ) -> bool: """Initialize the radio using BLE specifications. - Internally, this function also calls :meth:`~pyrf24.rf24.RF24.begin()`, so + Internally, this function also calls :meth:`~pyrf24.RF24.begin()`, so there's no need to initialized the radio's hardware before calling this function. @@ -466,7 +466,7 @@ def name(self, _name): @property def show_pa_level(self) -> bool: """If this attribute is `True`, the payload will automatically include - the nRF24L01's :py:attr:`~pyrf24.rf24.RF24.pa_level` in the + the nRF24L01's :py:attr:`~pyrf24.RF24.pa_level` in the advertisement. The default value of `False` will exclude this optional information.