Introduction

The Connect stack supports OTA distribution of firmware images, both server, and client available as plugins. The usual method of uploading the image to the server device is to connect the J-Link adapter and upload the image the same way as in case of any other firmware images - which requires to stop the server device during the upload process and restart after the images are uploaded. However exploiting the capabilities of the Gecko bootloader, it is possible to upload images during normal operation. The following example implements an XMODEM protocol based uploader using built-in APIs.

Prerequisites

The described method and the provided method applicable for any Connect based application with any EFR32 device which supports Connect, this article uses Connect (SoC): Empty Example. This project also needs a properly configured Gecko bootloader which will provide the necessary API for the flash operations. In this example, we will use BRD4255A radio board. The user has to have a serial terminal emulator software that supports sending files using the XMODEM protocol.

Prepare the bootloader

There are multiple bootloaders available through the Simplicity Studio wizard - we need to use one which matches the flash memory size of the chosen device:

The default configuration of the bootloader is suitable for the current project, we only need to compile and upload to the device. Note: Gecko bootloader is a two stage bootloader always use the firmware image which contains -combined in its filename (bootloader-storage-internal-single-512k-combined.s37 in this case).

Prepare the application

Open the Connect (SoC): Empty Example through Simplicity Studio project wizard:

Select the Application bootloader in the AppBuilder on the HAL tab:

The complete example enables several plugins and options for working with CLI which are not detailed here as their description is out of the scope of this document, but the attached files configured properly. However, to be able to interact with the bootloader the following plugins should be enabled:

When the setting is done in AppBuilder and the files are generated, the next step is implementing the code in the flex-callbacks.c. Just as the settings in AppBuilder, the complete code is not described in this document, but further Connect documentation and resources can be found in Connect online documentation and Connect tutorial series.

The XMODEM protocol handling and the bootloader / flash memory related operations implemented in the xmodem-load-image.c and xmodem-load-image.h files (attached). These files should be added to the project (in the xmodem-load-image directory, but it can be placed anywhere but the header file must be in the include path).

The implementation contains only one public function: xmodemLoadImage(). This function handles both XMODEM upload and writing the incoming data chunks into the flash. The implementation follows the XMODEM protocol, but it does not support re-sending packets in case of failure. If any failure happens during upload, the whole process must be started from the beginning (including erasing the flash memory).

Completing the steps above, compile and run the firmware.

Note: do not use full erase on the device, just upload the application firmware, otherwise the bootloader may be erased as well.

Testing the application

If everything went well, a CLI interface should be available where the user can issue the necessary commands.

The first step is executing the flash initialization by issuing the command bootloader init. Initialization should be called once, when the application started / restarted, no subsequent initialization is necessary.

connect_xmodem_bootloader>bootloader init
bootloader init succeeded!

Then, if the image storage is not in the erased state, it must be erased by bootloader flash-erase:

connect_xmodem_bootloader>bootloader flash-erase
flash erasing slot 0 started
......................................................................................................................
flash erase successful!

Image storage always has to be erased before uploading an image. This means, if an upload was unsuccessful the erase command must be executed prior to any further uploads.

If the initialization was successful and the image storage is erased, the image upload can be started by the xmodem-load-image command. It has no parameters, as the image filename has to be specified at the host (PC) side and the end of the upload process (i.e. the length of the image) is determined by the host as well.

So, issue the xmodem-load-image command and select the file to upload.

If the upload was successful, the following messages should appear on the console:

connect_xmodem_bootloader>xmodem-load-image
CCCC
download successfully completed
connect_xmodem_bootloader>

The XMODEM uploader does not check if the uploaded image is valid. Issue the bootloader validate-image command validates the image:

connect_xmodem_bootloader>bootloader validate-image
Verifying image............................................................................................................................................................done!
Image is valid!

Conclusion

Although, the Connect does not support uploading OTA images from application directly, the way to implement is fairly easy and straightforward.

The Si4133 AUXOUT should not be treated as an SPI MISO line. The Si4133 has a 3-wire serial interface but it is not SPI.  It does not support slave out data on the bus.

To read data from the part, you have to write special test instructions to the device, and then read them out AUXOUT. However, AUXOUT is not a true SPI MISO line.

Further, there are no test modes where AUXOUT can be set to tristate to a high impedance as would be required on a bus. 

Please note that this article is applicable to all Si41xx RF Synthesizers including Si4112, Si4113, Si4122, and Si4123 in addition to the Si4133. 

This series of tutorials demonstrates "the essentials" of building applications based on Silicon Labs Connect. The collection presents an incremental review of key techniques and features that help developers access the powerful convenience available thru Connect. These tutorials supplement the primary Connect resources below, which offer definitive documentation for the Connect developer:

• UG235: Silicon Labs Connect User's Guide Series (see full series index in Section 1)
• Connect Stack API Documentation

Note: The API reference above is the authoritative Connect resource, and represents the most current documentation at all times. Grant it priority in any conflicts you may encounter in the following (or any other) Connect guidance.

Prerequisites

