Component - Clock Synchronization¶

Introduction¶

Clock Synchronization is a Modem service that provides the time for user applications and some operations (for example, a GNSS assisted scan).

Compatibility¶

Prerequisites¶

Common:

• The device must be joined to a LoRaWAN® network

• The application server must forward messages on a configured Device Management FPort (199 by default) to mgs.loracloud.com.

Prerequisites for LoRa Basics™ Modem:

• The device must have a Real Time Clock (RTC).

Prerequisites for LoRa Basics™ Modem-E:

• 32.768 kHz crystal or the externally supplied clock to the LR1110 chip.

Step-by-Step Procedure¶

1. Enable Clock Sync on the device. (Clock Sync is disabled by default).

2. Wait for the event timeUpdatedClockSync (with parameter status=1: time sync done).

3. When synced, the getTime() command fetches the time from the device in GPS epoch format: seconds elapsed since 00:00:00 January 6th 1980.

4. If the device loses its time sync (that is, after six days without resynchronizing with the server) the timeUpdateClockSync event is triggered (with the parameter status=0: time sync lost). The user must then wait for the clock to be synchronized again.

Sample Code¶

Embedded

#include "lr1110_modem_lorawan.h"

// Activate Clock Sync
lr1110_modem_set_alc_sync_mode( &context, LR1110_MODEM_ALC_SYNC_MODE_ENABLE );

// Get time since GPS epoch (elapsed seconds since 00:00:00 January 6th 1980)
uint32_t gps_time = 0;
lr1110_modem_get_gps_time( &context, &gps_time );

// Modem event call-back
customer_event_callback_alc_sync_time_update( lr1110_modem_alc_sync_state_t status ) {
   if ( status == LR1110_MODEM_ALC_SYNC_DESYNCHRONIZED ) {
      printf( "ALCSYNC - Lost time synchronization\n" );
   } else {    // status == 1
      printf( "ALCSYNC - Acquired time synchronization\n" );
   }
}

In-depth Behavior¶

This service assumes that there is little or no delay in the Clock Sync request from either the LoRa Basics™ Modem or LoRa Basics Modem-E. Any delay introduced on this request will create an offset in a Modem’s time. There is no requirement on downlink timing.

The possible states are as follows.

Not Synchronized

1. Once enabled, the modem sends Clock Sync requests to the LoRa Cloud™ Modem & Geolocation Services for the initial time synchronization.

2. The LoRa Cloud™ Modem & Geolocation Services asks the application server to queue a downlink with its answer.

Recent Synchronization (less than 3 days)

1. Every 36 hours the modem sends an Clock Sync request to the LoRa Cloud™ Modem & Geolocation Services.

2. If the modem clock has drifted, the LoRa Cloud™ Modem & Geolocation Services asks the application server to queue a downlink with its answer.

No Recent Synchronization (more than 3 days)

1. Every 36 hours the modem sends an Clock Sync request to the LoRa Cloud™ Modem & Geolocation Services, asking for a mandatory answer.

2. The LoRa Cloud™ Modem & Geolocation Services asks the application server to queue a downlink with its answer.

De-synchronized

If the modem gets no update after six (6) days it will consider its time not valid.

Used by¶

Troubleshooting¶

References¶

• LoRa Basics™ Modem-E API Reference Manual chapters 2.3.4, 6.8, 6.52 and 6.53.