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 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_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 time 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.
Note
Do not schedule events too often. Keep the scheduled events at least a few seconds apart and at non-constant intervals.
Note
The callback is executed from within an interrupt. Care must be taken to not interfere with the system.
The callback must:* Not take longer than 3 ms * Not call other Mira API methods other than process_poll()
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.