We strongly recommend familiarity with the resources above (especially the User's Guide) before beginning Connect-based application development, as they provide insight on crucial decisions that impact the design phase of your project.

That said, each tutorial in this series walks you through important Connect concepts using accessible demonstrations and discussions that illuminate how you can make Connect work for you. To extract the most value from this tutorial series, programming experience in embedded C and (at least) a baseline understanding of of wireless networking theory is recommended.

Getting Started: Fundamentals

The series begins with this group of tutorials, which leads you from "square one", to performing packet analysis on traffic captured from firmware you've developed along the way. A Direct mode Connect-based application serves as the demonstration vehicle.

While this collection of fundamental concepts applies to all Connect developers, it should be noted that these first seven tutorials fully prepare a newcomer to develop Direct mode applications. Though the coverage spans a broad range of topics, they are designed to be completed sequentially:

1. Getting Started with Application Development
2. Communication Basics: Send and Receive
3. Command Line Interface
4. Communication Features: Acknowledge and Message Queue
5. Communication Features: Security
6. IEEE 802.15.4 Addressing
7. Traffic Analysis: Addressing, Acknowledgement, and Security

Note: Tutorial 6 is largely independent, and is immediately accessible as a strong subject matter reference.

Looking Ahead: Expanded Coverage

Additional tutorials are planned, and will be added to this space as they are completed. These will explore many other concepts, as well as address features exclusive to one or both of the two remaining Connect modes (Extended Star, MAC).

This is the seventh tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.

Previous tutorials incrementally constructed a Connect-based application that demonstrates sophisticated wireless communication features. In this tutorial, we closely examine how those features are encoded into message headers. To do so, we also introduce a powerful asset in the Connect developer toolkit: the Network Analyzer.

Preparations

To begin, install the application from the (Communication Features: Security) tutorial on two devices. To set up a connection, call commission 1 on device 1, and call commission 2 on device 2. To test the communication, call send 2 1 "message" 1 on device 1.

If you're using the Simplicity Studio Console to communicate with the devices, you may want to use a different terminal emulator for this tutorial as switching between the consoles and analyzer tool within Simplicity Studio will be difficult. We usually use TeraTerm or CuteCom, with 115200 8N1 settings, using CR/LF line termination.

Network Analyzer

In this tutorial (and others in the future), we'll use the Network Analyzer heavily, so we should first understand what it is: Network Analyzer is a tool to capture transmitted and received messages from an EFR32 device.

If you read that and assume it's a sniffer, you're correct - but it's a bit more capable than the average sniffer. Usually, a sniffer is a device that listens to a communication channel and prints every message it sees. This means you'll know that a message was transmitted, but you can't confirm if it was received or not. With Network Analyzer, both the transmitter and the receiver(s) will log the message. The Network Analyzer tool combines both of these information sources and presents the results, so you'll know if your message wasn't received for some reason. Network Analyzer can even tell you the RSSI (signal strength) measured by the receiver.

This is implemented through the Packet Trace Interface (PTI) hardware of the transceiver. It's basically a UART bus that encapsulates the frame on air into a proprietary protocol. This is than timestamped by the board controller of the WSTK (or your debugger), and sent to your computer, where Network Analyzer decodes it.

Note: RAIL can send additional information to the PTI interface; for example, Dynamic Multiprotocol Protocol Switch events are also logged.

Starting the Capture

Before starting the Network Analyzer, we should first set its decoder to use the Connect Stack. This isn't usually required (auto-detect is effective), but Connect is built on the same 802.15.4 as ZigBee, so specify Connect to make sure the messages won't be interpreted as ZigBee. To do that, go to the menu Window/Preferences, and select Network Analyzer/Decoding/Stack Versions. Select Connect stack in this window:

Now we can start the capture! Select both WSTKs under Debug Adapters, and select Connect after right-clicking on them:

If successful, you can right-click them again, and select Start capture:

This will start the capture, the Network Analyzer interface, and also switch to the Network Analyzer perspective in Studio.

Capture the First Packet

While the network analyzer is running, write send 2 1 "message" 1 on Device 1 a few times. This should result in messages popping up in the network analyzer. Before analyzing them, let's get familiar with the Network Analyzer itself:

1. Debug Adapters view - the same as that found on all perspectives in Studio.
2. Time scale - messages are represented here by vertical lines.
3. Network map - A graphical representation of the network topology. It's not too useful for connect, it's mostly designed for mesh networks.
4. Transactions - The transactions in the stack. It usually bundles a few messages together, e.g. in this case, a data frame and an ack.
5. Events - Each captured message (or other event) is shown here.
6. Radio Info - A message is usually captured on both the transmitter and the receiver, here you can see details for both.
7. Event Detail - The message is decoded here by Studio's decoder.
8. Hex Dump - The raw capture. It includes the framing required by Network Analyzer.

You'll often see Network Analyzer indicate "missing packets" for the last transaction for a while. This doesn't mean anything is actually missing, Network Analyzer is just waiting for packets that might continue the transaction.

You might also see messages appear out of order (e.g. an ACK before the message itself). This is caused by time synchronization problems between WSTKs. One workaround is to only capture from a single device - but that of course means you lose the ability to check both sides (Rx and Tx) of the message.

Analyzing a Simple Packet

To analyze a packet, select it under Events, and open the groups in Event Detail - let's select a Connect Network Data first:

At the highest level, you can see 3 major parts of the frame:

• IEEE 802.15.4, which includes the physical and mac layer header (PHR and MHR)
• Connect Network Frame, which is the header used by the Connect Network Layer
• Application Payload, which is our payload, "message"
• Radio Info EFR32, which includes the CRC (15.4 MAC footer) and additional information captured by the PTI interface, like the fact that transmit was successful

IEEE 802.15.4 Headers

PHY Header

The IEEE 802.15.4 headers (often stated as "15.4 headers") begin with the PHY header (PHR), which is the first byte. It only includes the packet length. The packet length value includes the CRC, but doesn't include the PHR itself.

So, our frame length is 10B+5B+7B+2B=24B (15.4 header; connect header; payload; CRC), which is exactly 1B more than what is stored in the PHR. Note that we used 24B to send a 7B string (not counting the preamble and sync word that preceded what is depicted here).

Frame Control Field

This is followed by the Frame controller field (FCF, 2Bytes). This defines what the stack should expect in the frame. In Connect Direct mode (which this example uses), only two FCF parameters are variable (ACK messages are an exception, as they're slightly different):

• Security Enabled - if enabled, the frame includes another header (Auxiliary Security Header), which controls what security mode is used
• Ack Required - as the name suggests, if it's set to true, the receiver should reply with an ACK frame

We will return to some of the other fields when using Connect in Extended Star or MAC mode.

So, as we see above, our frame is not secure, and we did request an ACK - you should see the ACK frame itself after the frame we're analyzing.

Sequence Number

Sequence number is a one byte field that increments on each transmit, and it is used by the ACK mechanism - we will return to this shortly.

Address Fields

The last 3 fields include: the PAN ID (configured during commissioning, PAN_ID in the tutorial source codes), the destination address, and the source address. The destination address is set by the first argument of emberMessageSend, while the source address is automatically set by the stack to the address we configured during commissioning.

These indicate this is a short addressed, intra PAN frame - which is the only data frame type supported by Connect in Direct mode (see Connect Tutorial 6 - IEEE 802.15.4 Addressing for details on addressing modes).

Connect Network Frame

The Connect Network Frame starts with its header:

• The frame type bit is not set, which means this is a data frame, and it will be sent to the application layer (command frames are handled by the stack).
• The endpoint we used is also included in the first byte
• The network frame also includes destination and source addresses; however, this part of the header is only used in Extended Star mode, so we'll ignore them for now.

This header is followed by the payload itself.

Radio Info

The last field of the packet is the radio info:

From this, only the CRC is transmitted over the air - everything else is information from the capture. E.g. in the above example we can see that this was a successfully transmitted frame (it is just copied from the MAC header)

ACK Mechanism

The next packet in the event flow should be an ACK:

As you can see, its length is only 6 Bytes (5 Bytes + PHR). It includes only:

• The PHR, i.e. the frame length (1B)
• The Frame Control Field (2B), where the only interesting part is that both addresses are disabled (Address Mode is set to None)
• The sequence number (1B)
• And the CRC (2B)

The sequence number is used to pair the ACK to the message it was sent in response to. If you check above, you can see that the sequence number is the same for the 2 messages.

Theoretically, the sequence number could be used to filter out repeated messages, but in practice, that's not feasible, and Connect doesn't do it. The main problem is that this is a single byte, which overflows quite quickly.

Frame without ACK

If you call set-tx-options 0 0, it will disable the ACK request. If you then try sending a packet using send 2 1 "message" 1, you'll see first that there are no ACKs. If you check one of the transmitted frame's headers, you will see something like this:

Note that the ACK Required bit is not set.

Security

To enable security (and re-enable ACKs), call set-tx-options 1 1. Now send some frames with send 2 1 "message" 1.

If you select one of the transmitted messages, you will see a note that it was encrypted with the "all A" key:

This means that the frame was encrypted, but Network Analyzer "knows" the key. This is because Network Analyzer is preconfigured with a few keys, and one of them is "all A". If you use some other key, you'll need to add it to Network Analyzer using the key configuration window, accessed by the key icon on the toolbar:

You can also see above that the Security Enabled bit is set.

Security Header and Footer

The security enable bit enables the Auxiliary Security Header, which configures the 15.4 security features:

In a Connect-based application, a single configuration is always used:

• No key identification (i.e. we can only use a single, pre-shared key)
• Encryption is enabled
• Authentication is enabled, using a 4Byte MIC (Message Integrity Code)

The security header also includes a Frame Counter which is used to protect against replay attacks.

Finally, after the payload, but before the CRC, the frame includes the MIC, which authenticates the frame.

Note that in 15.4, only the frame counter, payload and MIC are encrypted, the other headers and the CRC are not. The MIC is calculated over the whole MAC frame though (i.e. everything except the length byte and CRC).

While this is the only security mode supported in Connect (sometimes called mode-5 or AES-CCM-32), it's also one of the most secure (the few higher security modes only provide longer MICs).

Keep in mind that these security features consume 9 Bytes of the payload (1B control, 4B frame counter, 4B MIC).

Conclusion

This tutorial demonstrated the convenience and power afforded Connect application developers by the Network Analyzer tool in Simplicity Studio. By conducting a field-by-field examination of packets captured from our example application, hands-on experience "driving" the tool helped to reinforce the concepts introduced in prior tutorials.

This is the sixth tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.

With this edition of the tutorial series, we briefly step away from the demonstration table to discuss a topic of critical importance to Connect: addressing in IEEE 802.15.4. A common source of initial confusion is the IEEE 802.15.4 support for multiple addressing modes. This tutorial clarifies the main elements related to addressing covered by the "15.4" standard, and presents some practical addressing examples typical of the space.

The following guidance is written with the Connect stack in mind, but it is applicable to any 15.4-based communication. Though the content is not dependent upon any other series tutorials, you will find it a valuable reference when those documents (or any other Connect resources) discuss addressing.

Long Address

Each device that supports 15.4 should have an 8 Byte EUI-64 address assigned to it during manufacturing. This address is unique between all devices that supports this address format. This is usually called the long address.

PAN

IEEE 802.15.4 devices can be grouped into Personal Area Networks (PANs). These are identified by their 2 Byte PAN identifier (PAN ID). Messages sent between devices that are in the same PAN are called Intra-PAN messages, while messages that are sent between PANs are called Inter-PAN messages.

Short Address

Each device can configure a 2 Byte short address (sometimes called node id). This should be unique within the PAN.

When a device configures this address in the application layer, we usually call it commissioning. However, a network layer can also configure a short address to devices, usually during a join process.

Special Addresses

• The short address 0xFFFF is used for broadcasting. All devices should receive it in the PAN, and no device should ACK it.
• The PAN ID 0xFFFF is the broadcast PAN ID. Devices for all PANs should accept it. In practice, this is only used together with the broadcast short address.
• The long address 0xFFFFFFFFFFFFFFFF is used for broadcasting, though it is very rarely used in 15.4.
• The short address 0xFFFE is the "not configured" short address. This is usually used during a join process to acquire a unique short address.

Addressing Modes

IEEE 802.15.4 frames contain address information for both the source and destination. Each of these can be (independently) configured as one of three different addressing modes, which sets the address data (none/short/long, with/without PAN ID) that is included in the frame:

• No address: For example, both addresses are missing from ACK frames. For data and command frames, only one (either source or destination) field can be omitted - if the source address is omitted, it means the PAN coordinator sent the frame; if the destination address is missing, it means it should be received by the PAN coordinator.
• Short address: The address field includes a short address and a PAN ID (total of 32 bits).
• Long address: The address field includes a long address and a PAN ID (total of 80 bits).

Intra-PAN messages usually omit the source PAN ID (this is configurable, but in practice is never changed).

Frame Format Examples

Case 1

Short addressed, Intra-PAN.

This is the most common frame format used in 15.4. It includes short address for the source and the destination, as well as the destination PAN (which is the same as the source PAN). Addressing fields use 12B from the MAC header.

Case 2

Long addressed.

A 15.4 stack might not want to use short addresses at all, in which case they can use the long address for both source and destination. Since the addresses are unique, this mode can be used both inter-PAN and intra-PAN (in the latter case, the source PAN ID can be omitted)

Case 3

Long source, short destination.

This addressing mode is used during a join process, where the source device does not yet have short address.

Case 4

No address.

ACK frames don't have any address field.

Conclusion

This tutorial explained how the IEEE 802.15.4 standard treats addressing, and gave insight into when you might encounter specific scenarios or use certain elements within a 15.4-based network. The utility of this knowledge will be made particularly clear in the next tutorial,Traffic Analysis: Addressing, Acknowledgement, and Security.

For more information on 15.4 in Connect, see UG235.02: Using Silicon Labs Connect with IEEE 802.15.4.

This is the fifth tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.

The previous tutorial (Communication Features: Acknowledge and Message Queue) fortified simple radio operations with built-in Connect features to yield more resilient wireless communication and reduce application overhead. We'll now examine how to augment this configuration with the built-in security features available to Connect-based applications.

To conduct the following exercises, you'll need two Wireless Starter Kit (WSTK) boards, each equipped with a (preferably identical) radio board. The example application relies on CLI through the WSTK VCOM (over USB) port to issue commands and display status information.

Application Example: AES Encryption

Historically, security was - at best - an afterthought in the race to capture market share in the nascent IoT. You may even have heard the joke "The S in IoT stands for security" (credit:@tkadlec). After years of widespread public incidents attributed to IoT devices, lessons-learned led to heightened awareness and ultimately an industry-wide push to directly address the risk profiles of our modern, thoroughly-connected world.

One fundamental tenet of IoT security is the encryption of messages over-the-air (OTA). The example below demonstrates how easy it is to use Connect's built-in encryption support. Currently, Connect can implement AES or XXTEA ciphers - AES is strongly recommended (the inferior XXTEA is a remnant of support for 8bit devices on which AES was not feasible).

Important note: Connect supports security in a binary fashion - it is either enabled or disabled, on a per-message basis. This tutorial discusses the AES encryption component, as it requires application participation for key management. However, encryption is just one benefit (data confidentiality) of many (including data authenticity and replay protection) that Connect provides with "out of the box" security. A message integrity code (MIC) and frame counter (to resist replay attacks) are managed entirely by the Connect MAC layer. More detail on security in Connect is presented later in Traffic Analysis: Addressing, Acknowledgement, and Security

We'll build upon the example developed during the previous tutorial (Communication Features: Acknowledge and Message Queue). To begin, we recommend that you start from that project and extend it as instructed below. Feel free to use the attached "solution" files in your project instead, or simply for reference as you proceed through the steps below.

Modify the AppBuilder Configuration

We'll need only a few minor changes to the tutorial 4 example project. To include AES encryption support, select the Security AES plugin in AppBuilder / Plugins in the Connect Stack section, and deselect the Security AES Stub option.

Make two command line configuration changes so we can manipulate the AES feature via CLI:

• set-tx-options now needs a second "u" argument (to enable/disable encryption)
• add new command set-key to set the encryption key (string argument, "b") at run time

Remember to save the .isc file and [Generate] the project again to apply these updates.

For future reference: if you plan to implement additional application-layer security in your project (and leverage hardware acceleration via the mbedTLS library), select AppBuilder / Plugins / Connect Utility / mbed TLS to safely share crypto resources with Connect.

Source Code Modifications

Of course, we'll need a placeholder for the default security key. Since Connect implements AES-128 encryption, the key size is 16 Bytes. These 16 Bytes are loaded into a structure of type EmberKeyData (which has a single member, contents[]):

#define SECURITY_KEY   {{ 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, \
                          0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, \
                          0xAA, 0xAA, 0xAA, 0xAA }}

