System Clock Management¶

Logicrom provide system clock management using a time library with support for multiple time sources to sync system clock. Each time source has a priority predefined by the library.

Available time sources based on priority:

Network service provider (lowest priority)
NTP Service (available when enabled)
GPS Time (highest priority, available when gps library is used)

A custom time source can also be added using time source API.

API Reference¶

Header File¶

Source: include/libtime.h

#include <libtime.h>

Functions¶

int clock_src_register(const struct clocksrc_t *src)¶

Register clock sync source, clock is considered invalid by default

Parameters: src – [in] Clock source structure pointer clocksrc_t
Returns: 0 on success, negative value on error

int clock_src_setvalid(const char *name, int status)¶

Set clock source as valid, after clock source is marked valid system will call clocksrc_t::sync_cb after 30s.

Parameters

name – [in] Clock source name
status – [in] 1 for valid, 0 for invalid

Returns

0 on success, negative on error

int clock_src_getvalid(const char *name)¶

Get clock source valid status

Parameters: name – [in] Clock source name
Returns: returns 1 if valid, 0 if not valid

const char *clock_getsourcename(void)¶

Get currently used clock source name for system clock synchronization

Returns: returns clock source name

int clock_get_syncstatus(void)¶

Get system clock sync status

Returns: returns clkstatus_e

int clock_set_ntpserver(const char *server)¶

Set ntp server address, default is “service.logicrom.com”

Parameters: server – [in] NTP server domain or IP
Returns: return 0 on success, negative on error

const char *clock_get_ntpserver(void)¶

Get currently configured NTP server address

Returns: returns NTP server address

int clock_set_mode(int mode)¶

Set clock synchronization mode

Parameters: mode – [in] Clock mode clkmode_e
Returns: 0 on success, negative on failure

int clock_get_mode(void)¶

Get current clock synchronization mode

Returns: returns clockmode_e

int clock_sync(struct clocktm_t *timeval)¶

Update system clock, this function can be called from clock source sync callback to update system time.

Parameters: timeval – [in] Time structure with current time information
Returns: return 0 on success, negative on failure

Structures¶

struct clocksrc_t¶

Clock Source Structure

Public Members

const char *name¶: Clock Source name

int prio¶: Clock source priority clockprio_e

int sync_duration¶: Clock sync duration in seconds

int (*sync_cb)(void)¶: Clock source sync callback function

struct clocktm_t¶

Time structure for sync

Public Members

int year¶: Year from 0

int month¶: Month 1 to 12

int day¶: Day 1 to 31

int hour¶: Hour 0 to 23

int minute¶: Minute 0 to 59

int second¶: Second 0 to 59

int reserved¶: reserved must be 0

Macros¶

CLKSYNC_SECONDS(x)¶

CLKSYNC_MINUTE(x)¶

Enumerations¶

enum clkstatus_e¶

Clock status

Values:

enumerator CLK_STATUS_NOTSYNCED¶: System clock not synced

enumerator CLK_STATUS_SYNCED¶: System clock synced

enum clkprio_e¶

Clock Source priority, for multiple clock sources, highest priority source is selected for sync

Following are the library provided clock sources and their priorities:

Network Provider Clock : Low Priority¶

NTP : Medium Priority¶

GPS : High Priority¶

Values:

enumerator CLK_SRC_PRIO_VLOW¶: Priority very low

enumerator CLK_SRC_PRIO_LOW¶: Priority low

enumerator CLK_SRC_PRIO_MED¶: Priority medium

enumerator CLK_SRC_PRIO_HIGH¶: Priority high

enumerator CLK_SRC_PRIO_VHIGH¶: Priority Very High

enum clkmode_e¶

Clock synchronization mode select

Values:

enumerator CLOCK_MODE_AUTO¶: Auto Sync

enumerator CLOCK_MODE_MANUAL¶: Manual Sync