What is the Dynamic Configurator?

Dynamic Configurator is a Simplicity Studio feature that allows experimentation with radio configurations on EFR32 devices.

What is the typical use case?

Typically dynamic configuration is used to easily reconfigure the EFR32 of a Silabs development board or a custom radio board

• to evaluate the radio of the EFR32 (the other node of the link is a generator or spectrum analyzer)
• to find compatible configuration (the other node of the link is a fixed configuration/third party radio ).

How does it work?

There are CLI (Command Line Interface) commands implemented in a plugin of the RAILTest sample application, called Ram Modem Reconfiguration Commands.

Using these commands Simplicity Studio generates scripts of the user configured radio settings and applies them over a virtual COM port to  the target EFR32 to dynamically change the radio modem configuration, without the need for recompiling the RAILTest application and reflashing the target.

The virtual COM port consists of a physical UART between the target device and the board controller of the WSTK (Wireless Starter Kit) Mainboard, and a logical function in the board controller that makes the serial port available to the host PC, over USB or Ethernet.

How to use it?

1. Set up your development environment and create a new or open an existing RAILTest sample application for your connected Silabs or custom HW, according to the description in https://www.silabs.com/documents/public/quick-start-guides/qsg138-flex-efr32.pdf. You will end up in the Simplicity IDE perspective of Simplicity Studio with a RAILTest project open.
2. Open the isc file and in the configurator window set the initial configuration according to your needs. Make sure that the "Railtest Ram Modem Reconfiguration" plugin is enabled. Generate and compile the application.
3. Upload the application to the target without starting a debug session.
4. Open a terminal window for the virtual COM port of the target by right clicking on the target adapter in the "Debug Adapters window" and selecting "Launch Console…"
5. In the console window select the "Serial 1" tab and by pressing Enter in the text box check if the connection with the RAILTest is alive.
6. Now you can start using RAILTest with your initial configuration. See https://www.silabs.com/documents/public/user-guides/ug409-railtest-users-guide.pdf for help.
7. When you need to modify the configuration, do it in the configurator window. Note that the dynamic configurator can support only the first Channel Group of the first Protocol configuration.
8. In the configurator window click on the Dynamic Radio Configuration button of the isc editor, open the "Adapters" tab and select your target adapter.
9. Then go to the "Create configuration" tab. It will create and display the dynamic configuration script as soon as you click on the "Generate dynamic Railtest Configuration" button.
10. To send the script to the target, go to the "Apply Configuration" tab and click the "Apply Configuration" button. The commands of the script and the responses will appear in the previously opened console window. In case of success the radio will start to behave according to the modified configuration.

Note that the dynamic config modifies only radio registers, so getConfigIndex, printDataRates or similar CLI commands that get values from other sources may return incorrect values. The overwritten configuration can be reverted by a reset or setConfigIndex CLI command.

Note also that the RAM Modem Reconfiguration CLI Commands (writeRmrStructure, updateConfigurationPointer and reconfigureModem) are intended to be used only by Simplicity Studio and not directly from the CLI.)

The function RAIL_Idle() takes a mode argument, with which you select one of the four available methods of idling the radio to use. Though the API documentation briefly describes each mode, it might be difficult to understand their differences without seeing examples and usecases. This document aims to help you more clearly understand each mode.

General recommendations

In most cases, RAIL_IDLE is the recommended mode to use with this API. RAIL_IDLE_ABORT is helpful when you want to also abort an ongoing ("active") tx or rx operation.

On the other hand, RAIL_IDLE_FORCE_SHUTDOWN is not recommended for use, and RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS should be handled with care.

RAIL_IDLE

The mode RAIL_IDLE turns off the radio after the current operation is finished. It also cancels any transmit or receive scheduled in the future. Current operations that won't be aborted include:

• active transmit, which starts when the first bit (usually preamble) is transmitted and ends when the last bit (usually CRC) is transmitted.
• active receive, which starts at sync word detect, and ends when the last bit is received (which depends on the decoded length of the packet).

RAIL_IDLE_ABORT

The mode RAIL_IDLE_ABORT works the same as RAIL_IDLE, but it will also abort active operations. However, RAIL_IDLE_ABORT will always wait for a stable state before turning off the radio, e.g. if the radio was preparing to enter rx mode and is waiting for the PLL to lock, RAIL will wait until the rx state is reached before idling the radio.

