SNTP Client

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_addr	Pointer 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_port	The source UDP port of the NTP response, or the UDP port of the NTP server targeted by the unsuccessful query.
[in]	process_result	The value of this parameter reveals whether a response from the NTP server or a timeout triggered the callback.
[in]	callback_parameter	This 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_param

Pointer 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_SUCCESS	Module successfully initialized.
NRF_ERROR_NULL	If 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_time

Local unix time.

Return values

NRF_SUCCESS	Getting locally stored unix time successful.
SDK_ERR_MODULE_NOT_INITIALIZED	The module was not initialized.
NRF_ERROR_NULL	If 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_address	Pointer to the IPv6 address of the NTP server. This memory must be resident until the query is completed.
[in]	ntp_server_udp_port	Destination port of the NTP server. The UDP port number assigned by the IANA to NTP is 123.
[in]	sync_local_time	A boolean value telling the module whether to synchronize its local clock with any response received from the NTP server.

Return values

NRF_SUCCESS	SNTP query successfully sent.
SDK_ERR_MODULE_NOT_INITIALIZED	The module was not initialized.
NRF_ERROR_NULL	If 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_value

The 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_SUCCESS	Module successfully uninitialized.
SDK_ERR_MODULE_NOT_INITIALIZED	The module was not initialized.