Simple Relay Network <NWK_SIMPLE>

A simple relay network

This is a network behavior implementing a simple relay network.

auto&& nwksmpl = the_twelite.network.use<NWK_SIMPLE>();
nwksmpl << NWK_SIMPLE::logical_id(0xFE)
        << NWK_SIMPLE::repeat_max(3);

The above is an example of network usage declaration and configuration. The basic concept of network addresses and other fundamental content will be explained first, with details provided later.

For actual usage examples, please see Explanation of Sample Acts.

Each wireless station in this network is identified by an 8-bit logical ID. This value is independently set by each wireless station at startup. Logical IDs can be duplicated, but communication must be conducted assuming duplication.

Set the ID of each wireless station. Usually, the network consists of a wireless station acting as a parent and wireless stations acting as children. It is also possible to operate a network with only child stations.

Child stations also serve as relay stations.

Wireless Station ID	Role
`0x00`	Parent Station
`0x01`..`0xEF`	Child Station
`0xFE`	Child Station without assigned ID

Logical IDs can be specified as destinations, but 0xFE and 0xFF have special meanings. The following table summarizes destination specifications.

Destination ID	Meaning
`0x00`	Specifies the parent from a child. Invalid when specified from the parent.
`0x01`..`0xEF`	Specifies a specific child station.
`0xFE`	Broadcast to all child stations.
`0xFF`	Broadcast to all wireless stations.

Also, a 32-bit serial number can be used to identify wireless stations.

Packet delivery uses IEEE802.15.4 broadcast. Since ACK is not used, the sender cannot determine delivery success, but an appropriate number of retries is set to achieve the required success rate. If confirmation of arrival is necessary, normal packet communication is used.

For large-scale or frequent communication, this may seem inefficient, but it can be more efficient in networks primarily performing data collection with relatively few relay hops.

Also, since communication for network construction is not required, communication stopping entirely due to failures or exceptional situations is theoretically less likely. If the parent station is in receive mode and within wireless range of the child station, and the child station transmits packets, the parent can receive them in most cases. Networks requiring communication for construction must complete communication to re-establish connection after configuration information is lost. The network behavior <NWK_SIMPLE> is named “simple” for this reason.

To operate this simple network, it is often necessary to ignore multiple received retransmitted packets (identical packets). Identification of identical packets in <NWK_SIMPLE> is done using the sender’s serial number and the packet sequence number (called the duplicate checker). The sequence number ranges from 0 to 63 and is assigned sequentially, assuming packets received close in time have close sequence numbers. Sequence numbers considered distant after a certain timeout are excluded from duplication checks.

Considerations for the duplicate checker are as follows.

Under typical conditions (e.g., relay hops of 3 or less and fewer than 10 packets per second from each station), no special considerations are necessary.

Number of elements that can be checked (increasing this increases memory usage and processing time)
Timeout settings

By default, the timeout is 1 second, and the number of wireless stations checked is 16. That means packets relayed around and older than 1 second are no longer considered duplicates. If packets arrive from more than 16 stations in a short time, duplicate checks cannot be performed for the excess stations.

If there are many relay stations or retransmissions occur at very long intervals, settings may need to be considered.

Declaration and Registration

An example of using the network behavior <NWK_SIMPLE>.

##include <TWELITE>
##include <NWK_SIMPLE>

void setup() {
  ...

  auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
}

Line 2 includes the definition of <NWK_SIMPLE>. Line 7 registers <NWK_SIMPLE> with the_twelite.

Configuration

Configure after registering <NWK_SIMPLE>.

void setup() {
  auto&& nwksmpl = the_twelite.network.use<NWK_SIMPLE>();
  nwksmpl << NWK_SIMPLE::logical_id(0xFE);
}

Configuration is done using the << operator.

`<<` Operator (Configuration)

The << operator is used to perform initial settings on the object the_twelite.

The following configuration class objects are used as inputs. If not configured, default values apply.

`NWK_SIMPLE::logical_id(uint8_t id)`

Sets the logical device ID specified by parameter id. Default is 0xFE (child without assigned ID).

`NWK_SIMPLE::retry_default(uint8_t val)`

Sets the default number of retransmissions on send to the value specified by val.

`NWK_SIMPLE::repeat_max(uint8_t val)`

Sets the maximum relay count to the value specified by val. Default is 2.

Specify 0 to disable relaying.

If the receive circuit is disabled, the TWELITE wireless microcontroller cannot receive wireless packets, so relay operation will naturally not occur.

`NWK_SIMPLE::dup_check(uint8_t maxnodes, uint16_t timeout_ms, uint8_t tickscale)`

Parameters for the duplicate packet detection algorithm.

Consideration is necessary if there are many relay hops or retransmission intervals are long, but no configuration changes are needed for typical use.