static EmberKeyData securityKey = SECURITY_KEY;

To apply the security key, the following API has to be called:

emberSetSecurityKey(&securityKey);

We'll call this API any time we want to change the key, but also in commissionCommand(void) to ensure the default key is applied when the network is first created. As AES is a symmetric-key algorithm, this single key is used for both encryption of sent messages and decryption of received messages.

void commissionCommand(void) {
  EmberStatus status;
  EmberNodeId nodeId;
  EmberNetworkParameters params;

  // Initialize the security key to the default key prior to forming the
  // network.

  emberSetSecurityKey(&securityKey);

  nodeId = emberUnsignedCommandArgument(0);
  params.panId = PAN_ID;
  params.radioChannel = RADIO_CHANNEL;
  params.radioTxPower = RADIO_TX_POWER;

  status = emberJoinCommissioned(EMBER_DIRECT_DEVICE,
                                 nodeId,
                                 &params);

  if ( status != EMBER_SUCCESS ) {
    emberAfCorePrintln("Commissioning failed, 0x%x", status);
  }
}

To support our new run time key change command (usage: set-key <16 byte security key>), we implement its corresponding command handler:

void setSecurityKeyCommand(void)
{
  EmberKeyData key;
  emberCopyKeyArgument(0, &key);

  if (emberSetSecurityKey(&key) == EMBER_SUCCESS) {
    uint8_t i;

    emberAfCorePrint("Security key set {");
    for (i = 0; i < EMBER_ENCRYPTION_KEY_SIZE; i++) {
      emberAfCorePrint("%x", key.contents[i]);
    }
    emberAfCorePrintln("}");
  } else {
    emberAfCorePrintln("Security key set failed");
  }
}

