Add NRF52x info to docs (#230)

* Add NRF52x info to docs * Docs: Add MAX_FRAME_SIZE adjustment * Add MAX_FRAME_SIZE to adv config * Add links to encryption examples per @2bndy5 Co-authored-by: Brendan <[email protected]> * update doxygen CSS and use v1.11.0 --------- Co-authored-by: Brendan <[email protected]>
nRF24 · Jun 23, 2024 · c81cf1f · c81cf1f
1 parent 970ae24
commit c81cf1f
Show file tree

Hide file tree

Showing 6 changed files with 139 additions and 56 deletions.
diff --git 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
@@ -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
@@ -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
@@ -2,106 +2,165 @@ 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 */
 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,<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>');
+  --note-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-280q17 0 28.5-11.5T520-320v-160q0-17-11.5-28.5T480-520q-17 0-28.5 11.5T440-480v160q0 17 11.5 28.5T480-280Zm0-320q17 0 28.5-11.5T520-640q0-17-11.5-28.5T480-680q-17 0-28.5 11.5T440-640q0 17 11.5 28.5T480-600Zm0 520q-83 0-156-31.5T197-197q-54-54-85.5-127T80-480q0-83 31.5-156T197-763q54-54 127-85.5T480-880q83 0 156 31.5T763-763q54 54 85.5 127T880-480q0 83-31.5 156T763-197q-54 54-127 85.5T480-80Zm0-80q134 0 227-93t93-227q0-134-93-227t-227-93q-134 0-227 93t-93 227q0 134 93 227t227 93Zm0-320Z"/></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>');
+  --remark-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-80q-33 0-56.5-23.5T400-160h160q0 33-23.5 56.5T480-80ZM360-200q-17 0-28.5-11.5T320-240q0-17 11.5-28.5T360-280h240q17 0 28.5 11.5T640-240q0 17-11.5 28.5T600-200H360Zm-30-120q-69-41-109.5-110T180-580q0-125 87.5-212.5T480-880q125 0 212.5 87.5T780-580q0 81-40.5 150T630-320H330Zm24-80h252q45-32 69.5-79T700-580q0-92-64-156t-156-64q-92 0-156 64t-64 156q0 54 24.5 101t69.5 79Zm126 0Z"/></svg>');
+  --attention-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-280q17 0 28.5-11.5T520-320q0-17-11.5-28.5T480-360q-17 0-28.5 11.5T440-320q0 17 11.5 28.5T480-280Zm0-160q17 0 28.5-11.5T520-480v-160q0-17-11.5-28.5T480-680q-17 0-28.5 11.5T440-640v160q0 17 11.5 28.5T480-440ZM363-120q-16 0-30.5-6T307-143L143-307q-11-11-17-25.5t-6-30.5v-234q0-16 6-30.5t17-25.5l164-164q11-11 25.5-17t30.5-6h234q16 0 30.5 6t25.5 17l164 164q11 11 17 25.5t6 30.5v234q0 16-6 30.5T817-307L653-143q-11 11-25.5 17t-30.5 6H363Zm1-80h232l164-164v-232L596-760H364L200-596v232l164 164Zm116-280Z"/></svg>');
+  --important-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-360q17 0 28.5-11.5T520-400q0-17-11.5-28.5T480-440q-17 0-28.5 11.5T440-400q0 17 11.5 28.5T480-360Zm0-160q17 0 28.5-11.5T520-560v-160q0-17-11.5-28.5T480-760q-17 0-28.5 11.5T440-720v160q0 17 11.5 28.5T480-520ZM240-240l-92 92q-19 19-43.5 8.5T80-177v-623q0-33 23.5-56.5T160-880h640q33 0 56.5 23.5T880-800v480q0 33-23.5 56.5T800-240H240Zm-34-80h594v-480H160v525l46-45Zm-46 0v-480 480Z"/></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>');
   --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,
 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%);
 }
diff --git 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
@@ -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