Event Scheduling#

These macros implement an event abstraction that allows the application to schedule code to run after some specified time interval. An event consists of a procedure to be called at some point in the future and a control object that determines when the procedure should be called. Events are also useful for when an ISR needs to initiate an action that should run outside of ISR context.

See event.h for source code.

Note that while not required, it is recommended that the event-handling procedure explicitly defines the recurrence of the next event, either by rescheduling it via some kind of emberEventControlSetDelayXX() call or by deactivating it via a call to emberEventControlSetInactive(). In cases where 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. Each tick is approximately equal to a millisecond, but the true duration depends on the platform. The duration of a tick is 1000 / ::MILLISECOND_TICKS_PER_SECOND, where 1000 is the number of milliseconds per second and ::MILLISECOND_TICKS_PER_SECOND is the platform-specific number of ticks per second. For example, ::MILLISECOND_TICKS_PER_SECOND on the EM357 SoC is 1024, so each tick is therefore 1000 / 1024 = ~0.98 milliseconds. Calling emberEventControlSetDelayMS(someEvent, 100) on the EM357 SoC will schedule the event for 100 ticks * (1000 milliseconds / 1024 ticks) = ~97.7 milliseconds. Note however that the accuracy of the base tick depends on the timer source. Further, 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. Calling emberEventControlSetDelayMinutes(someEvent, 3) on the EM357 SoC will schedule the event for 3 minutes * (65536 ticks / minute) * (1000 milliseconds / 1024 ticks) = ~3.2 minutes. It is possible to avoid these binary units by using emberEventControlSetDelayMS and the various MILLISECOND_TICKS_PER_XXX multipliers. For example, calling emberEventControlSetDelayMS(someEvent, 3 * MILLISECOND_TICKS_PER_MINUTE) will delay for 3 minutes on any platform. Be aware of EMBER_MAX_EVENT_CONTROL_DELAY_MS when using this approach.

Following are some 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 we need to do something 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 to run in
⁄⁄ this order.
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);
  }
}