To enable the encryption of outgoing messages, we need only add EMBER_OPTIONS_SECURITY_ENABLED to the options passed to emberMessageSend(). For convenience, we've added a second input parameter to the set-tx-options command - in addition to ACK requested, it now expects a second argument: security enabled (0 to disable, 1 to enable). The handler for set-tx-options is extended to accommodate the new parameter:

void setTxOptionsCommand(void) {
  uint8_t enableAck = emberUnsignedCommandArgument(0);
  uint8_t enableSecurity = emberUnsignedCommandArgument(1);

  if(enableAck) {
    txOptions |= EMBER_OPTIONS_ACK_REQUESTED;
  } else {
    txOptions &= ~EMBER_OPTIONS_ACK_REQUESTED;
  }

  if(enableSecurity) {
    txOptions |= EMBER_OPTIONS_SECURITY_ENABLED;
  } else {
    txOptions &= ~EMBER_OPTIONS_SECURITY_ENABLED;
  }
  emberAfAppPrintln("ACK is %srequested, security is %s",
      (txOptions & EMBER_OPTIONS_ACK_REQUESTED) ? "" : "not ",
      (txOptions & EMBER_OPTIONS_SECURITY_ENABLED) ? "enabled" : "disabled");
}

Successful reception of an encrypted message requires that the same security key be used by both the sender and receiver. However, the receiving device does not dictate security (this is set by the sender) - it merely evaluates the "security enabled" bit present on any inbound message to determine whether or not a decryption operation is required. Any received messages with that bit cleared (i.e. unencrypted messages) will therefore be treated as valid. This can present a security concern if a device with security enabled (i.e. it is transmitting encrypted outbound messages) converses with a remote device that is not encrypting its responses.