RAIL_IDLE_FORCE_SHUTDOWN

Unlike RAIL_IDLE_ABORT (which waits for a stable radio state), RAIL_IDLE_FORCE_SHUTDOWN immediately forces the radio off. As this is an abrupt transition, it may corrupt data in the receive or transmit buffers. This buffer corruption can only be resolved by completely clearing the FIFO - which loses data, and can also consume additional time.

In our experience, it's almost always slower than RAIL_IDLE_ABORT, so the costs typically outweigh the benefit of using RAIL_IDLE_FORCE_SHUTDOWN (except when recommended by our support team for diagnostic purposes).

RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS

The mode RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS works the same as RAIL_IDLE_FORCE_SHUTDOWN, but it also clears any pending events. For more details on scenarios where this can be useful, see the article on RAIL interrupt safety.

In embedded software development, some of the most complicated debug challenges are caused by calling non-reentrant functions in interrupt context. Hence, it's in the developer's best interest to carefully design their application to avoid these scenarios.

To do so, however, requires sufficiently detailed knowledge of the interrupts and API functions - which are not accessible in a closed-source product like RAIL. This document aims to provide the information required to develop interrupt- and thread-safe applications in RAIL.

Thread Safety

In an application without a task scheduler, only an interrupt request can interrupt the main program. If you use a preemptive scheduler, like the scheduler available in most embedded OSes (including Micrium OS), higher priority tasks can interrupt lower priority tasks as well. Regardless, when looking at the RAIL APIs, the same concerns are present in either case:

• Is it safe to interrupt this API?
• Is it safe to call this API from a thread/interrupt which interrupted something?

The Event Handler

RAIL uses an event handler, which is set up by RAIL_Init(). In our examples, it's usually called RAILCb_Generic(). This function is called by the RAIL library, and it's almost always called from an interrupt handler. This means the event handler should be used with care:

• It should be kept in mind that interrupts are disabled when the event handler is running, so the function must not take long to return
• More importantly, the function might be interrupting the main loop (or some other task)

Note that the first point above might not be completely true if interrupt priorities are used, in which case only interrupts at the same and lower priorities are disabled. However, the event handler will never be interrupted by another event handler as all RAIL interrupts must be used at the same priority.

General Rules for the RAIL API

First, let's collect the general rules of the API, and we'll detail exceptions in later points:

1. Calling any RAIL API from the main thread (or a single OS thread) is safe.
2. Calling any API from multiple threads is unsafe, except for DMP.
3. Calling most APIs from an interrupt handler is safe (see exceptions below).

Dynamic Multiprotocol (DMP)

In general, if you have a multi-threaded application, you should use RAIL from a single thread. The exception to this guidance is DMP, where in most cases each protocol runs in its own thread. In this scenario, using RAIL from each thread is safe, as each protocol has its own railHandle. So, a more generalized wording of rule 2 is:

Calling any API from multiple threads is only safe if each thread has a dedicated railHandle, and each thread only accesses RAIL with its own handle.

The few APIs that don't use railHandle - like RAIL_GetTime(), RAIL_Sleep(), or RAIL_Wake() - can be called from any thread.

Interrupt Safety in general

In general, calling an API which changes the radio state (i.e. between rx, idle and tx) can be risky. The simplest way to write interrupt safe application is to not call state changing APIs from any interrupt handler, including the RAIL event handler. This can be achieved by setting a flag or changing a state variable in the event handler instead of calling an API directly:

typedef enum  {
  S_IDLE,
  S_START_RX,
  S_START_TX,
} state_t;

volatile state_t state;
volatile RAIL_Time_t lastEvent;

int main(){
  //init code

  state = S_START_TX;
  while(1){
    switch(state){
      case S_START_TX:
        RAIL_StartTx(railHandle, 0, RAIL_TX_OPTIONS_DEFAULT, NULL);
        state = S_IDLE;
        break;
      case S_START_RX:
        RAIL_StartRx(railHandle, 0, NULL);
        state = S_IDLE;
        break;
      default:
        break;
    }
  }
  return 0;
}

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events)
{
  lastEvent = RAIL_GetTime();
  if ( events & RAIL_EVENTS_TX_COMPLETION ){
    state = S_START_RX;
    RAIL_SetTxPower(railHandle, 200);
  }
}

