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¶

mira_net_time_t¶

typedef uint32_t mira_net_time_t;

mira_net_time_schedule_callback_t¶

typedef void(* mira_net_time_schedule_callback_t) (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¶

Name	Description
tick	Storage for the time.

Return value¶

Name	Description
MIRA_SUCCESS	Current network time stored successfully.
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. Default is 10000 for 10 ms, but may differ depending on root setup.

The value is only available when joined to the network.

Parameters¶

Name	Description
tick_length	Storage for the tick length.

Return value¶

Name	Description
MIRA_SUCCESS	Current network tick length successfully retrieved.
MIRA_NET_ERROR_NOT_ASSOCIATED	Node is not associated.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.

mira_net_time_schedule¶

mira_status_t mira_net_time_schedule(uint32_t tick, mira_net_time_schedule_callback_t 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 execution start is within +/-50us.

The callback only runs if associated to the network. Scheduling may still occur while not associated, as long as the node associates before the scheduled time.

If Mira misses the scheduled tick, it executes the callback at the first available later tick. In that case, the "tick" argument contains the tick value at which Mira executes the callback. Compare the tick value in the callback to the scheduled value, to identify a possible execution delay. Even if the callback runs at a later tick, it is within the +/- 50us span from that tick.

Only one callback may be scheduled at the a time. Rescheduling overwrites the previous schedule without calling the callback.

To remove a scheduled callback, reschedule with NULL as callback.

Note

Do not schedule callbacks too often. Keep the schedule times at least a few seconds apart and at non-constant intervals.

Note

The callback executes from within an interrupt. Only call interrupt-safe functions, and limit execution time.

The callback must:* not take longer than 3 ms

not call other Mira API methods other than process_poll()

Note: the callback interrupts other memory accesses from the application, and should therefore have proper protection against concurrent memory access.

Return value¶

Name	Description
MIRA_SUCCESS	Callback successfully scheduled.
MIRA_ERROR_NOT_INITIALIZED	Network stack is not initialized.