To avoid this scenario, use the EMBER_OPTIONS_SECURITY_ENABLED flag in the options member of Connect's EmberIncomingMessage structure to filter out any unwanted messages (i.e. when the flag is set in TX options, but not in an incoming message). The updated callback implementation below prints a warning when those conditions are present:

void emberAfIncomingMessageCallback(EmberIncomingMessage *message) {
 // your code here
  if((txOptions & EMBER_OPTIONS_SECURITY_ENABLED) && !(message->options & EMBER_OPTIONS_SECURITY_ENABLED)) {
    // In normal circumstances if security is enabled but the message is not
    // encrypted it should be ignored to avoid security issues
    emberAfAppPrintln("warning: security is enabled, but the incoming message is not encrypted");
  }

  emberAfAppPrint("incoming message: from: 0x%02x, options=0x%1x, endpoint=%d, length=%d, payload=[",
                                message->source,
                                message->options,
                                message->endpoint,
                                message->length);
  for(int cnt = 0; cnt < message->length; cnt++) {
    emberAfAppPrint("%c", message->payload[cnt]);
  }
  emberAfAppPrintln("]");
}

Using the Example Application

As in the previous tutorial (Communication Features: Acknowledge and Message Queue), compile and download the firmware to the devices, and open terminals for both. To set up a connection, call commission 1 on device 1, and call commission 2 on device 2. To test the communication, call send 2 1 "message" 1 on device 1.

To turn on message encryption for device 1, simply enable security (this will also request ACKs, as the first parameter is 1) by issuing:

> set-tx-options 1 1
ACK is requested, security is enabled

Ensure that security is disabled (this is the default setting) on device 2 by issuing:

> set-tx-options 1 0
ACK is requested, security is disabled

Now transmit an unencrypted message from device 2 to device 1 with send 1 1 "message" 1. Device 1 will receive the message, but observe that security is disabled in the options member and warn of this condition over CLI:

warning: security is enabled, but the incoming message is not encrypted
incoming message: from: 0x0002, options=0x02, endpoint=1, length=7, payload=[message]

Enable security on device 2 also, and device 1 will now happily receive encrypted messages:

incoming message: from: 0x0002, options=0x03, endpoint=1, length=7, payload=[message]

On only one of the devices, "break" the communication by changing its key from the default:

> set-key {00112233445566778899aabbccddeeff}
Security key set {00112233445566778899AABBCCDDEEFF}

With the keys on each device out of sync, messages sent with security enabled will fail to be received (this example application drops such messages without notifying the CLI). Set the same key on both devices and the receiver will again successfully decrypt and report each message reception.

Notes

The security key is stored in flash memory, so in theory it is not necessary to apply the key on every boot. This is useful for devices after power cycle or reset that rejoin a network that has over time migrated security keys.

The selection of the "all 0xAA" key used in this example was deliberate, as messages encrypted with this key are automatically decrypted by Simplicity Studio's built-in network analyzer. This tool enables convenient debugging of encrypted communications, and is covered in depth in the Traffic Analysis: Addressing, Acknowledgement, and Security tutorial.

Conclusion

Combining the CLI and enhanced radio messaging from prior tutorials with built-in Connect security features, this tutorial demonstrated message encryption in a Direct Mode Connect network. Discussion of additional security features (beyond encryption) is presented in Traffic Analysis: Addressing, Acknowledgement, and Security.

For more information on the Connect security implementation, see UG235.02: Using Silicon Labs Connect with IEEE 802.15.4 and UG235.03: Architecture of the Silicon Labs Connect Stack.

API References

Functions

• emberAfIncomingMessageCallback()
• emberSetSecurityKey()
• emberCopyKeyArgument()

Type definitions

• EmberStatus
• EmberNetworkParameters
• EmberNodeId
• EmberIncomingMessage
• EmberKeyData

