Skip to content

Network time

Nodes in a Mira network can perform highly synchronised actions by scheduling tasks to be performed by the network time. The network time can be obtained in a resolution of 10ms, but is synchronized to 50us relative to the root device.

Types

Name Type Description
mira_net_time_t uint32_t
mira_net_time_schedule_callback void(* )(mira_net_time_t tick, void *storage)

Functions

mira_net_time_get_time

mira_status_t mira_net_time_get_time(
    mira_net_time_t*  tick);

Get current network time. The current network time is a global timer for the network. The time is guaranteed to be in sync between the nodes, when joined to the network.

The time is only available when joined to a network.

The resolution of the timer is set by the root node, by default in ticks of 10ms.

Parameters

Parameter Description
tick Storage for the time. Written to if MIRA_SUCCESS is returned.

Return

See enum definition.

Value Description
MIRA_SUCCESS Current network time successfully gotten.
MIRA_NET_ERROR_NOT_ASSOCIATED Node is not associated.

mira_net_time_get_tick_length

mira_status_t mira_net_time_get_tick_length(
    uint32_t*     tick_length);

Get current tick length. Get the length of a net timer tick, in microseconds. This is usually 10000 for 10ms, but may differ in some setups.

The value is only available when joined to the network

Parameters

Parameter Description
tick_length Storage for the tick length. Written to if MIRA_SUCCESS is returned.

Return

See enum definition.

Value Description
MIRA_SUCCESS Current network time successfully gotten.
MIRA_NET_ERROR_NOT_ASSOCIATED Node is not associated.

mira_net_time_schedule

mira_status_t mira_net_time_schedule(
    uint32_t                         tick,
    mira_net_time_schedule_callback  callback,
    void*                            storage);

Schedule a timed callback. Schedule a timed callback on a given tick. The resolution of a scheduled event is of one tick, but the precision of when the event is executed is within +/-50us.

The callback will only be executed if joined to the network. However, scheduling may be done while not associated, as long as the node associates before the time occurs.

If the time is by some reason missed, the callback will be executed at first available later time, having the "tick" value set to the time when the callback is executed. The user has to verify the tick value in the callback to the value scheduled to identify if the callback was executed at the correct time. Even if the callback is executed late, it is within the +/- 50us threshold from the tick.

Only one scheduled event may be scheduled at the same time. Rescheduling an event will overwrite the previous scheduled event without calling the callback.

To remove a scheduled an event, pass NULL as callback.

Warning: Do not schedule events too often. Keep the scheduled events at least a few seconds apart. Also, don't use strict periodic intervals, since it may affect network performance.

Warning: The callback is executed from within an interrupt. Care must be taken to not interfere with the system.

The callback must:

Also note that the callback is designed to interrupt other memory access from the application, and should therefore have proper protection against concurrent memory access.

Return

MIRA_SUCCESS if successful.