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

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.
Back to top