Defines

• EMBER_SUCCESS
• EMBER_ENCRYPTION_KEY_SIZE
• EMBER_OPTIONS_ACK_REQUESTED
• EMBER_OPTIONS_SECURITY_ENABLED

This is the fourth tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.

The second tutorial (Communication Basics: Send and Receive) covered simple radio transmit and receive operations. With this fourth tutorial in the series, we examine two Connect features that expand on those simple ideas to enable more sophisticated communication. By offloading some radio management from the application, message queues and auto-acknowledgement yield both more robust wireless communication and less application overhead.

To conduct the following exercises, you'll need two Wireless Starter Kit (WSTK) boards, each equipped with a (preferably identical) radio board. The example application relies on CLI through the WSTK VCOM (over USB) port to issue commands and display status information.

Message Queue Plugin

By default, emberMessageSend() can send one message at a time. An application must wait until the current message is fully transmitted before the next message can be sent. Calling the API again too quickly (i.e., before the previous message transmit is complete) will return with an error (EMBER_PHY_TX_BUSY).

To eliminate this restriction, the Connect stack supports message queuing with the MAC Packet Queue plugin (AppBuilder / Plugins / Connect Stack). Using this feature, multiple emberMessageSend() calls can be issued at any time - without waiting between each call for the prior message to completely transmit. The Connect stack will queue each "sent" message, and transmit them incrementally (in the order in which they were queued) as the radio becomes available. This occurs without any further interaction from the application.

Message queue depth is configured by the plugin option Outgoing Packet Queue Size. If the queue is already full (i.e., an application tries to send one more packet than there are free slots in the queue), the emberMessageSend() call will return with an error (EMBER_MAC_TRANSMIT_QUEUE_FULL).

Automatic Message Acknowledgement

Connect supports the automated acknowledgement (ACK) of received messages. When enabled, this means a receiving device ("receiver") will automatically send an ACK packet to the sending device ("sender"), to acknowledge that the message was successfully received.

To enable this feature, the application running on the sender should pass EMBER_OPTIONS_ACK_REQUESTED to emberMessageSend() - the outgoing packet will then be configured to request that it be ACKed by the receiver. The receiving device will automatically reply with an ACK upon successful receipt of a message that requested one - no receiver application intervention is needed.

If a sender requesting ACKs doesn't receive one within the timeout period, it will re-send the message (and repeat this timeout->re-send sequence multiple times, if necessary). If the ACK still does not arrive after these multiple attempts, the sender will conclude that the message was not delivered. The end-result of a message transmission attempt can be retrieved from the emberAfMessageSentCallback().

Application Example

In the example that follows, we show how the built-in automatic acknowledge features can be used in a Connect application. This example is constructed using Connect's Direct Mode. Feel free to use the attached "solution" files in your project instead, or simply for reference as you proceed through the steps below.

