LoRa Basics Modem and LoRa Edge documentation

Component - Application Layer Clock Synchronization

Introduction

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

Compatibility

LoRa Basics Modem

LoRa Basics Modem-E

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 das.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.

Step-by-Step Procedure

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

  2. Wait for the event timeUpdatedAlcSync (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 timeUpdateAlcSync event is triggered (with the parameter status=0: time sync lost). The user must then wait for the clock to be synchronized again.

Note

The getTime() command returns 0 when the time is not synchronized or has lost its synchronization. If the time is set with setTime(), no event is generated. The time is considered not valid after six (6) days without a new call to the setTime() command.

Sample Code

Embedded

#include "lr1110_modem_lorawan.h"

// Activate ALC 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 ALC 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.

Note

As per the LoRaWAN specification, the LoRa Cloud™ Device & Application Services will answer only if the timing inaccuracy of the LoRa Basics Modem or LoRa Basics Modem-E is more than one (1) second when the bit AnsRequired is not set.

The possible states are as follows.

Not Synchronized

  1. Once enabled, the modem sends ALC Sync requests to the LoRa Cloud Device & Application Services for the initial time synchronization.

  2. The LoRa Cloud Device & Application Services ask the application server to queue a downlink with its answer.

Recent Synchronization (less than 3 days)

  1. Every 36 hours the modem sends an ALC Sync request to the LoRa Cloud Device & Application Services.

  2. If the modem clock has drifted, the LoRa Cloud Device & Application 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 ALC Sync request to the LoRa Cloud Device & Application Services, asking for a mandatory answer.

  2. The LoRa Cloud Device & Application 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.

@startuml _alc_sync_flowtitle Simplified order of operations for\nApplication Layer Clock synchronizationskinparam linetype orthobox Device #ADD8E6    participant "End-Device Application" as UC #ADD8E6    participant "LoRa Basics™\nModem(s)" as modem #00ADEFend boxbox LoRaWAN® #AAAAAA    participant "Network Server" as NS  #D3D3D3end boxbox Cloud #ADD8E6    participant "Application Server" as AppS #ADD8E6end boxbox LoRa Cloud™ #00ADEF    participant "Device & Application Services" as DAS #00ADEFend boxlegend left|=             |= Owner || <#00ADEF>    | Semtech || <#ADD8E6>    | Customer || <#D3D3D3>    | Ecosystem |endlegend== Not Synchronized State ==UC -> modem : Enable ALC syncmodem -> NS ++: Uplink with ALC sync requestNS -> AppS : Uplink with ALC sync requestactivate AppSAppS -> DAS : Call uplink/sendactivate DASreturn Downlink request with\nALC sync responsereturn Downlink ALC sync responsereturn Downlink ALC sync responsemodem --> UC : Time Updated ALC sync event== Recent Synchronization State ==loop First 3 days    ... Every 36 hours ...    modem -> NS ++: Uplink with ALC sync request    NS -> AppS ++: Uplink with ALC sync request    AppS -> DAS ++: Call uplink/send    return Optional downlink request\nwith ALC sync response    note right        The downlink request from DAS is optional.        The DAS decides if the modem clock should        be updated or not.    end note    return Optional downlink\nALC sync response    NS --> modem --: Optional downlink\nALC sync responseend== No Recent Synchronization State ==loop Between 3 and 6 days    ... Every 36 hours ...    modem -> NS ++: Uplink with ALC sync request    NS -> AppS ++: Uplink with ALC sync request    AppS -> DAS ++: Call uplink/send    return Downlink request\nwith ALC sync response    note right        In this state, the DAS must return        the ALC sync response    end note    return Downlink\nALC sync response    NS --> modem --: Downlink\nALC sync responseend@enduml

Used by

GNSS

Troubleshooting

Time is never synchronized

The time request has probably not been delivered to the LoRa Cloud Device & Application Services, or the LoRa Cloud Device & Application Services’ answer has not reached the modem.

  1. Determine whether uplinks are being correctly delivered to the LoRa Cloud Device & Application Services.

  2. Determine whether the LoRa Cloud Device & Application Services are creating a downlink when they receive an ALC Sync request (a DM frame with first byte equal to 0x18).

  3. Ensure that the LoRa Cloud Device & Application Services’ downlinks are being sent to the modem.

Synchronized time has an offset of several minutes

There might be a delay between the ALC Sync uplink sent by the modem and its delivery to the LoRa Cloud Device & Application Services. To address this issue, review this recommendation.

References