diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index c0f5af6b..ad16a9c3 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -32,5 +32,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' + doxygen-version: '1.11.0' secrets: inherit diff --git a/docs/addressing.md b/docs/addressing.md index 30814363..bd0bfd7b 100644 --- a/docs/addressing.md +++ b/docs/addressing.md @@ -11,6 +11,9 @@ The nrf24 radio modules typically use a 40-bit address format, requiring 5-bytes array of addresses to be utilized. In addition, the radios are limited to direct communication with 6 other nodes while using the Enhanced-Shock-Burst (ESB) functionality of the radios. +The NRF52x modules use a similar format for addressing, but can communicate directly with 8 other nodes while using the +Enhanced-Shock-Burst (ESB) functionality of the radios. + RF24Network uses a simple method of data compression to store the addresses using only 2 bytes, in a format designed to represent the network topology in an intuitive way. See the [Topology and Overview](tuning.md) page for more info regarding topology. @@ -35,6 +38,9 @@ support 4 nodes (01n to 04n etc), 1 multicast address and 1 parent pipe. Users c `#define RF24NetworkMulticast` as well. This allows the master to support 5 children, with nodes supporting 5 children also. See the [Topology and Overview](md_docs_tuning.html) page for more info regarding topology. +With the newer NRF52x devices, the master node will support 7 nodes (01 through 07) and 1 multicast address, while the nodes +themselves support 6 nodes (01n to 06n etc), 1 multicast address and 1 parent pipe. + ### Decimal, Octal and Binary | Decimal | Octal | Binary | diff --git a/docs/advanced_config.md b/docs/advanced_config.md index 8dd4d845..1439a987 100644 --- a/docs/advanced_config.md +++ b/docs/advanced_config.md @@ -13,3 +13,5 @@ RF24Network offers many features, some of which can be configured by editing the | `#define DISABLE_USER_PAYLOADS` | This option will disable user-caching of payloads entirely. Use with RF24Ethernet to reduce memory usage. (TCP/IP is an external data type, and not cached) | | `#define ENABLE_SLEEP_MODE` | Uncomment this option to enable sleep mode for AVR devices. (ATTiny,Uno, etc) | | `#define ENABLE_NETWORK_STATS` | Enable counting of all successful or failed transmissions, routed or sent directly | +| `#define NUM_PIPES` | Define the number of pipes for addressing. The max value is generally hardware dependant. NRF24 supports 6 pipes, NRF52x supports 8 pipes | +| `#define MAX_FRAME_SIZE` | Found in RF24Network.h, this allows users to set the maximum frame size used internally. NRF24 supports 32-bytes, NRF52x supports 123-bytes, or 111 if encryption is enabled | diff --git a/docs/doxygen-custom.css b/docs/doxygen-custom.css index 2b5ef5a1..4a3c469c 100644 --- a/docs/doxygen-custom.css +++ b/docs/doxygen-custom.css @@ -2,33 +2,74 @@ table.markdownTable th { color: unset; } -/* overrides from default CSSS for some admonitions */ -dl.note, dl.remark, -dl.warning, dl.attention { +/* overrides from default CSS for some admonitions */ +dl.note, +dl.remark, +dl.warning, +dl.attention, +dl.important, +dl.deprecated, +dl.see { color: unset; + box-shadow: 5px 5px 5px hsla(0, 0%, 19.2%, 0.5); } + dl.remark { - background: var(--remark-color-bg); - border-left: 8px solid var(--remark-color-hl); + background: var(--remark-color-bg); + border-left: 8px solid var(--remark-color-hl); } + dl.remark dt { - color: var(--remark-color-hl); + color: var(--remark-color-hl); +} + +dl.important dt { + color: var(--important-color-hl); +} + +dl.important { + background: var(--important-color-bg); + border-left: 8px solid var(--important-color-hl); +} + +dl.attention dt { + color: var(--attention-color-hl); +} + +dl.attention { + background: var(--attention-color-bg); + border-left: 8px solid var(--attention-color-hl); +} + +dl.deprecated dt { + color: var(--deprecated-color-hl); +} + +dl.deprecated { + background: var(--deprecated-color-bg); + border-left: 8px solid var(--deprecated-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); + background: var(--seealso-color-bg); + border-left: 8px solid var(--seealso-color-hl); } + dl.see dt { - color: var(--seealso-color-hl); + color: var(--seealso-color-hl); } + dl.see { padding: 10px; - margin: 10px 0px; - overflow: hidden; - margin-left: 0; - border-radius: 4px; + margin: 10px 0px; + overflow: hidden; + margin-left: 0; + border-radius: 4px; +} + +dl.see dd { + margin-left: 0; } /* admonition icons */ @@ -36,72 +77,90 @@ 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.important dt::before { + background-color: var(--important-color-hl); + mask-image: var(--important-icon); +} + +dl.attention dt::before { + background-color: var(--attention-color-hl); + mask-image: var(--attention-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; +dl.deprecated dt::before, +dl.important dt::before, +dl.attention 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 { +dl.deprecated dt, +dl.important dt, +dl.attention dt { margin-top: -0.35em; margin-bottom: 0.5em; } /* icon SVG data */ *:root { - --note-icon: url('data:image/svg+xml;utf8,'); - --seealso-icon: url('data:image/svg+xml;utf8,'); + --note-icon: url('data:image/svg+xml;utf8,'); --warning-icon: url('data:image/svg+xml;utf8,'); - --remark-icon: url('data:image/svg+xml;utf8,'); + --remark-icon: url('data:image/svg+xml;utf8,'); + --attention-icon: url('data:image/svg+xml;utf8,'); + --important-icon: url('data:image/svg+xml;utf8,'); + --seealso-icon: url('data:image/svg+xml;utf8,'); --deprecated-icon: url('data:image/svg+xml;utf8,'); } /* 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, 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%); + --note-color-hl: hsl(213.7, 92.8%, 62%); + --note-color-bg: hsla(213.7, 92.8%, 62%, 12.5%); + --warning-color-hl: hsl(40.6, 72.1%, 47.8%); + --warning-color-bg: hsla(40.6, 72.1%, 47.8%, 12.5%); + --attention-color-hl: hsl(2.7, 92.6%, 62.9%); + --attention-color-bg: hsla(2.7, 92.6%, 62.9%, 12.5%); + --deprecated-color-hl: hsl(0, 0%, 47%); + --deprecated-color-bg: hsla(0, 0%, 47%, 12.5%); + --seealso-color-hl: hsl(323, 72%, 52%); + --seealso-color-bg: hsla(323, 72%, 52%, 12.5%); + --remark-color-hl: hsl(128.4, 49.2%, 48.6%); + --remark-color-bg: hsla(128.4, 49.2%, 48.6%, 12.5%); + --important-color-hl: hsl(262.4, 89.8%, 73.1%); + --important-color-bg: hsla(262.4, 89.8%, 73.1%, 12.5%); } \ No newline at end of file diff --git a/docs/main_page.md b/docs/main_page.md index 7edadb06..55a7174b 100644 --- a/docs/main_page.md +++ b/docs/main_page.md @@ -97,7 +97,7 @@ Please see the recent changes listed in [the github releases page](https://githu ## Topology for Mesh Networks using nRF24L01(+) This network layer takes advantage of the fundamental capability of the nRF24L01(+) radio to -listen actively to up to 6 other radios at once. The network is arranged in a +listen actively to up to 6 other radios at once (8 with NRF52x). The network is arranged in a [Tree Topology](http://en.wikipedia.org/wiki/Network_Topology#Tree), where one node is the base, and all other nodes are children either of that node, or of another. Unlike a true mesh network, multiple nodes are not connected together, so there is only one @@ -116,6 +116,7 @@ digit in the address represents a position in the tree further from the base. - The largest node address is 05555, so up to 781 nodes are allowed on a single channel. An example topology is shown below, with 5 nodes in direct communication with the master node, and multiple leaf nodes spread out at a distance, using intermediate nodes to reach other nodes. +- With the newer NRF52x devices, up to 3200 nodes are allowed on a single channel @image html example_tree.svg diff --git a/docs/tuning.md b/docs/tuning.md index 7b895309..401e11a5 100644 --- a/docs/tuning.md +++ b/docs/tuning.md @@ -22,16 +22,17 @@ Retrying failed payloads over and over on a radio network can hinder communicati reduce throughput and errors on routing nodes. Radios in this network are linked by **addresses** assigned to **pipes**. Each radio can listen -to 6 addresses on 6 pipes, therefore each radio has a parent pipe and 4-5 child pipes, which are used -to form a tree structure. Nodes communicate directly with their parent and children nodes. Any other +to 6 addresses on 6 pipes, (8 pipes on NRF52x) therefore each radio has a parent pipe and 4-5 child pipes, which are +used to form a tree structure. Nodes communicate directly with their parent and children nodes. Any other traffic to or from a node must be routed through the network. ## Topology of RF24Network Anybody who is familiar at all with IP networking should be able to easily understand RF24Network topology. The -master node can be seen as the gateway, with up to 4 directly connected nodes. Each of those nodes creates a -subnet below it, with up to 4 additional child nodes. The numbering scheme can also be related to IP addresses, -for purposes of understanding the topology via subnetting. Nodes can have 5 children if multicast is disabled. +master node can be seen as the gateway, with (by default) up to 5 directly connected nodes. Each of those nodes +creates a subnet below it, with up to 4 additional child nodes. The numbering scheme can also be related to IP +addresses, for purposes of understanding the topology via subnetting. Nodes can have 5 children if multicast is +disabled. ### Expressing RF24Network addresses in IP format @@ -47,12 +48,12 @@ In RF24Network, the master is just `00` ## Multicast -Multicast is enabled by default, which limits the master node to 5 child pipes and other nodes to 4. Nodes are -arranged in multicast 'levels' with the master node being level 0, nodes 01-05 are level 1, nodes n1-n5 are level 2, -and so on. The multicast level of each node can be configured as desired by the user, or multicast can be -disabled by editing RF24Network_config.h. For example, if all nodes are in range of the master node, all nodes can -be configured to use multicast level 1, allowing the master node to contact all of them by sending a single payload. -Multicasting is also used by the RF24Mesh layer for dynamic addressing requests. +Multicast is enabled by default, which limits the master node to 5 child pipes and other nodes to 4 when using RF24 +modules. Nodes are arranged in multicast 'levels' with the master node being level 0, nodes 01-05 are level 1, nodes +n1-n5 are level 2, and so on. The multicast level of each node can be configured as desired by the user, or +multicast can be disabled by editing RF24Network_config.h. For example, if all nodes are in range of the master node, +all nodes can be configured to use multicast level 1, allowing the master node to contact all of them by sending a +single payload. Multicasting is also used by the RF24Mesh layer for dynamic addressing requests. ## Routing @@ -120,6 +121,20 @@ network.txTimeout variable. Timeout periods of extended duration (500+) will gen are failing due to data collisions, it will only extend the duration of the errors. Extended duration timeouts should generally only be configured on leaf nodes that do not receive data. +## Usage with NRF52x devices + +1. Users can utilize large payloads by calling `radio.begin();` then `radio.enableDynamicPayloads(123);` + prior to calling `network.begin();`. Users would also need to edit RF24Network.h and set + MAX_FRAME_SIZE to a maximum of 111 if encryption is enabled, 123 without encryption. +2. Users can allow more nodes by modifying RF24Network_config.h and setting NUM_PIPES to 8 (Allows + master to have 7 child nodes, other nodes can have 6 children by default) +3. The MAX_PAYLOAD_SIZE is also defined in RF24Network_config.h. Raise to a multiple of 123 to allow + multiple large payloads to be cached in memory. + +@see +- [RX example using encryption](https://github.com/TMRh20/nrf_to_nrf/blob/main/examples/RF24Network/helloworld_rxEncryption/helloworld_rxEncryption.ino) +- [TX example using encryption](https://github.com/TMRh20/nrf_to_nrf/blob/main/examples/RF24Network/helloworld_txEncryption/helloworld_txEncryption.ino) + ## Scenarios ### Example 1