Network Behavior (NWK)

• 1: Simple Relay Network <NWK_SIMPLE>
• 2: <NWK_LAYERED>

1 - Simple Relay Network <NWK_SIMPLE>

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.

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.

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

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.

• 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.

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

Parameters for the duplicate packet detection algorithm.

• 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.

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.

• 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

2 - <NWK_LAYERED>

Initialize in setup() as follows. Assign the role as a parent using NWK_LAYERED::ROLE_PARENT.

##include <NWK_LAYERED>
void setup() {
  ...
  auto&& nwk_ly = the_twelite.network.use<NWK_LAYERED>();
  nwk_ly << NWK_LAYERED::network_role(NWK_LAYERED::ROLE_PARENT);
            // set a role as parent.
}

When a packet is received, on_rx_packet() is called similarly to NWK_SIMPLE.

void on_rx_packet(packet_rx& rx, bool_t &handled) {
  auto type = rx.get_network_type();

  if (type == mwx::NETWORK::LAYERED) {
    ; // Packet of layered tree network
    handled = true; // Mark as handled
  }
}

rx is a class that wraps packet information. Internally, except for setting an internal flag for the processing of _get_network_type(), no modification of packet information is performed.

In other words, by referring to rx.get_psRxDataApp(), which returns tsRxDataApp*, you can obtain the same packet information as in the TWENET C library. packet_rx defines some procedures to access this information, but the information obtained does not change.

Using with NWK_SIMPLE

When used together with NWK_SIMPLE, assign NWK_LAYERED to the_twelite.network and NWK_SIMPLE to the_twelite.network2.

##include <NWK_LAYERED>
##include <NWK_SIMPLE>

void setup() {
    ...
	auto&& nwk_ly = the_twelite.network.use<NWK_LAYERED>();
	auto&& nwk_sm = the_twelite.network2.use<NWK_SIMPLE>();
}

void on_rx_packet(packet_rx& rx, bool_t &handled) {
  auto type = rx.get_network_type();

  if (type == mwx::NETWORK::LAYERED) {
      ; // Packet of layered tree network
  }
  else if (type == mwx::NETWORK::SIMPLE) {
      ; // Packet of NWK_SIMPLE
  }
  else if (type == mwx::NETWORK::NONE) {
      ; // Normal app (such as App_Twelite)
  }
  else {
      ; // Uninterpretable packet
  }

  // Mark the packet as handled, and prevent further intervention by the MWX library.
  handled = true;
}

Each packet type is identified by .get_network_type() as shown above.

• mwx::NETWORK::LAYERED : Refer to the packet information as is.
• mwx::NETWORK::SIMPLE : Follow the processing of NWK_SIMPLE.
• mwx::NETWORK::NONE : No network processing or duplicate packet handling is performed. For example, in the standard App_Twelite application, three packets including retransmissions are sent per transmission. If all packets are successfully received, on_rx_packet() will be called three times. Usually, receiving three times does not mean the data from the 2nd and 3rd receptions is needed. You need to add processing for duplicate packets.

For examples, please refer to Act_Samples Rcv_Univsl. It handles reception of packets with the same wireless channel and application ID but different types in TWELITE PAL, Act_samples, and App_Twelite. Additionally, duplicate check processing is provided for App_Twelite.