Develop multi-tasks projects on Energia

This section requires a compatible board running on Energia MT.

Because the underlying framework of Energia MT or Energia Multi-Tasking is TI-RTOS, a real time operating system from Texas Instruments, projects with multiple tasks are possible.

As a consequence, the project has multiple .ino files. This is the only case a project can have multiple .ino files.

By default, the project has one task on the default .ino file, with a setup() function and a loop() function.

Each new task brings its own setup() and loop() functions with the name of the task.

For an introduction to RTOS,

Add a task

Adding a new task can be done in two ways.

Create a new task on a specific sketch

The recommended solution creates a specific .ino sketch file for the new task.

To create a specific .ino file for the new task.

  • Call the menu File > New > New File... or press Cmd+N.

  • Select the macOS option.

  • Scroll down to the embedXcode or embedXcode+ group.

  • Select Task Energia MT.

The Task Energia MT files defines a new task with the setup() and loop() functions.

  • Give a name to the task, TaskCode is proposed by default.

The new task contains two functions, setup_TaskCode() and loop_TaskCode(), based on the name of the task TaskCode.ino.

// Setup
void setup_TaskCode()
{
    ;
}

// Loop
void loop_TaskCode()
{
    ;
}

Add functions to main sketch

An alternative solution simply adds the functions of the new task to the default main .ino sketch file.

To add a task to the default main .ino file, for example task2,

  • Define two new functions setupTask2() and loopTask2() on the existing main sketch.
void setupTask2()
{

}

void loopTask2()
{

}

Check new task functions names

Here are the requirements for naming the setup() and loop() functions of the new task.

  • Give a different name to each task.

  • Define a setup() function and a loop() function for each task.

  • Include setup in the name of the setup() function of a task.

void TaskCode_setup()
void setup_TaskCode()
void setupTaskCode()
  • Include loop in the name of the loop() function of a task.
void TaskCode_loop()
void loopTaskCode()
void loop_TaskCode()

Warning

The latest release of Energia requires setup and loop to be mentioned as prefixes in the names of the functions, when embedXcode allows any combinations.

  • Check the setup() and loop() functions share the same name inside the task, here TaskCode.
void setup_TaskCode()
void loop_TaskCode()
  • Check each setup() function and each loop() function has a unique name across the whole project.

For more information about Energia MT,

For more information on TI-RTOS,

Check the tasks file

During compilation and linking, embedXcode parses the different .ino files, selects the setup() and loop() functions, and generates the rtosTasks.h file automatically.

This file describes the different tasks. It includes calls to each .ino sketch files, except the default main .ino sketch file of the project, declares the tasks with their setup() and loop() functions, and lists the names of the tasks.

There is no #include for the default embed1.ino file of the embed1 project, because the main.cpp file already mentions it. If one function is missing, an error is raised. 

==== Check project embed1 ====
ERROR   Different number of setup() and loop()
ERROR   TaskCode.ino: no setup() function

It is a good idea to have a look at it to check that all the tasks are correctly mentioned. Do not edit this file as it is generated automatically at each compilation.

For more information about Energia MT,

Here is an example of a populated rtosTasks.h file.

//
// rtosTasks.h
// Header file
// ----------------------------------
//
// List of tasks for project embed-rtos
//
// File generated by embedXcode_check
// Sat Sep 30 11:11:47 CEST 2017
//
// ----------------------------------
// DO NOT EDIT THIS FILE.
// ----------------------------------
//

// List of sketches to #include
//
#include "TaskCode.ino";
// embed_rtos.ino already #included in main.cpp

// List of setup() and loop() functions 
//
extern void setup_TaskCode();
extern void loop_TaskCode();
extern void setup();
extern void loop();

// Number of tasks
//
#define NUM_SKETCHES 2

// List of pointers to setup() and loop()
//
void (*func_ptr[NUM_SKETCHES][2])(void) = {
 { setup_TaskCode, loop_TaskCode },
 { setup, loop },
};

// Names of the tasks
//
const char *taskNames[] = {
 "loop_TaskCode",
 "loop",
};

Add global variables and main setup function

An optional file rtosGlobals.h contains global variables and a optional main setup function setupRtos().

This main setup function setupRtos() runs before all other setup() functions of the tasks.

// Add optional setupRTOS function
void setupRtos()
{
    ;
}

This is especially useful for initialising shared resources like Serial, I²C and SPI ports, and shared RTOS elements like clock, mailbox, semaphore.

All tasks in the .ino files need to include rtosGlobals.h.

// Include application, user and local libraries
#include "rtosGlobals.h"

Warning

This feature is specific to embedXcode and is not supported by the Energia IDE.