Simple Network Time Protocol

ESP has built-in support for Simple Network Time Protocol (SNTP). It is support through middleware API calls for configuring servers and reading actual date and time.

Minimum SNTP example
 1/*
 2 * A simple example to get current time using SNTP protocol
 3 * thanks to AT commands being supported by Espressif
 4 */
 5#include "sntp.h"
 6#include "lwesp/lwesp.h"
 7
 8/**
 9 * \brief           Run SNTP
10 */
11void
12sntp_gettime(void) {
13    struct tm dt;
14
15    /* Enable SNTP with default configuration for NTP servers */
16    if (lwesp_sntp_set_config(1, 1, NULL, NULL, NULL, NULL, NULL, 1) == lwespOK) {
17        lwesp_delay(5000);
18
19        /* Get actual time and print it */
20        if (lwesp_sntp_gettime(&dt, NULL, NULL, 1) == lwespOK) {
21            printf("Date & time: %d.%d.%d, %d:%d:%d\r\n", (int)dt.tm_mday, (int)(dt.tm_mon + 1),
22                   (int)(dt.tm_year + 1900), (int)dt.tm_hour, (int)dt.tm_min, (int)dt.tm_sec);
23        }
24    }
25}
group LWESP_SNTP

Simple network time protocol supported by AT commands.

Functions

lwespr_t lwesp_sntp_set_config(uint8_t en, int16_t tz, const char *h1, const char *h2, const char *h3, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Configure SNTP mode parameters. It must be called prior any lwesp_sntp_gettime can be used, otherwise wrong data will be received back.

Parameters

  • en – [in] Status whether SNTP mode is enabled or disabled on ESP device

  • tz – [in] Timezone to use when SNTP acquires time, between -12 and 14

  • h1 – [in] Optional first SNTP server for time. Set to NULL if not used

  • h2 – [in] Optional second SNTP server for time. Set to NULL if not used

  • h3 – [in] Optional third SNTP server for time. Set to NULL if not used

  • evt_fn – [in] Callback function called when command has finished. Set to NULL when not used

  • evt_arg – [in] Custom argument for event callback function

  • blocking – [in] Status whether command should be blocking or not

Returns

lwespOK on success, member of lwespr_t enumeration otherwise

lwespr_t lwesp_sntp_get_config(uint8_t *en, int16_t *tz, char *h1, char *h2, char *h3, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get current SNTP configuration.

Todo:

Parse response for hostnames, which is not done at the moment

Parameters

  • en – [in] Pointer to status variable

  • tz – [in] Pointer to timezone

  • h1 – [in] Optional first SNTP server for time. Set to NULL if not used, otherwise value is copied into the pointer. Must be sufficient enough

  • h2 – [in] Optional second SNTP server for time. Set to NULL if not used otherwise value is copied into the pointer. Must be sufficient enough

  • h3 – [in] Optional third SNTP server for time. Set to NULL if not used otherwise value is copied into the pointer. Must be sufficient enough

  • evt_fn – [in] Callback function called when command has finished. Set to NULL when not used

  • evt_arg – [in] Custom argument for event callback function

  • blocking – [in] Status whether command should be blocking or not

Returns

lwespOK on success, member of lwespr_t enumeration otherwise

lwespr_t lwesp_sntp_set_interval(uint32_t interval, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Set SNTP synchronization interval on Espressif device SNTP must be configured using lwesp_sntp_set_config before you can use this function.

Note

This command is not available for all Espressif devices using AT commands and will return error when this is the case.

Parameters

  • interval – [in] Synchronization interval in units of seconds. Value can be set between 15 and 4294967 included

  • evt_fn – [in] Callback function called when command has finished. Set to NULL when not used

  • evt_arg – [in] Custom argument for event callback function

  • blocking – [in] Status whether command should be blocking or not

Returns

lwespOK on success, member of lwespr_t enumeration otherwise

lwespr_t lwesp_sntp_get_interval(uint32_t *interval, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get SNTP synchronization interval on Espressif device SNTP must be configured using lwesp_sntp_set_config before you can use this function.

Note

This command is not available for all Espressif devices using AT commands and will return error when this is the case.

Parameters

  • interval – [in] Pointer to variable to write interval. It is value in seconds. It must not be NULL

  • evt_fn – [in] Callback function called when command has finished. Set to NULL when not used

  • evt_arg – [in] Custom argument for event callback function

  • blocking – [in] Status whether command should be blocking or not

Returns

lwespOK on success, member of lwespr_t enumeration otherwise

lwespr_t lwesp_sntp_gettime(struct tm *dt, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get time from SNTP servers SNTP must be configured using lwesp_sntp_set_config before you can use this function.

Parameters

  • dt – [out] Pointer to struct tm structure to fill with date and time values

  • evt_fn – [in] Callback function called when command has finished. Set to NULL when not used

  • evt_arg – [in] Custom argument for event callback function

  • blocking – [in] Status whether command should be blocking or not

Returns

lwespOK on success, member of lwespr_t enumeration otherwise