Simple Network Time Protocol (SNTP)

Table of Contents

• Code examples
  • Initializing the module
  • Sending an SNTP query
  • Getting the local Unix time
  • Uninitializing the module
• Configuration parameters
• Implementation specific limitations

The SNTP Client SNTP client module is a Simple Network Time Protocol Version 4 (SNTPv4) client implementation. It provides a local clock in the Unix time format and can query a Network Time Protocol (NTP) server and synchronize the local clock to the server time source.

The SNTP client requires the IoT Timer module to be present.

At initialization the local clock is set to zero, which is equivalent to the Unix epoch time 00:00:00 UTC on 1 January 1970. The local clock can be synchronised with an NTP server with the sntp_client_server_query procedure. The module can be configured at initialization to provide asynchronous callbacks when a server response is received or when a query times out. The conversion between the NTP timestamp format and the Unix time format is done automatically.

The sntp_client_local_time_get procedure provides the local time without querying an NTP server. The elapsed time since the last synchronisation with an NTP server is calculated from the wall clock value of the IoT Timer module. Therefore, the accuracy of the local clock is limited by the value of IOT_TIMER_RESOLUTION_IN_MS.

The SNTP Client module can be uninitialized with the sntp_client_uninitialize procedure. This frees up the UDP socket allocated for the module.

Code examples

Initializing the module

#define SNTP_MAX_RETRANSMISSION_COUNT       2
#define SNTP_RETRANSMISSION_INTERVAL        2

void sntp_evt_handler(const ipv6_addr_t * ntp_srv_addr, \
                      uint16_t ntp_srv_udp_port,        \
                      uint32_t process_result,          \
                      sntp_client_cb_param_t callback_parameter)
{
    /*  ...  */
}

static void sntp_c_init(void)
{
    uint32_t err_code = NRF_SUCCESS;
    static sntp_client_init_param_t sntp_client_init_param;

    // Set the local UDP port.
    sntp_client_init_param.local_udp_port  = 55000;
    // Set the event handler callback procedure. It can be set to NULL to disable callbacks.
    sntp_client_init_param.app_evt_handler = sntp_evt_handler;

    err_code = sntp_client_init(&sntp_client_init_param);
    APP_ERROR_CHECK(err_code);
}

int main(void)
{
    /*  ...   */

    iot_timer_init();   // The IoT Timer module needs to be present.
    sntp_c_init();

    /*  ...   */
}

Sending an SNTP query

#define NTP_SERVER_DEFAULT_PORT 123

// The NTP server address is assumed by the API to be resident memory, thus the variable is not 
// to be changed between the start and completion of an SNTP query.
static ipv6_addr_t m_ntp_server_address = { .u8 = {0x26, 0x07, 0xfe, 0x70, 0x00, 0x00, 0x00, 0x16, \
                                                   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0a} };

int main(void)
{
    uint32_t err_code = NRF_SUCCESS;
    /*  ...   */

    err_code = sntp_client_server_query(&m_ntp_server_address, \
                                        m_ntp_server_port,     \
                                        true);
    APP_ERROR_CHECK(err_code);

    /*  ...   */
}

Getting the local Unix time

void procedure(void)
{
    /*  ...   */

    time_t local_unix_time;
    uint32_t err_code = sntp_client_local_time_get(&local_unix_time);
    APP_ERROR_CHECK(err_code);

    /*  ...   */
}

Uninitializing the module

void procedure(void)
{
    /*  ...   */

    time_t current_local_time;
    uint32_t err_code = sntp_client_uninitialize();
    APP_ERROR_CHECK(err_code);

    /*  ...   */
}

Configuration parameters

The following configuration parameters should be defined in sdk_config.h.

SNTP_MAX_RETRANSMISSION_COUNT

Maximum number of retransmissions of a query. Set this define to 0 to disable retransmission attempts.

Description	Value
Minimum value	0
Maximum value	255
Dependencies	None

SNTP_RETRANSMISSION_INTERVAL

Interval between retransmissions in seconds.

Description	Value
Minimum value	1
Maximum value	None
Dependencies	None

SNTP_CLIENT_DISABLE_API_PARAM_CHECK

Disables API parameter checks in the module. Set this define to 1 to disable checks on API parameters in the module.

API parameter checks are added to ensure that the correct parameters are passed to the module. These checks are useful during development phase, but they might be redundant when the application is finalized. Disabling these checks might improve performance.

Description	Value
Enable API parameters check	0
Disable API parameters check	1
Dependencies	None

SNTP_CLIENT_DISABLE_LOGS

Disables debug tracing in the module. To enable tracing, this flag must be set to 0 and ENABLE_DEBUG_LOG_SUPPORT must be set to 1.

Description	Value
Enable debug trace	0
Disable debug trace	1
Dependencies	ENABLE_DEBUG_LOG_SUPPORT

Implementation specific limitations

• Parallel queries are not supported.
• The exponential-backoff algorithm for retransmissions (as described in RFC 4330) is not implemented, and retransmissions are triggered at regular intervals.