Events with Energia MT and Galaxia Library

Energia IDE and Galaxia Library

The Arduino-compatible IDE or integrated development environment is called Energia. However, Energia comes with a major new release for this board: Energia MT.

Energia MT stands for Energia Multi-Tasking and is based on Texas Instruments RTOS, aka. Real Time Operating System. Real-time means each task is completed within a determined period of time, and RTOS is an operating system built on it.

Energia MT runs on selected boards, LaunchPad MSP432, LaunchPad CC3200 WiFi and SensorTag CC2650.

I've developed libraries which encapsulate the RTOS elements into classes with a consistent and minimal set of functions. The goal is to provide libraries with the same ease of use as the standard classes (e.g. SPI, I²C, Serial) provided by the Wiring / Arduino framework. All the libraries are bundled in one single package called Galaxia, included in the Energia distribution.

How Events Work

An event is like a message. Multiple senders can send the message but only one subscriber can wait for and receive it.

An event is declared with 

 
#include "Event.h"
Event myEvent1;

and initialised by

   myEvent1.begin();

To send an event, use 

   myEvent1.send();
   myEvent1.send(Event_Id_01);

By default, Event_Id_00 is sent.

To wait for an event, use

   uint32_t events = myEvent1.waitFor();
   uint32_t events = myEvent1.waitFor(Event_Id_01);

By default, Event_Id_00 is waited for.

An event can manage different conditions, with OR or AND.

The syntax for waitFor() is

uint32_t waitFor(xdc_UInt andMask = Event_Id_00, 
                xdc_UInt orMask  = Event_Id_NONE);

with

• andMask AND condition, default = Event_Id_00

// AND
uint32_t events = myEvent2.waitFor(Event_Id_02 + Event_Id_03, Event_Id_NONE);

The Event2 event waits for both Event_Id_02 AND Event_Id_03, listed with an addition.

• orMask OR condition, default = Event_Id_NONE

// OR
uint32_t events = myEvent2.waitFor(Event_Id_NONE, Event_Id_02 + Event_Id_03);

The Event2 event waits for any of Event_Id_02 OR Event_Id_03, listed with an addition.

In the example provided, there are 2 events, myEvent1 and myEvent2.

• For the simple myEvent1, the message is sent by Galaxia_Event.ino every 2 seconds and received by LED1.ino.

• For the event with conditions myEvent2, messages are sent by Event2.ino every 5 seconds and Event3.ino every 3 seconds and received by LED23.ino.

The example uses a semaphore to manage the serial console. For an introduction to semaphore, please refer to Manage Single Resource with Energia MT and Galaxia.

Remember:

Only a single Task can wait for a given Event object at a time.

Simple Event

The event Event1 with Event_Id_01 is sent by Event1.ino every 2 seconds.

   myEvent1.send(Event_Id_01);
   delay(2000);

On the loop() function of the LED1.ino sketch, the message with Event_Id_01 is waited for and received by

   uint32_t events = myEvent1.waitFor(Event_Id_01);

The result is:

1       : myEvent1 1   (0100)
4       : myEvent1 *   (0100) red   ON
2004    : myEvent1 1   (0100)
2005    : myEvent1 *   (0100) red   OFF
4005    : myEvent1 1   (0100)
4006    : myEvent1 *   (0100) red   ON
6006    : myEvent1 1   (0100)
6007    : myEvent1 *   (0100) red   OFF
8007    : myEvent1 1   (0100)
8008    : myEvent1 *   (0100) red   ON
10008   : myEvent1 1   (0100)
10009   : myEvent1 *   (0100) red   OFF
12009   : myEvent1 1   (0100)
12010   : myEvent1 *   (0100) red   ON
14010   : myEvent1 1   (0100)
14011   : myEvent1 *   (0100) red   OFF

The green LED state is changed each time Event1 with Event_Id_01 is sent.

AND Condition for Events 

Events can carry conditions, and wait for all the conditions to be met (AND condition) , or wait for any of a list of conditions is sent (OR condition).

On the loop() function of the LED23.ino sketch, uncomment

uint32_t events = myEvent2.waitFor(Event_Id_02 + Event_Id_03, Event_Id_NONE);