To begin, create a new Connect (SoC): Empty Example Flex SDK Project as described in tutorial 1 "Getting Started with Application Development". (Just create a new project for this tutorial 4 and give it an appropriate name - you don't need to actually repeat the tutorial 1 exercise.) Then, enable CLI-related plugins and printing functions as described in the previous Command Line Interface tutorial. We'll keep the default configuration, which enables access to the EFR32 serial port through the VCOM (over USB) port on the WSTK board.

Select Plugins

To enable the MAC queue feature, select the MAC Packet Queue plugin in AppBuilder / Plugins in the Connect Stack section, and deselect the MAC Packet Queue Stub option.

Click on the MAC Packet Queue text in the left pane of the [Plugins] tab, to display info and config options for this plugin in the right-hand pane. Set the Outgoing Packet Queue Size to 2 (the default value is 8). This will simplify the following demonstrations, making it easier to test the behavior when the queue is full.

Select Callbacks

The following extra callbacks should be enabled in AppBuilder / Callbacks:

• emberAfStackStatusCallback
• emberAfIncomingMessageCallback
• emberAfMessageSentCallback

CLI commands

To make the example easier to control we will add some commands:

You can now save your changes and [Generate] the project in AppBuilder.

The Example Code

A sender can request acknowledgement of message receipt from the receiver by enabling EMBER_OPTIONS_ACK_REQUESTED. To help demonstrate the use-cases that follow, in our example application we define a global variable to hold send options:

static EmberMessageOptions txOptions = EMBER_OPTIONS_ACK_REQUESTED;

We've implemented the following callback to report over CLI whenever the network status changes:

void emberAfStackStatusCallback(EmberStatus status) {
  // see error-def.h for status codes
  switch(status) {
    case EMBER_NETWORK_UP:
      emberAfAppPrintln("network is up");
      break;
    case EMBER_NETWORK_DOWN:
      emberAfAppPrintln("network is down");
      break;
    default:
      emberAfAppPrintln("stack status changed: 0x%01x", status);
      break;
  }
}

When a message is received, we will print the payload and some message properties to the CLI:

void emberAfIncomingMessageCallback(EmberIncomingMessage *message) {

  emberAfAppPrint("incoming message: from: 0x%02x, options=0x%1x, endpoint=%d, length=%d, payload=[",
                                message->source,
                                message->options,
                                message->endpoint,
                                message->length);
  for(int cnt = 0; cnt < message->length; cnt++) {
    emberAfAppPrint("%c", message->payload[cnt]);
  }
  emberAfAppPrintln("]");
}

In the "message sent" callback, we check the status associated with the send operation (successful, no ACK received, etc.) and print this result to the CLI - along with a tag that is used to associate the message result with the originating call to emberMessageSend():

void emberAfMessageSentCallback(EmberStatus status,
                                EmberOutgoingMessage *message) {

  if(status == EMBER_SUCCESS) {
  emberAfAppPrintln("tag: %d, message successfully sent", message->tag);
  } else {
    if(status == EMBER_MAC_NO_ACK_RECEIVED) {
      emberAfAppPrintln("tag: %d, no ack received", message->tag);
    } else {
      // see error-def.h for status codes
      emberAfAppPrintln("tag: %d, message sending failed, status=0x%01x", status);
    }
  }
}

As opposed to the Communication Basics: Send and Receive tutorial, where the local and remote addresses were hard-coded in the source, this example will use the CLI to set the local address:

void commissionCommand(void) {
  EmberStatus status;
  EmberNodeId nodeId;
  EmberNetworkParameters params;

  nodeId = emberUnsignedCommandArgument(0);
  params.panId = PAN_ID;
  params.radioChannel = RADIO_CHANNEL;
  params.radioTxPower = RADIO_TX_POWER;

  status = emberJoinCommissioned(EMBER_DIRECT_DEVICE,
                                 nodeId,
                                 &params);

  if ( status != EMBER_SUCCESS ) {
    emberAfCorePrintln("Commissioning failed, 0x%x", status);
  }
}

Usage syntax for this command is: commission <node id> which will apply the specified address (node id) as the device's short address.

Add the following macros earlier in your flex-callbacks.c to support the above commission callback:

#define PAN_ID 0xABCD
#define RADIO_CHANNEL 0
#define RADIO_TX_POWER 10

We've added a CLI command to toggle whether or not ACK is requested for outgoing packets. This command sets (or clears) the EMBER_OPTIONS_ACK_REQUESTED bit in our txOptions global variable, which is passed to the send function:

void setTxOptionsCommand(void) {
  uint8_t enableAck = emberUnsignedCommandArgument(0);
  // this CLI command sets/clears only the TX ACK option
  if(enableAck) {
    txOptions |= EMBER_OPTIONS_ACK_REQUESTED;
  } else {
    txOptions &= ~EMBER_OPTIONS_ACK_REQUESTED;
  }
  emberAfAppPrintln("ACK is %srequested",
      (txOptions & EMBER_OPTIONS_ACK_REQUESTED) ? "" : "not ");
}

Usage: set-tx-options <ack> if ack = 0, acknowledgement is not required; otherwise, send operations will request ACKs.

We've also added a send command to support initiating message transmit operations from CLI:

void sendCommand(void) {
  EmberStatus status;
  uint8_t length;
  EmberNodeId destination = emberUnsignedCommandArgument(0);
  uint8_t endpoint = emberUnsignedCommandArgument(1);
  uint8_t *contents = emberStringCommandArgument(2, &length);
  uint8_t numberOfMessages = emberUnsignedCommandArgument(3);
  uint8_t messageTag;
  char *statusMessage;

  // parameters specified in the command line
  //  destination: the node ID to send the message to
  //  endpoint: additional parameter the receiver can use to filter the incoming message on
  //  contents: data to send (preferably a string, as the receive callback prints as text)
  //  numberOfmessages: how many times to transmit the message (used to demo the MAC queue depth)
  //  txOptions: various transmit settings, here we use only the ACK request
  for(messageTag = 0; messageTag < numberOfMessages; messageTag++) {
    status = emberMessageSend(destination,
                              endpoint,
                              messageTag,
                              length,
                              contents,
                              txOptions);

    switch(status) {
      case EMBER_SUCCESS:
        statusMessage = "message queued successfully";
        break;
      case EMBER_MAC_TRANSMIT_QUEUE_FULL:
        statusMessage = "transmit queue full";
        break;
      case EMBER_INVALID_CALL:
        statusMessage = "invalid call (API call is not allowed given the current state)";
        break;
      default:
        statusMessage = " see error-def.h";
        break;
    }
    // see error-def.h for status codes

    emberAfCorePrintln("tag=%d, status=0x%x, %s", messageTag, status, statusMessage);
  }
}

Usage: send <remote address> <remote endpoint> <payload> <number of messages to send> where the first parameter is the address of the remote device, the second is the endpoint (this can be chosen freely), the third is the message payload (preferably, a text string), and the last one specifies how many times to send the message.

The parameter txOptions (which can be set by the previously mentioned set-tx-options command) passed to emberMessageSend() controls whether or not the sender requires an ACK from the receiver (remote device). It is a bitfield that also affects other TX behavior - see EmberMessageOptions in ember-types.h.

The last parameter (number of messages to send) is included here to test the message queue. If it is more than two (i.e. exceeds the Outgoing Packet Queue Size), the emberMessageSend() call should return with an error.

The send command prints to CLI the result of each individual emberMessageSend().

The leave command resets the network state - it must be issued before a new address can be commissioned:

void leaveCommand(void) {
  // if the network is already up, it must be reset before commissioning again
  emberResetNetworkState();
}

Usage: leave (without any parameters).

Use-Case Exercises for the Example Application

Compile and download the firmware to the devices, and open terminals for both. Initialize the network on both devices as follows:

Device 1:

>commission 1
network is up

Device 2:

>commission 2
network is up

At this point the devices can send messages to each other, and the remote side should receive the message and print some information to your terminal.

By default, ACK requests are enabled when the application starts. If it becomes necessary to re-enable ACK requests, issue the set-tx-options 1 command.

Case 1

ACK requests are on, and the number of messages is less than the depth of the queue.

On device 1, issue a send command as follows:

>send 2 1 "message" 1
tag=0, status=0x00, message queued successfully
tag: 0, message successfully sent

Device 2 should receive a single message and print a notice to the CLI:

incoming message: from: 0x0001, options=0x02, endpoint=1, length=7, payload=[message]

Case 2

ACK requests are on, but more messages are sent than the queue can hold at once.

On device 1, issue a send command as follows:

>send 2 1 "message" 3
tag=0, status=0x00, message queued successfully
tag=1, status=0x00, message queued successfully
tag=2, status=0x39, transmit queue full
tag: 0, message successfully sent
tag: 1, message successfully sent

Device 2 should receive two messages and notify the CLI:

incoming message: from: 0x0001, options=0x02, endpoint=1, length=7, payload=[message]
incoming message: from: 0x0001, options=0x02, endpoint=1, length=7, payload=[message]

As depicted in the device 1 (sender) CLI above, only the first two messages were sent successfully. Since the queue size is set to two, the third requested message transmit was dropped due to a full queue. Hence, the receiver observed only two sent messages.

Case 3

ACK requests are on, but not received before timing out (and maxing out the retry attempts).

On device 1, issue a send command as follows - deliberately addressed to a non-existent device::

>send 3 1 "message" 1
tag=0, status=0x00, message queued successfully
tag: 0, no ack received

Case 4

ACK requests are not enabled.

On device 1, disable ACK requests by issuing:

>set-tx-options 0

Then repeat the send command (addressed to a non-existent device) from Case 3:

>send 3 1 "message" 1
tag=0, status=0x00, message queued successfully
tag: 0, message successfully sent

Note above that - without verifying message receipt by requesting ACKs - device 1 now believes a message was "successfully sent" to a device that doesn't exist.

This is one aspect of how the built-in Connect ACK support facilitates the rapid development of applications with robust wireless communication.

Conclusion

Building on the CLI and simple radio operations covered previously in the series, this tutorial demonstrated some of the enhanced functionality available "out-of-the-box" in Connect-based applications. Additionally, rapid examinations of these features under multiple usage scenarios clearly demonstrated the utility and extensible power of the built-in CLI capability.

API References

Functions

• emberAfIncomingMessageCallback()
• emberAfMessageSentCallback()
• emberAfStackStatusCallback()
• emberMessageSend
• emberResetNetworkState()
• emberGetStringArgument()
• emberUnsignedCommandArgument()

Type definitions

• EmberStatus
• EmberNetworkParameters
• EmberNodeId
• EmberMessageOptions

Defines

• EMBER_SUCCESS
• EMBER_PHY_TX_BUSY
• EMBER_MAC_TRANSMIT_QUEUE_FULL
• EMBER_INVALID_CALL
• EMBER_OPTIONS_ACK_REQUESTED
• EMBER_NETWORK_UP
• EMBER_NETWORK_DOWN
• EMBER_MAC_NO_ACK_RECEIVED
• EMBER_DIRECT_DEVICE

This KBA provides a brief summary about and highlights the possible need for board-level ESD protection for RF devices.

Radio chips are designed for and tested against different chip-level ESD standards, such as Human Body Model (HBM), Machine Model (MM) and Charged Device Model (CDM). These chip-level test results are summarized in the RF IC’s Qualification Reports.

However, in a real-world application a final module/board has to resist and stand against an ESD shock. For this purpose, the final electronic product has to be tested against a different, more stringent standard that simulates and replicates the real world ESD stress conditions. This system-level ESD standard is the IEC 61000-4-2, for instance. System/module designers should take care to comply with the IEC 61000-4-2 system-level ESD standard. This KBA provides some board-level insights about how to make an RF design more immune against ESD.

For more technical details, please refer to Silicon Labs' application note AN895. This application note provides recommendations on ESD protection circuits and shows test results measured with the Si4x6x chip family, however the suggested protection circuits can also be utilized with any other RF chip families. 

https://www.silabs.com/documents/public/application-notes/AN895.pdf

For an RF design the most ESD-sensitive part is the RF path, including the antenna, matching network and RF ports. Secondly, the supply and GND paths are also sensitive, and lastly any GPIO or other paths connected to the RF chip directly. 

So, the antenna definitely needs special care during design and assembly into the end product. ESD protection can be enhanced by: 

- antenna placement: end-user shouldn't be able to touch it in any case.

- design an antenna with direct GND connection, e.g. inverted-F antenna. 

- protection circuit elements in the RF path: parallel inductors, capacitors, TVS diodes. 

Many circuit designs have the supply trace connected to the PA externally, for which cases the supply trace may also need care and ESD protection. 

Lastly, any push-button or interface, that can be touched by the user of the end-product during normal usage, may also need to be ESD-protected. These are, typically, GPIO ports of RF devices. 

Please see AN895 application note for recommended ESD protection circuits and for more technical details. 

Si446x revC2A, A2A devices have a feature that automatically restarts the demodulator upon an RSSI jump event. The feature can be enabled in field ENJMPRX in API property MODEM_RSSI_CONTROL2. The RSSI jump threshold can be programmed in API property MODEM_RSSI_JUMP_THRESH.

The feature is meant to be used for recovering the Rx when a packet is being received but a higher power wanted packet arrives. Upon the power jump detection, the Rx restarts and receives the higher-level packet. This is true if the power difference between the packets is higher than the minimum SNR the demodulator needs for error free reception. This level is typically 10 dB for 2FSK H=1 modulation formats. (H is the modulation index.) Without the feature neither of the packets would be received.

There is a flaw with the feature: it only resets the demodulator but not the packet handler.  The implication is that if the higher power packet arrives after sync word has been detected on the weak packet than both packets will be lost as the packet handler does not get reset and remains in packer Rx state on the 1st packet (as opposed to going back to sync word search state).  If the higher power packet arrives before sync word is detected on the weak packet than the higher power packet will be received all right.

This flaw limits the performance of the feature quite a bit. A possible SW workaround to the issue is checking if sync word has been detected when the RSSI JUMP UP interrupt fires. If it has, then restart the Rx, if it has not, then do nothing. Obviously, this workaround takes time so the minimum preamble length requirement for this to work error free will be higher. By exactly how many bits longer a preamble is required depends on the data rate. You may measure how much time the whole restart takes and translate that to preamble bits. These bits must be added on top of the minimum requirement w/o the workaround. Minimum preamble length requirements are 40 bits, 32 bits and 16 bits with preamble detection with AFC, preamble detection w/o AFC and with DSA, respectively.