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.
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.
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.
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.
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:
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.
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:
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).
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):
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 is a one byte field that increments on each transmit, and it is used by the ACK mechanism - we will return to this shortly.
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).
The Connect Network Frame starts with its header:
This header is followed by the payload itself.
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)
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 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.
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.
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.
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:
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).
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.