Condition Event_Id_02 of Event2 is sent by Event2.ino every 5 seconds.

   myEvent2.send(Event_Id_02);
   delay(5000);

Condition Event_Id_03 of Event2 is sent by Event3.ino every 3 seconds.

   myEvent2.send(Event_Id_03);
   delay(3000);

The result is:

1       : myEvent1 1   (0100)
4       : myEvent1 *   (0100) red   ON
10      : myEvent2  2  (0010)
30      : myEvent2   3 (0001)
31      : myEvent2  ** (0011) green ON
2004    : myEvent1 1   (0100)
2005    : myEvent1 *   (0100) red   OFF
3031    : myEvent2   3 (0001)
4005    : myEvent1 1   (0100)
4006    : myEvent1 *   (0100) red   ON
5011    : myEvent2  2  (0010)
5012    : myEvent2  ** (0011) green OFF
6006    : myEvent1 1   (0100)
6007    : myEvent1 *   (0100) red   OFF
6032    : myEvent2   3 (0001)
8007    : myEvent1 1   (0100)
8008    : myEvent1 *   (0100) red   ON
9033    : myEvent2   3 (0001)
10008   : myEvent1 1   (0100)
10009   : myEvent1 *   (0100) red   OFF
10013   : myEvent2  2  (0010)
10015   : myEvent2  ** (0011) green ON
12009   : myEvent1 1   (0100)
12010   : myEvent1 *   (0100) red   ON
12034   : myEvent2   3 (0001)
14010   : myEvent1 1   (0100)
14011   : myEvent1 *   (0100) red   OFF
15015   : myEvent2  2  (0010)
15016   : myEvent2  ** (0011) green OFF
15035   : myEvent2   3 (0001)

The green LED state is changed when both Event_Id_02 and Event_Id_03 are sent.

OR Condition for Events

On the loop() function of the LED23.ino sketch, uncomment

uint32_t events = myEvent2.waitFor(Event_Id_NONE, Event_Id_02 + Event_Id_03);

As before, condition Event_Id_02 is sent by Event2.ino every 5 seconds and condition Event_Id_03 of Event2 is sent by Event3.ino. every 3 seconds.

The result is:

1       : myEvent1 1   (0100)
4       : myEvent1 *   (0100) red   ON
10      : myEvent2  2  (0010)
11      : myEvent2  ** (0010) green ON
30      : myEvent2   3 (0001)
31      : myEvent2  ** (0001) green OFF
2004    : myEvent1 1   (0100)
2005    : myEvent1 *   (0100) red   OFF
3031    : myEvent2   3 (0001)
3032    : myEvent2  ** (0001) green ON
4005    : myEvent1 1   (0100)
4006    : myEvent1 *   (0100) red   ON
5011    : myEvent2  2  (0010)
5012    : myEvent2  ** (0010) green OFF
6006    : myEvent1 1   (0100)
6007    : myEvent1 *   (0100) red   OFF
6032    : myEvent2   3 (0001)
6033    : myEvent2  ** (0001) green ON
8007    : myEvent1 1   (0100)
8008    : myEvent1 *   (0100) red   ON
9033    : myEvent2   3 (0001)
9034    : myEvent2  ** (0001) green OFF
10008   : myEvent1 1   (0100)
10009   : myEvent1 *   (0100) red   OFF
10013   : myEvent2  2  (0010)
10015   : myEvent2  ** (0010) green ON
12009   : myEvent1 1   (0100)
12010   : myEvent1 *   (0100) red   ON
12034   : myEvent2   3 (0001)
12035   : myEvent2  ** (0001) green OFF
14010   : myEvent1 1   (0100)
14011   : myEvent1 *   (0100) red   OFF
15015   : myEvent2  2  (0010)
15016   : myEvent2  ** (0010) green ON
15035   : myEvent2   3 (0001)
15036   : myEvent2  ** (0001) green OFF
 

The green LED state is changed when either Event_Id_02 or Event_Id_03 is sent first.

Conclusion

The events offer an elegant solution to send messages with conditions to trigger actions. When the program is waiting for an event, it enters low power mode.

Remember:

Only a single Task can wait for a given Event object at a time.