Note that some RAIL API was called from the event handler, but none of those were state changing APIs.

Interrupt safety with state changing APIs

In some (usually time critical) cases however, it's not possible to avoid calling state changing APIs from the event handler (or other interrupt handler). State changing APIs are not always risky: Some APIs might be safe, as long as they don't interrupt another specific API.

Hence, in the following list, we identify the risky API after first specifying which initially-running (i.e., "interrupted") API makes it risky (and how). We've included in this list some interrupt combinations that might be "safe", but the end result is not predictable - i.e. the radio might be in rx or in idle, depending on which API is called first.

• Interrupting RAIL_Start<something>() with another RAIL_Start<something>() is risky, especially if they would start on different channels.
• Interrupting RAIL_Idle(handle, <something>, true) with any RAIL_Start<something>() is risky.
• Interrupting RAIL_Idle(handle, <something>, false) with any RAIL_Start<something>() is safe, but the end result is not predictable (i.e. the radio will either be in Idle, or start the requested operation).
• Interrupting RAIL_Start<something>() with RAIL_Idle() is safe but the end result is not predictable, and might cause strange events (see the next section for details).
• Interrupting RAIL_StopTxStream() with any RAIL_Start<something>() is very risky (the radio might remain in test configuration and start transmitting/receiving).
• Interrupting RAIL_StopTx() is safe. Interrupting RAIL_StopTx() with RAIL_Start<something>() is safe but the end result is not predictable (i.e. the radio will either be in Idle, or start the requested operation).
• Interrupting anything with RAIL_StopTx() is safe (see next section for important clarification). Interrupting RAIL_StartTx() with RAIL_StopTx(handle, RAIL_STOP_MODE_ACTIVE) is safe, but not predictable.
• Interrupting anything with RAIL_StopTxStream() is safe. Interrupting RAIL_StartTxStream() with RAIL_StopTxStream() is safe but not predictable.

RAIL_Idle in the Event Handler

Calling RAIL_Idle() or RAIL_StopTx(handle, RAIL_STOP_MODE_ACTIVE) from the event handler might cause strange results. For example, let's say you're receiving on a channel and want to detect preambles using the event RAIL_EVENT_RX_PREAMBLE_DETECT and RAIL_EVENT_RX_PREAMBLE_LOST. The following scenario may unfold:

• Preamble lost interrupt is received, so (at least) other radio interrupts are temporarily disabled.
• You enter the event handler with RAIL_EVENT_RX_PREAMBLE_LOST.
• At this point, the radio detects a preamble. The interrupt is logged, but the handler cannot run since the interrupts are masked.
• Still in the event handler, you decide to turn off the radio with RAIL_Idle(railHandle, RAIL_IDLE_ABORT, true).
• The radio turning off will generate a preamble lost interrupt.
• The radio is now off, and you return from the event handler.
• Interrupts are enabled again, so the pending preamble detect interrupt handler starts running.
• You enter the event handler with RAIL_EVENT_RX_PREAMBLE_DETECT and RAIL_EVENT_RX_PREAMBLE_LOST both set at the same time

So you end up with a preamble detect event, even though the radio is off. This is usually harmless, since you always have the _LOST or _ABORTED event as well - but this demonstrates why your design must carefully consider in what order to handle events.

The easiest way to avoid this conflicted outcome is to disable the events that might cause problems when turning off the radio.

Another way to avoid this issue is to use RAIL_Idle(handle, RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS, true), which will clear the pending interrupts. However, using RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS has other drawbacks. It does force the radio state machine to idle state, and it might corrupt the transmit or receive FIFOs - in which case it must clear them, losing all data that might already be in there. It could also take more time to finish running than RAIL_IDLE_ABORT.

Critical Blocks

One usual way to avoid internal safety issues is to create critical (a.k.a. atomic) blocks, in which interrupts are disabled, in the main thread to make sure some code segment is never interrupted. However, this can create other problems, so it should be used carefully. There's no general rule to avoid this kind of "collateral damage", but here's an example that should be avoided:

RSSI averaging is running, and just before it finishes, we interrupt it with RAIL_StartTx() which is called from a critical block. The following race condition could happen:

• We enter the critical block, interrupts are disabled.
• RSSI averaging done interrupt is received, but the interrupt handler won't start since interrupts are masked.
• StartTx turns off the radio, prepares it for transmit, then starts transmitting.
• We leave the critical block, interrupts are enabled again.
• RSSI averaging done interrupt handler runs at this point which will turn off the radio, aborting the current transmit.

One way to avoid the problem above is to clear interrupts in the critical block. This can be done by using RAIL_Idle(handle, RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS, true) at the beginning of the critical block, but the drawbacks of doing so (mentioned above) should be kept in mind. In general, it's better to avoid risky interrupts without using critical blocks in the main thread.

Using FORCE_SHUTDOWN

In the two sections above we mentioned two usecases where RAIL_IDLE_FORCE_SHUTDOWN_CLEAR_FLAGS can be useful. In general however, RAIL_IDLE or RAIL_IDLE_ABORT is a sufficient and preferred way to stop transmitting/receiving - therefore the FORCE_SHUTDOWN modes should be only used when they are really needed (as in the specific scenarios described here). For more details, see the article on the idle modes.

The following signals are necessary for RX direct mode

RX data clock output

RX data output

You can assign them to any radio GPIO pin by setting the corresponding GPIO_MODE to RX_DATA_CLK or RX_DATA via the GPIO_PIN_CFG command.

The following signals are necessary for TX direct mode

TX data clock output

You can assign it to any radio GPIO pin by setting the corresponding GPIO_MODE to TX_DATA_CLK via the GPIO_PIN_CFG command.

TX data input

The TX_DIRECT_MODE_GPIO field of the MODEM_MOD_TYPE property determines which radio GPIO pin is selected as the modulation data source during TX Direct mode. Also the GPIO_MODE of the corresponding radio GPIO has to be set to INPUT via the GPIO_PIN_CFG command.

When generating the configuration from WDS, GPIO mode can be selected on the "GPIO and FRR" tab of the configurator. However the TX_DIRECT_MODE_GPIO field is left by WDS always in the default GPIO0 setting and can be modified only by hand in the generated config header.

Note 1: For Si4x55 the TX data input can be assigned only to GPIO0.

Note 2: For active signals like data and clock, the GPIO0 and GPIO1 pins should be primarily used , because these have less susceptibility to generating spurious components in the synthesizer than GPIO2 and GPIO3 have.

Content

• Motivation
• The Theory
• Realizing in RAIL
• Examples
  • Typical use cases
  • Further development

Motivation

I used to play quiz game with my friends, but when we needed to determine who was the first, who put his hand after a question arose, we get into disagreement. For this I was long thinking about a simple wireless system, what is able to decide who will be the responder, taking the responsibility (and our annoyance as well) out. This system should consist of one central device and any number of nodes, enhancing the network scalability, and the synchronization process should be simple and quick as well (capable to be done even for every new question), enabling simultaneous synchronization. This task may be done through existing solutions like Bluetooth or Wi-Fi, but I want accuracy in the order of microseconds, to be as precise as possible. RAIL time base is suitable for this, as it is in microseconds. It's not the best example to show the strength of synchronization, but I will cover here in this KBA some other examples.

This KBA presents a solution to synchronize networks containing one Master device and one or more Slave devices.

Application examples

There are many examples around us to everyday use of time synchronization including but not limited to the following.

GPS and other localization examples

Probably the most known application example of time synchronization is GPS (Global Positioning System). The synchronization is necessary to measure distance with wireless devices, as the distance is derived from the amount of time, since we know the velocity of light spreading through the air (vacuum). And if we can measure distance the next step is the positioning or localization.

Multihop network synchronization

If a computer connects to the internet, there is an opportunity right away to synchronize it to the global time (NTP). Since it is a multihop network, the delay from the reference time does increase, so the accuracy decrease with the number of hops.

Similarly, if the task is the scheduling a bunch of sensor nodes spanning a large geographical area it can be solved with time synchronization, where the nodes synchronize their neighbor nodes.

Low duty cycle

If you are not familiar with the term of Low duty cycle (LDC) take a look at this article.

This technology helps to save energy using lower power energy modes with a less accurate timer. There may be need for regular synchronization between the nodes, to minimize the active time along with the consumption, though this process handled automatically due to the communication.

The Theory of Operation

In the context of time synchronization it is good enough for the most application to have one reference time, which is known to all device, and in most cases this is the time of one particular device which dictates the system time. It gives the opportunity to schedule events in a common time base. We will refer to this device, which serves the reference time, as Master, and to the others as Slaves.