maxnodes is the number of wireless stations (nodes) whose history is kept. If set too low, duplicate exclusion will fail for nodes exceeding this number in a short time, causing multiple data receptions or excessive retransmissions. Default is 16. Each node consumes 21 bytes of memory.
timeout_ms is the timeout in milliseconds before history is erased. Timeout is managed in sequence number blocks and processed per block. Default is 1000 ms.
tickscale is the time unit for timeout management, 2^tickscale ms. Time is managed with 7 bits, so set so that 127*(2^tickscale) > timeout_ms. Default is 5 (32 ms).

`NWK_SIMPLE::secure_pkt(const uint8_t *pukey, bool b_recv_plain_pkt = false)`

Enables encrypted packets.

pukey specifies the encryption key as 16 bytes (128 bit).
b_recv_plain_pkt set to true allows receiving plaintext packets with the same application ID and channel.

Whether a packet is plaintext or not can be determined by packet_rx::is_secure_pkt(), which returns true (encrypted) or false (plaintext).

`STG_STD`

Reflects interactive mode settings. The following values are applied.

auto&& set = the_twelite.settings.use<STG_STD>();
auto&& nwk = the_twelite.network.use<NWK_SIMPLE>();
...
set.reload(); // Load settings
nwk << set;   // Apply interactive mode settings

logical_id
retry_default

Methods

`prepare_tx_packet()`

// The type name is packet_tx_nwk_simple<NWK_SIMPLE>, but auto&& is used here.
auto&&  preare_tx_packet()

// Example
if (auto&& pkt =
  the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {
  ...
  pkt.transmit();
}

Obtains a transmission object. The object is derived from packet_tx. This object stores the transmission address and payload and sends packets with the .transmit() method.

This object has a bool operator. If TWENET cannot accept the transmission request at object creation, it returns false.

Transmission Object

Methods of the transmission object obtained by .prepare_tx_packet().

`bool` Operator

operator bool()

// Example
if (auto&& pkt =
  the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {

Returns false if TWENET cannot accept the transmission request at object creation.

`transmit()`

MWX_APIRET transmit()

// Example
uint8_t txid;

if (auto&& pkt =
  the_twelite.network.use<NWK_SIMPLE>().prepare_tx_packet()) {

  ...

  MWX_APIRET ret = pkt.transmit();
  if (ret) {
    txid = pkt.get_value();
  }
}

Performs packet transmission. MWX_APIRET is true if the transmission request succeeds, but the transmission process does not start at this point.

The packet transmission ID is stored in the value part obtained by .get_value() of MWX_APIRET. Transmission completion can be confirmed by the_twelite.tx_status.is_complete() or transmit_complete().

Maximum Packet Length and Structure

The maximum packet length is shown below. When the destination is LID (logical device ID), up to 91 bytes can be included without encryption.

Network Layer	Encryption	Maximum Payload
`<NWK_SIMPLE>`	None	91
`<NWK_SIMPLE>`	Enabled	89

Two bytes are reserved for future use. Users may use these reserved bytes if desired.

The packet structure is as follows.

|MacH:XX[........................................]MacF:2|
         TWENET:3[.....................]TwenetF:1
                  NWK_SIMPLE:11|PAYLOAD
                                        (:n is bytes)

1: MacH is the IEEE802.15.4 MAC header information
2: TwenetH is information for TWENET identification
3: NWK_SIMPLE is NWK_SIMPLE network control information
  |Type:1|Src LID:1|Src Addr:4|Dest LID:1|Dst Addr:4|Repeat:1|
4: PAYLOAD is the payload
5: TwenetF is the CRC8 checksum (for TWENET packet discrimination)
6: MacF is the CRC16 MAC layer checksum

Simple Relay Network <NWK_SIMPLE>

Declaration and Registration

Configuration

<< Operator (Configuration)

NWK_SIMPLE::logical_id(uint8_t id)

NWK_SIMPLE::retry_default(uint8_t val)

NWK_SIMPLE::repeat_max(uint8_t val)

NWK_SIMPLE::dup_check(uint8_t maxnodes, uint16_t timeout_ms, uint8_t tickscale)

NWK_SIMPLE::secure_pkt(const uint8_t *pukey, bool b_recv_plain_pkt = false)

STG_STD

Methods

prepare_tx_packet()

Transmission Object

bool Operator

transmit()

Maximum Packet Length and Structure

`<<` Operator (Configuration)

`NWK_SIMPLE::logical_id(uint8_t id)`

`NWK_SIMPLE::retry_default(uint8_t val)`

`NWK_SIMPLE::repeat_max(uint8_t val)`

`NWK_SIMPLE::dup_check(uint8_t maxnodes, uint16_t timeout_ms, uint8_t tickscale)`

`NWK_SIMPLE::secure_pkt(const uint8_t *pukey, bool b_recv_plain_pkt = false)`

`STG_STD`

`prepare_tx_packet()`

`bool` Operator

`transmit()`