# Network Topology¶

## Network Levels¶

Because of the hardware limitation’s of the nRF24L01 transceiver, each network is arranged in a levels where a parent can have up to 5 children. And each child can also have up to 5 other children. This is not limitless because this network is designed for low-memory devices. Consequently, all node’s Logical Address are limited to 12-bit integers and use an octal counting scheme.

• The master node (designated with the Logical Address `0o0`) is always the only node in the lowest level (denoted as level 0).

• Child nodes are designated by the most significant octal digit in their Logical Address. A child node address’ least significant digits are the inherited address of it’s parent node. Nodes on level 1 only have 1 digit because they are children of the master node.

Hopefully, you should see the pattern. There can be up to a maximum of 5 network levels (that’s 0-4 ordered from lowest to highest).

For a message to travel from node `0o124` to node `0o3`, it must be passed through any applicable 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 `channel`), but for readability reasons, the following graph only demonstrates

• the master node (level 0) and it’s 5 children (level 1)

• level 2 only shows the 1st and 2nd children of parents on level 1

• level 3 only shows the 3rd and 4th children of parents on level 2

• level 4 only shows the 5th children of parents on level 3

• The Physical address is the 5-byte address assigned to the radio’s data pipes.

• The Logical address is the 12-bit integer representing a network node. The Logical address uses an octal counting scheme. A valid Logical Address must only contain octal digits in range [1, 5]. The master node is the exception for it uses the number `0`

Tip

Use the `is_address_valid()` function to programmatically check a Logical Address for validity.

Note

Remember that the nRF24L01 only has 6 data pipes for which to receive or transmit. Since only data pipe 0 can be used to transmit, the other other data pipes 1-5 are devoted to receiving transmissions from other network nodes; data pipe 0 also receives multicasted messages about the node’s network level).

### Translating Logical to Physical¶

Before translating the Logical address, a single byte is used repetitively as the base case for all bytes of any Physical Address. This byte is the address prefix (stored internally and unexposed) in the `RF24Network` class. By default the address prefix has a single byte value of `0xCC`.

The `RF24Network` class also has a predefined internal (unexposed) array of bytes used for translating unique Logical addresses into unique Physical addresses. This list is called address suffix. By default the address suffix has 6-byte value of `{ 0xC3, 0x3C, 0x33, 0xCE, 0x3E, 0xE3 }` where the order of bytes pertains to the data pipe number and child node’s most significant byte in its Physical Address.

For example:

The Logical Address of the network’s master node is `0`. The radio’s pipes 1-5 start with the address prefix. To make each pipe’s Physical address unique to a child node’s Physical address, the address suffix is used.

The Logical address of the master node: `0o0`

pipe

1

`CC CC CC CC 3C`

2

`CC CC CC CC 33`

3

`CC CC CC CC CE`

4

`CC CC CC CC 3E`

5

`CC CC CC CC E3`

The Logical address of the master node’s first child: `0o1`

pipe

1

`CC CC CC 3C 3C`

2

`CC CC CC 3C 33`

3

`CC CC CC 3C CE`

4

`CC CC CC 3C 3E`

5

`CC CC CC 3C E3`

The Logical address of the master node’s second child: `0o2`

pipe

1

`CC CC CC 33 3C`

2

`CC CC CC 33 33`

3

`CC CC CC 33 CE`

4

`CC CC CC 33 3E`

5

`CC CC CC 33 E3`

The Logical address of the master node’s third child’s second child’s first child: `0o123`

pipe

1

`CC 3C 33 CE 3C`

2

`CC 3C 33 CE 33`

3

`CC 3C 33 CE CE`

4

`CC 3C 33 CE 3E`

5

`CC 3C 33 CE E3`

## 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 `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).

Important

Any network that will use RF24mesh for a child node needs to have a RF24Mesh master node. This will not interfere with RF24Network nodes since the RF24Mesh API is layered on top of the RF24Network API.

To better explain the difference between a node’s `mesh_address` vs a node’s `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 `node_id` (which is limited to the range [0, 255]).

Hint

Remember that `0` is reserved the master node’s `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 high) if this process fails.

3. When a polling transmission is responded, the connecting mesh node sends an address request which gets forwarded to the master node when necessary (using a `NETWORK_REQ_ADDRESS` message).

4. The master node will process the address request and respond with a `mesh_address` (using a `NETWORK_ADDR_RESPONSE` message). If there is no available occupancy on the network level from which the address request originated, then the master node will 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 `node_id`.

### Points of failure¶

This process happens over a span of a few milliseconds. However,

• If the connecting node is physically moving throughout the network very quickly, then this process will take longer and is likely to fail.

• If a master node is able to respond faster than the connecting node can prepare itself to receive, then the process will fail entirely. This failure about faster master nodes often results in some slower RF24Mesh nodes only being able to connect to the network through another non-master node.

If you run into trouble with this connection process, then please open an issue on github and describe the situation with as much detail as possible.