The synchronization means that one Slave device tries to estimate the Master's time, and then its operation scheduled in that assumed time base. We intentionally used the 'try' verb, because a synchronization is always inaccurate and requires regular adjustments. Though a simple synchronization can be done very quickly, the hardest part of the process is the evaluation of this inaccuracy, and the (sequential/continuous) correction, especially in a dense network, with a couple of Slave devices.

Time synchronization involves a several new terms which are describing delay times. Without completeness those are:

1. Warmup time (including channel access time): the time from assembling packet, through requesting the radio module to send, to the start of the first bit's transmission.
2. Transmission time: the time while the packet is on-the-air, from the first bit (end of Warmup time) to the last.
3. Propagation time: the time starting from related parts of the packet leave the transmitter and reach receiver (relative: doesn't have beginning nor end).
4. Reception time: similarly to the Transmission time, the time while the packet is on-the-air, till the end of the last bit of packet have been totally received.
5. Processing time: time to process received packet.
6. Settling time: time to set the time base at the receiver to the assumed time base of the transmitter (have not found this time in the literature, but the example application use this).

Using these delay terms and the terms describing difference of two clocking system the inaccuracy can be quantized.

Errors in/during/after synchronization

In terms of Time synchronization two types of error could occur. One is the offset error and the other is the dynamic or slope error (clock drift). Synchronization is nothing more than the elimination of these errors.

The offset error is very straightforward, it is the error measured between two devices right after the synchronization. This kind of error come from the incorrect calculation of delay times. It is a zero-order (constant) error.

The dynamic error is the speed difference between the clocks of the two devices. This is caused by the speed difference of the two oscillator. The dynamic error can be reduced by calibrating the clocking systems to a common reference (e.g. CTune calibration). The quality of this error is in first-order.

These errors might change during the lifetime of a system: as the temperature changes, the oscillators' frequencies change as well. This may be compensable with CTune calibration.

Measuring the errors

The task of synchronizing is very similar to a geometry exercise, finding a straight line in a coordinate system. This task requires a point and a slope or two points in a defined coordinate system. In this metaphor the coordinate system is defined by the "real time" and the Master's time base (assuming the Master device uses a 0ppm clock).

In the figures below the x axis represents the real time, and the y is the (discrete) value of time with the devices' metric (RAIL Time base, which is actually 1μs), the solid line represents the Master's time while the dotted line is the Slave's time.

Offset error compensation

Let's assume first that the slopes are the same (the clocks run at the same speed), therefore we need only a well defined point for the line fitting. With this assumption the offset error can be compensated in the following way:

1. Generate an event perceived by the master and slave devices
2. Get the event's timestamps on both side (~get to know the coordinate system)
3. Share Master's timestamp with the Slave(s) (~get to know the point on the coordinate system)
4. Compensate offset error on Slave(s)' side (~place the line on the coordinate system)

The task is to be able to figure out the what is the time on both the Master and the Slave at a given time, using the Slave's time base - It will be different, since they weren't powered up at the same time, thus the counters hold different values.

As a first step it should happen such an event which is perceived on both the Master and the Slave device. It is evident that this event may be a packet transmission and reception, therefore the delay times have to be known. As a result two timestamp generated on each device. Such an event will provide enough information to get the offset error. The clearest way to send a message from the Master, which is received by the Slave(s).

The next step is to share the Master's timestamp with the Slave device(s). It means that Master should send an another message, which holds the previous message's timestamp. From this message, the Slave(s) will know much its local clock differs from the Master's clock - the offset error - and will know more or less what time is it on the other at present (with the initial assumption).

Dynamic error compensation

In the real world there is always some difference between the clock systems. This is where the dynamic error takes place, and we should compensate it as well.

This can be done in a very similar way as we saw it in the previous section: we should repeat the process. This means getting an another point on the coordinate system, and from this information the to get the first-order error (the slope, or we can say that the velocity of the offset error's increase) can be defined and the dynamic error can be eliminated.

This process requires only 3 packet to be sent from a Master device, as the second packet, which holds the first packet's timestamp has it's own timestamp, which can be sent in the third packet.

Once these errors are known, they can be eliminated by calculation (software) or by modifying the clocking system (hardware) to be synchronized.

Implementation in RAIL

Possibilities

RAIL supports timestamping for both the transmitted and the received packet. The enum RAIL_PacketTimePosition_t defines the possibilities timestamp positions. The available positions are:

• the start of the preamble (first preamble bit sent or received)
• end of the syncword (last syncword bit sent or received),
• end of the packet (last bit of the packet sent or received).

In fact, at TX side only the end of the packet will be recorded as timestamp, and the other timestamps calculated relatively from this value. This implies additive error due to dynamic error in case of a very long packet (though it is almost negligible). Furthermore this means that there is no way to timestamp the packet, then send out the timestamp in that same packet.

NOTE: This will change in the future on some devices!

Since we won't use long packets in such an application, and this difference from dynamic error would be eliminated with the offset error compensation, we chose the timestamp position to the end of syncword (though it does not have any benefit).

The synchronization process

This image shows the synchronization process:

The red part is the preamble and the syncword of the packet. The Slave must save the timestamp of first packet's end (T_s) as well as the Master (T_m). The difference between the two timestamp is the propagation time (T_prop). Then in the second packet the Master device should send T_m, which is in its own time base. Finally the Slave device receiving T_m will know the difference between its own and the Master's time base eliminating the offset error, whic is the first step of synchronization.

But then, after a while, the error between the time assumed by the Slave, and the real time according to the Master's time base will differ due to HFXO clock deviation. This can be reduced repeating the previous step and "predicting" the masters new T_m from the last known value. The difference of the actual and the predicted T_m shows whether the Slave clocks are slower or the Master's. That way the slope error can be estimated. The accuracy of the estimation improves with the increasing delay between the synchronizations.

One can add the question: what about the delay times? We did not care about most of them (ones have definite beginning and end), due to the timestamp system of RAIL eliminates them. We didn't care about the propagation time either, since it is less than 1 us (what is the resolution of our timer) if the distance between the two device is less than 300 m.

Explanation of the code

The application is based on the example "simple-rail-with-hal" for BRD4169B and BRD4164A radio boards (EFR32MG14/MG12) which was used with WSTK. The application is using the Command interpreter Plugin, thus "Virtual COM Port" has to be enabled in the hardware configurator. No other modification should be made in the radio and hardware configurator.

The application was extended with two additional packet: One from the Slave with an assumed value (T_predict) to the Master's second packet's timestamp, and with a compensation feedback (T_comp) from the Master, which tells the Salve how accurate the prediction was.

Caution: This is only a demonstration project, we want to show the synchronization process in the simplest way, so our implementation can be improved. Furthermore it contains features assisting debug. Here are some notes what you should avoid in your design.

• Don't use the RAIL_SetTime() API in that way, as it is used here.
• The blocking delay implementation is not recommended. A timer interrupt routine may be more elegant in your project.
• Starting Master without Slave (or vice versa) will stuck while it won't get any packet. You should reset the device to exit this state.

States and roles

The application operates upon a state machine, equipped with command line interface, GPIO interrupt handlers for push buttons, and with radio event handling functionality. 5 state was implemented for both Master and Slave(s). Those are matching to each other. These are:

1. Waiting for start (pushbutton or CLI command),
2. Sending/receiving first packet from Master (produce timestamps T_m_1 and T_s_1),
3. Sending/receiving second packet from Master (produce T_m_2 and T_s_2 and send/get T_m_1),
4. Sending/receiving first packet from Slave (send T_predict for predicting T_m_2),
5. Sending/receiving third packet from Master (get T_comp).

A single application has been developed with two roles: there is a run-time variable to select whether a device is Master (default) or Slave.

typedef enum MasterStates {
   MASTER_WAIT, MASTER_STATE_SEND_FIRST_PACKET, MASTER_STATE_SEND_SECOND_PACKET,
} MasterStates_t;

typedef enum MasterStates {
  MASTER_WAIT, MASTER_STATE_SEND_FIRST_PACKET, MASTER_STATE_SEND_SECOND_PACKET,
} MasterStates_t;

typedef enum Role {
  ROLE_MASTER, ROLE_SLAVE
} Role_t;
...
static Role_t role = ROLE_MASTER;

The CLI commands

The application implements 5 cli commands:

• cliSetRole selects between Master (0) and Slave (1) roles,
• cliStart starts a synchronization process (if the argument is 1),
• cliSetCtune sets the CTune value (second argument); if the first argument is 0 the second argument will be used as CTune, if 1 the second argument will be saved to the User Page first, if 2 the CTune value will be fetched from the User Page and the second argument will not take any effect,
• cliGetTime prints the current time,
• cliGetVal prints one of the timestamps or calculations (for debug use only).

The interrupt handler routines

The interrupt handling routines are mostly setting flags which are monitored in the main loop.

static volatile bool sent = false;
static volatile bool received = false;
static volatile bool start = false;

The left pushbutton (PB1) does exactly the same thing as cliStart command does, while the right (PB0) operates as cliGetTime.

void gpioCallback(uint8_t pin) {
  if (pin & 0x01) {
    start = true;
  } else {
    RAIL_Time_t t = RAIL_GetTime();
    printf("time %d\n", t);
  }
}

The enabled radio events are the RX and TX related ones. Only for the successful events are handled in this application, RAIL_EVENT_TX_PACKET_SENT and RAIL_EVENT_RX_PACKET_RECEIVED. Every packet transmission and reception refreshes the timestamp value bound to the syncword's last bit.

static volatile RAIL_PacketTimeStamp_t timeStamp;
...

RAIL_Events_t events = (RAIL_EVENTS_TX_COMPLETION | RAIL_EVENTS_RX_COMPLETION);
RAIL_ConfigEvents(railHandle, events, events);

...

void RAILCb_Generic(RAIL_Handle_t railHandle, RAIL_Events_t events) {
  
  if (events & RAIL_EVENT_TX_PACKET_SENT) {
    // Set flag for the main loop
    sent = true;

    RAIL_TxPacketDetails_t packetDetails = { .timeSent = timeStamp .isAck = false };
    RAIL_GetTxPacketDetails(railHandle, &packetDetails);

    timeStamp = packetDetails.timeSent;
    // Don't print in the event handler! We do that for demonstration only.
    printf("packet sent\n");
  }

  if (events & RAIL_EVENT_RX_PACKET_RECEIVED) {
    // Set flag for the main loop
    received = true;

    // Get the newest packet's information from RX FIFO
    RAIL_RxPacketInfo_t packetInfo;
    RAIL_RxPacketHandle_t packetHandle = RAIL_RX_PACKET_HANDLE_NEWEST;
    RAIL_GetRxPacketInfo(railHandle, packetHandle, &packetInfo);

    // Set the position of the packet where the timestamp should be acquired,
    // and the packet's length to calculate it correctly
    timeStamp.timePosition = RAIL_PACKET_TIME_AT_PACKET_END;
    timeStamp.totalPacketBytes = packetInfo.packetBytes;
    RAIL_RxPacketDetails_t packetDetails = { .timeReceived = timeStamp };
    RAIL_GetRxPacketDetails(railHandle, packetHandle, &packetDetails);

    RAIL_CopyRxPacket(rxPacket, &packetInfo);

    RAIL_ReleaseRxPacket(railHandle, packetHandle);

    timeStamp = packetDetails.timeReceived;
    RAIL_ResetFifo(railHandle, false, true);
    // Don't print in the event handler! We do that for demonstration only.
    printf("packet received %d\n", timeStamp.packetTime);
  }

}

Manual calibration

In this section we will present how the application works.

After flashing the binary to two device we connected their serial ports to a PC. In the serial terminal we should only issue a setRole 1 command to select the slave device. Push the PB1 first on the slave (this will enable RX) and then on the master (send the first message). After some milliseconds the two device will be synchronized.

We can prove that the the devices are synchronized by getting the current time from both device in the same time. This can be done with pushing PB0, while the two GPIO lines are connected. The button's line can be found at the seventh pin of the external pin header connector on the WSTK (using the BRD4169B radio boards).

I pushed PB0 per ~1 second, and the two terminal windows printed the following timestamps (in microseconds):

The first time pair shows that the slave counts 3 more us than the master device, and in ~29 seconds the difference increased to 16 us. It means that the slave's clock ran faster causing 1 us drift per ~2.25 second (slope error).

Adjusting CTune (with the SetCtune command) this kind of error can be minimized (increasing on the slave to slow down, or decreasing on the master to speed up the oscillator).

This accuracy is now good enough for my quiz application.

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.