nRF5 IoT SDK  v0.9.0
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Simple Network Time Protocol (SNTP) client for obtaining and storing local unix time. More...

Data Structures

union  sntp_client_cb_param_t
 SNTP client callback parameter. More...
 
struct  sntp_client_init_param_t
 SNTP client initialization structure. More...
 

Macros

#define KISS_CODE_LEN   4
 

Typedefs

typedef void(* sntp_evt_handler_t )(const ipv6_addr_t *p_ntp_srv_addr, uint16_t ntp_srv_udp_port, uint32_t process_result, sntp_client_cb_param_t callback_parameter)
 SNTP client callback type. More...
 

Functions

uint32_t sntp_client_init (const sntp_client_init_param_t *p_sntp_client_init_param)
 Function for initializing the SNTP client module. More...
 
uint32_t sntp_client_uninitialize (void)
 Function for uninitializing the SNTP client module. More...
 
uint32_t sntp_client_server_query (ipv6_addr_t *p_ntp_server_address, uint16_t ntp_server_udp_port, bool sync_local_time)
 Function for sending an SNTP query to the specified NTP server. More...
 
uint32_t sntp_client_local_time_get (time_t *p_current_time)
 Function for getting the local unix time from the module. More...
 
void sntp_client_timeout_process (iot_timer_time_in_ms_t wall_clock_value)
 Function for performing retransmissions of SNTP queries. More...
 

Detailed Description

Simple Network Time Protocol (SNTP) client for obtaining and storing local unix time.

Concurrent queries are not supported. Exponential-backoff algorithm for retransmissions is not implemented, retransmissions are triggered at regular intervals.

Macro Definition Documentation

#define KISS_CODE_LEN   4

Kiss-o'-Death packets convey kiss codes as 4 character long ASCII messages.

Typedef Documentation

typedef void(* sntp_evt_handler_t)(const ipv6_addr_t *p_ntp_srv_addr, uint16_t ntp_srv_udp_port, uint32_t process_result, sntp_client_cb_param_t callback_parameter)

SNTP client callback type.

Execution of the callback function marks the completion of an SNTP query. The callback will be executed if a response is received from the NTP server, or if the server remains unresponsive even after SNTP_MAX_RETRANSMISSION_COUNT is reached.

Parameters
[in]p_ntp_srv_addrPointer to the source IPv6 address of the NTP response, or to the IPv6 address of the NTP server targeted by the unsuccessful query.
[in]ntp_srv_udp_portThe source UDP port of the NTP response, or the UDP port of the NTP server targeted by the unsuccessful query.
[in]process_resultThe value of this parameter reveals whether a response from the NTP server or a timeout triggered the callback.
[in]callback_parameterThis parameter holds the unix time from the server after a successful query, or the kiss code if a Kiss-o'-Death packet was received. Otherwise NULL.
Return values
None.

Function Documentation

uint32_t sntp_client_init ( const sntp_client_init_param_t p_sntp_client_init_param)

Function for initializing the SNTP client module.

The SNTP client uses UDP as transport layer, therefore, one UDP socket is allocated for the module and is used to transmit any future queries.

Parameters
[in]p_sntp_client_init_paramPointer to the initialization structure for the SNTP client. Should not be NULL.
Note
The event handler in the initialization structure can be set to NULL to disable callbacks from the module.
Return values
NRF_SUCCESSModule successfully initialized.
NRF_ERROR_NULLIf p_sntp_client_init_param is NULL, or if it points to a local UDP port that is NULL.
uint32_t sntp_client_local_time_get ( time_t *  p_current_time)

Function for getting the local unix time from the module.

The local unix time is set to zero (1-Jan-70) when the module is initialized. It can be updated by using sntp_client_server_query procedure. The accuracy of the output is depending on the wall clock of the IoT Timer module.

Parameters
[out]p_current_timeLocal unix time.
Return values
NRF_SUCCESSGetting locally stored unix time successful.
SDK_ERR_MODULE_NOT_INITIALZEDThe module was not initialized.
NRF_ERROR_NULLIf p_current_time is a NULL pointer.
uint32_t sntp_client_server_query ( ipv6_addr_t p_ntp_server_address,
uint16_t  ntp_server_udp_port,
bool  sync_local_time 
)

Function for sending an SNTP query to the specified NTP server.

The local unix time is set to zero (1-Jan-70) when the module is initialized. It can be updated by using the sntp_client_server_query procedure. The accuracy of the output is depending on the wall clock of the IoT Timer module.

Parameters
[in]p_ntp_server_addressPointer to the IPv6 address of the NTP server. This memory must be resident until the query is completed.
[in]ntp_server_udp_portDestination port of the NTP server. The UDP port number assigned by the IANA to NTP is 123.
[in]sync_local_timeA boolean value telling the module whether to synchronise its local clock with any response recieved from the NTP server.
Return values
NRF_SUCCESSSNTP query successfully sent.
SDK_ERR_MODULE_NOT_INITIALZEDThe module was not initialized.
NRF_ERROR_NULLIf p_ntp_server_address or ntp_server_udp_port is a NULL pointer.
void sntp_client_timeout_process ( iot_timer_time_in_ms_t  wall_clock_value)

Function for performing retransmissions of SNTP queries.

The SNTP client module implements the retransmission mechanism by invoking this function periodically. This procedure is to be added to the IoT Timer client list and has to be called repeatedly with a minimum period of SNTP_RETRANSMISSION_INTERVAL.

Parameters
[in]wall_clock_valueThe value of the wall clock that triggered the callback.
Return values
None.
uint32_t sntp_client_uninitialize ( void  )

Function for uninitializing the SNTP client module.

This procedure frees up the UDP socket previously allocated to the module. Any pending retransmissions are cleared and no more callbacks will be executed.

Return values
NRF_SUCCESSModule successfully uninitialized.
SDK_ERR_MODULE_NOT_INITIALZEDThe module was not initialized.