Hi,

It is not really a bug or a regression, but an usability issue: you can override any (locked or not locked) replace key with a new value with adding a new key-value pair (with the same key). Note that always the last added item will be the active.

Best Regards,
Bence

Hi Hamza,

The documentation of RAIL_AutoAckConfig_t structure's documentation can be found here. 
Did you enable RAIL_EVENT_RX_ACK_TIMEOUT event by the RAIL_ConfigEvents() API?

Best Regards,
Bence

Hi Terry,

This question was moved to the Bluetooth Forum.

Best Regards,
Bence

Hi,

I am developing on BGM13S32F512GA with SDK - BT Mesh v1.5.2 and BT 2.12.3.0.

I found that the OTA image could not be used while the OTA image was sent successfully.

 

The log from the host:

System rebooted
Local address:08:6b:d7:7c:6d:58
Bytes to send:388936
Scanning...OK
Device address found, connecting.
Connecting...OK
Discovering services...ATT MTU exchanged: 247
OK
Discovering characteristics...OK
    Control handle:79
    Data handle:81
    OTA Data characteristic properties:0x04
DFU mode...OK
OTA DFU - write without response
100% 51.01kbit/s
time: 61.00s
Finishing DFU block...OK
Closing connection...OK
 

 

The log from the device:

upload finished. received file size 388936 bytes
connection closed, reason: 0x213
Installing new image

 

However, the old image ran after reboot.

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.

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.

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 in the end of this KBA some other examples will be shown.

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.

Last question has a new topic here.

Hi James,

The actual load capacitance value may change from chip-to-chip and board-to-board, you will find more information under the EZCONFIG_XO_TUNE property description in the public API documentation.

I can confirm what the Application Note states, you should use 26 MHz crystal to avoid those issues.

You should tune the capacitor to get the frequency (emitting a CW signal) you set as Base frequency in WDS.

Best Regards,
Bence

Hi Avid,

Merging radio configuration files may work, but we do not recommend to do that. The only way we supporting is the configuration within the app builder.

We are currently working on enhancing the radio configurator, with which you may generate so large channel group configuration.

Best Regards,
Bence