Event Scheduling#
Scheduling events for future execution.
See Event Scheduling for documentation. These macros implement an event abstraction that allows the application to schedule code to run after a specified time interval. An event consists of a procedure to be called at some point in the future and a control object that determines which procedure should be called. Events are also useful when an ISR needs to initiate an action that should run outside the ISR context.
See event.h for source code.
Note that, while not required, it is recommended that the event-handling procedure explicitly define the recurrence of the next event, either by rescheduling via some kind of emberEventControlSetDelayXX() call or by deactivating via a call to emberEventControlSetInactive().
When the handler does not explicitly reschedule or cancel the event, the default behavior of the event control system is to keep the event immediately active as if the handler function had called emberEventControlSetActive(someEvent) or emberEventControlSetDelayMS(someEvent, 0).
The base time units for events are ticks. A tick equals 1 ms on every platform supported by Connect. Note, however, that the accuracy of the base tick depends on the timer source, which by default is the LF RC oscillator on EFR32 platforms.
Furthermore, the scheduled delay is the minimum delay. If emberRunEvents() or emberRunTask() are not called frequently enough, the actual delay may be longer than the scheduled delay.
Additionally, the APIs for quarter second and minute delays (emberEventControlSetDelayQS() and emberEventControlSetDelayMinutes()) use "binary" units. One quarter second is 256 ticks and one minute is 65536 ticks. These APIs are therefore doesn't actually mean a quarter of second or a minute on platforms supported by Connect.
However, in the future, Connect support might become available on platforms where one tick is not exactly 1 ms. For example, on the EM357 SoC, 1 s is 1024 ticks, so each tick is 1000 / 1024 = ~0.98 milliseconds. If you need platform independent accurate delays, use the macros MILLISECOND_TICKS_PER_SECOND and MILLISECOND_TICKS_PER_MINUTE. For example, calling emberEventControlSetDelayMS(someEvent, 3 * MILLISECOND_TICKS_PER_MINUTE) will delay for 3 minutes on any platform.
The following are brief usage examples.
EmberEventControl delayEvent;
EmberEventControl signalEvent;
EmberEventControl periodicEvent;
void delayEventHandler(void)
{
// Disable this event until its next use.
emberEventControlSetInactive(delayEvent);
}
void signalEventHandler(void)
{
// Disable this event until its next use.
emberEventControlSetInactive(signalEvent);
// Sometimes an action has to occur 100 ms later.
if (somethingIsExpected)
emberEventControlSetDelayMS(delayEvent, 100);
}
void periodicEventHandler(void)
{
emberEventControlSetDelayQS(periodicEvent, 4);
}
void someIsr(void)
{
// Set the signal event to run at the first opportunity.
emberEventControlSetActive(signalEvent);
}
// Put the controls and handlers in an array. They will be run in
// this order (this is usually generated)
EmberEventData events[] =
{
{ &delayEvent, delayEventHandler },
{ &signalEvent, signalEentHandler },
{ &periodicEvent, periodicEventHandler },
{ NULL, NULL } // terminator
};
void main(void)
{
// Cause the periodic event to occur once a second.
emberEventControlSetDelayQS(periodicEvent, 4);
while (true) {
emberRunEvents(events);
}
}
Time Manipulation Macros#
Set EmberEventControl to run at the next available opportunity.
Set EmberEventControl to run some milliseconds in the future.
Check when the event is scheduled to run.
Start an event handler if anything is scheduled when this function is called.
Start an event handler if there is anything scheduled at the moment this function is called.
Check when the next event is scheduled to run.
Check when the next event is scheduled to run.
Check when the next stack event is scheduled to run.
Initialize a task for managing events and processor idling state.
Try to idle the CPU, unless any events in any tasks are pending.
Enable or disable idling.
Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 16 bit values. Result may not be valid if the time samples differ by more than 32767.
Returns the elapsed time between two 32 bit values. Result may not be valid if the time samples differ by more than 2147483647.
Returns true if t1 is greater than t2. Can only account for 1 wrap around of the variable before it is wrong.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns true if t1 is greater than t2. Can only account for 1 wrap around of the variable before it is wrong.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns true if t1 is greater than t2. Can only account for 1 wrap around of the variable before it is wrong.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
The number of event tasks that can be used to schedule and run events. Connect stack requires one, while another is used for Application Framework events.
Set EmberEventControl as inactive (no pending event).
Check whether EmberEventControl is currently active. An event is considered active if it is set to run some time in the future (activated by emberEventControlSetActive(), emberEventControlSetDelayMS() or any other emberEventControlSetDelay* functions)
Set EmberEventControl to run at the next available opportunity.
The maximum delay that may be passed to emberEventControlSetDelayMS().
Set EmberEventControl to run some milliseconds in the future.
The maximum delay that may be passed to emberEventControlSetDelayQS().
Set EmberEventControl to run some quarter seconds in the future.
The maximum delay that may be passed to emberEventControlSetDelayMinutes().
Set EmberEventControl to run some minutes in the future.
Check when the event is scheduled to run.
Enable or disable idling.
Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task.
Macros#
Time Manipulation Macros Documentation#
sli_event_control_set_active#
void sli_event_control_set_active (EmberEventControl * event)
Set EmberEventControl to run at the next available opportunity.
| [in] | event | Pointer to the control of the event to set active |
Warnings
Applications should use emberEventControlSetActive() instead.
299 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemEventControlSetDelayMS#
void emEventControlSetDelayMS (EmberEventControl * event, uint32_t delay)
Set EmberEventControl to run some milliseconds in the future.
| [in] | event | Pointer to the control of the event to run. |
| [in] | delay | The delay in milliseconds. Must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS |
Warnings
Applications should use emberEventControlSetDelayMS() instead.
325 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemEventControlGetRemainingMS#
uint32_t emEventControlGetRemainingMS (EmberEventControl * event)
Check when the event is scheduled to run.
| [in] | event | Pointer to the control of the event in question. |
Returns
Return the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.
Warnings
Applications should use emberEventControlGetRemainingMS() instead.
378 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberRunEvents#
void emberRunEvents (EmberEventData * events)
Start an event handler if anything is scheduled when this function is called.
| [in] | events | Pointer to the array of events. |
An application typically creates an array of events along with their handlers. This function should be called in the main loop to run those events. Warnings
This is normally handled by emberRunTask() in the main plugin.
392 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberRunTask#
void emberRunTask (EmberTaskId taskid)
Start an event handler if there is anything scheduled at the moment this function is called.
| N/A | taskid |
If an application has initialized a task via emberTaskInit(), to run the events associated with that task, it should call emberRunTask() instead of emberRunEvents().
Warnings
This is normally handled by the main plugin.
405 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberMsToNextEvent#
uint32_t emberMsToNextEvent (EmberEventData * events, uint32_t maxMs)
Check when the next event is scheduled to run.
| [in] | events | An array of events to check. |
| [in] | maxMs | If no event is scheduled before maxMs, maxMs will be returned |
Returns
Returns the number of milliseconds before the next event is scheduled to expire, or
maxMsif no event is scheduled to expire within that time.
Note
If any events are modified within an interrupt, to guarantee the accuracy of this API, it must be called with interrupts disabled.
See Also
420 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberMsToNextEventExtended#
uint32_t emberMsToNextEventExtended (EmberEventData * events, uint32_t maxMs, uint8_t * returnIndex)
Check when the next event is scheduled to run.
| [in] | events | An array of events to check. |
| [in] | maxMs | If no event is scheduled before maxMs, maxMs will be returned |
| [out] | returnIndex | If not NULL pointer was passed, the index of the next event will be returned here, or 0xFF if no event is scheduled before maxMs. |
Returns
Returns the number of milliseconds before the next event is scheduled to expire, or
maxMsif no event is scheduled to expire within that time.
Note
If any events are modified within an interrupt, to guarantee the accuracy of this API, it must be called with interrupts disabled.
See Also
438 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberMsToNextStackEvent#
uint32_t emberMsToNextStackEvent (void )
Check when the next stack event is scheduled to run.
| N/A |
Returns
Returns the number of milliseconds before the next stack event is scheduled to run.
446 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberTaskInit#
EmberTaskId emberTaskInit (EmberEventData * events)
Initialize a task for managing events and processor idling state.
| [in] | events | Pointer to the array of events to manage |
Returns
Returns the EmberTaskId which represents the newly created task.
Note
After the task is created emberRunTask() should be called periodically.
456 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberMarkTaskIdle#
bool emberMarkTaskIdle (EmberTaskId taskid)
Try to idle the CPU, unless any events in any tasks are pending.
| [in] | taskid | the task which should handle the idling. |
Returns
Returns true if the processor was idled false if idling wasn't permitted because a task has something to do.
Note
This API should always be called with interrupts disabled. It will forcibly re-enable interrupts before returning.
468 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemTaskEnableIdling#
void emTaskEnableIdling (bool allow)
Enable or disable idling.
| [in] | allow | Setting it to true will enable, while setting it to false will disable idling. |
Warnings
Applications should use emberTaskEnableIdling() instead.
484 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemMarkTaskActive#
void emMarkTaskActive (EmberTaskId taskid)
Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task.
| [in] | taskid | The task to mark active. |
Warnings
Applications should use emberMarkTaskActive() instead.
499 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.helapsedTimeInt8u#
#define elapsedTimeInt8uValue:
(oldTime, newTime)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
190 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.helapsedTimeInt16u#
#define elapsedTimeInt16uValue:
(oldTime, newTime)
Returns the elapsed time between two 16 bit values. Result may not be valid if the time samples differ by more than 32767.
197 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.helapsedTimeInt32u#
#define elapsedTimeInt32uValue:
(oldTime, newTime)
Returns the elapsed time between two 32 bit values. Result may not be valid if the time samples differ by more than 2147483647.
204 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMAX_INT8U_VALUE#
#define MAX_INT8U_VALUEValue:
(0xFF)
Returns true if t1 is greater than t2. Can only account for 1 wrap around of the variable before it is wrong.
211 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hHALF_MAX_INT8U_VALUE#
#define HALF_MAX_INT8U_VALUEValue:
(0x80)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
212 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.htimeGTorEqualInt8u#
#define timeGTorEqualInt8uValue:
(t1, t2)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
213 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMAX_INT16U_VALUE#
#define MAX_INT16U_VALUEValue:
(0xFFFF)
Returns true if t1 is greater than t2. Can only account for 1 wrap around of the variable before it is wrong.
220 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hHALF_MAX_INT16U_VALUE#
#define HALF_MAX_INT16U_VALUEValue:
(0x8000)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
221 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.htimeGTorEqualInt16u#
#define timeGTorEqualInt16uValue:
(t1, t2)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
222 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMAX_INT32U_VALUE#
#define MAX_INT32U_VALUEValue:
(0xFFFFFFFFUL)
Returns true if t1 is greater than t2. Can only account for 1 wrap around of the variable before it is wrong.
229 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hHALF_MAX_INT32U_VALUE#
#define HALF_MAX_INT32U_VALUEValue:
(0x80000000UL)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
230 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.htimeGTorEqualInt32u#
#define timeGTorEqualInt32uValue:
(t1, t2)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
231 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMILLISECOND_TICKS_PER_SECOND#
#define MILLISECOND_TICKS_PER_SECONDValue:
1000UL
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
234 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMILLISECOND_TICKS_PER_DECISECOND#
#define MILLISECOND_TICKS_PER_DECISECONDValue:
(MILLISECOND_TICKS_PER_SECOND / 10)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
237 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMILLISECOND_TICKS_PER_QUARTERSECOND#
#define MILLISECOND_TICKS_PER_QUARTERSECONDValue:
(MILLISECOND_TICKS_PER_SECOND >> 2)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
241 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMILLISECOND_TICKS_PER_MINUTE#
#define MILLISECOND_TICKS_PER_MINUTEValue:
(60UL * MILLISECOND_TICKS_PER_SECOND)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
245 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMILLISECOND_TICKS_PER_HOUR#
#define MILLISECOND_TICKS_PER_HOURValue:
(60UL * MILLISECOND_TICKS_PER_MINUTE)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
249 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hMILLISECOND_TICKS_PER_DAY#
#define MILLISECOND_TICKS_PER_DAYValue:
(24UL * MILLISECOND_TICKS_PER_HOUR)
Returns the elapsed time between two 8 bit values. Result may not be valid if the time samples differ by more than 127.
253 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hEMBER_TASK_COUNT#
#define EMBER_TASK_COUNTValue:
(3)
The number of event tasks that can be used to schedule and run events. Connect stack requires one, while another is used for Application Framework events.
261 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlSetInactive#
#define emberEventControlSetInactiveValue:
(control)
Set EmberEventControl as inactive (no pending event).
268 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlGetActive#
#define emberEventControlGetActiveValue:
(control)
Check whether EmberEventControl is currently active. An event is considered active if it is set to run some time in the future (activated by emberEventControlSetActive(), emberEventControlSetDelayMS() or any other emberEventControlSetDelay* functions)
Returns
Returns true if the event is active false otherwise
282 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlSetActive#
#define emberEventControlSetActiveValue:
(control)
Set EmberEventControl to run at the next available opportunity.
291 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hEMBER_MAX_EVENT_CONTROL_DELAY_MS#
#define EMBER_MAX_EVENT_CONTROL_DELAY_MSValue:
(HALF_MAX_INT32U_VALUE - 1)
The maximum delay that may be passed to emberEventControlSetDelayMS().
305 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlSetDelayMS#
#define emberEventControlSetDelayMSValue:
(control, delay)
Set EmberEventControl to run some milliseconds in the future.
314 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hEMBER_MAX_EVENT_CONTROL_DELAY_QS#
#define EMBER_MAX_EVENT_CONTROL_DELAY_QSValue:
(EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 8)
The maximum delay that may be passed to emberEventControlSetDelayQS().
330 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlSetDelayQS#
#define emberEventControlSetDelayQSValue:
(control, delay)
Set EmberEventControl to run some quarter seconds in the future.
Warnings
Applications should use emberEventControlSetDelayQS() instead.
341 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hEMBER_MAX_EVENT_CONTROL_DELAY_MINUTES#
#define EMBER_MAX_EVENT_CONTROL_DELAY_MINUTESValue:
(EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 16)
The maximum delay that may be passed to emberEventControlSetDelayMinutes().
347 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlSetDelayMinutes#
#define emberEventControlSetDelayMinutesValue:
(control, delay)
Set EmberEventControl to run some minutes in the future.
356 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberEventControlGetRemainingMS#
#define emberEventControlGetRemainingMSValue:
(control)
Check when the event is scheduled to run.
Returns
Returns the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.
366 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberTaskEnableIdling#
#define emberTaskEnableIdlingValue:
(allow)
Enable or disable idling.
477 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.hemberMarkTaskActive#
#define emberMarkTaskActiveValue:
(taskid)
Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task.
492 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/stack/include/event.h