TACOS

This is the Trajectory Analysis Control OS (TACOS) that serves as a framework for flight computer development. TACOS offers a state machine, a CAN bus interface, a watchdog and other HAL features through it's submodules. It runs on cmsis-rtos2 FreeRTOS on STM32 microcontrollers with C++ (maybe future versions will offer external C interfaces to support a wide array of languages...).

To use TACOS one should implement threads, which fulfill the various roles of the module in the App directory. TACOS utilizes ALPAKA features, in particular requiring sta-core and rtos2-utils, as such it requires these to be in it's include path.

Setting up a TACOS Project

Setting up the Project

First one must create a new CubeIDE project with FreeRTOS. To avoid doing that however we recommend using the ioc-collection to get a preconfigured IOC for the STM microcontroller you are using. From here follow the following steps:

1. Import -> General -> Import an Existing STM32CubeMX Configuration File (.ioc)
2. Select the .ioc file from the ioc-collection
3. Enter the project name and location you want to save the project to
4. Select C++ as the target language
5. Click "Finish"

Setting up the Folder Structure

Now it is necessary to setup the dependencies and include paths for TACOS. For this first create a new folder in the project directory called Libs. Then create another folder in the project directory called App with the subfolders Inc and Src. Now also create a folder called sta in the Inc folder. Finally add the empty files App/Inc/sta/config.hpp and App/Src/startup.cpp.

Now your project should look like this:

...
App/
├── Inc/
│   ├── sta/
│   │   └── config.hpp
├── Src/
│   └── startup.cpp
Libs/
...

Setting up the Dependencies

First it is recommended to initialize a git repository in the project folder with git init. Then add the TACOS, sta-core and rtos2-utils repositories as submodules in the Libs folder with the following commands:

cd Libs
git submodule add https://git.intern.spaceteamaachen.de/ALPAKA/TACOS.git
git submodule add https://git.intern.spaceteamaachen.de/ALPAKA/sta-core.git
git submodule add https://git.intern.spaceteamaachen.de/ALPAKA/rtos2-utils.git

Make sure that you add the include paths for TACOS, sta-core and rtos2-utils to the project with the following steps:

1. Right click your project in the Project Explorer and select Properties -> C/C++ General -> Paths and Symbols -> Includes -> GNU C -> Add...
2. Select Add to all languages and Is a workspace path
3. Click on Workspace and select a folder from the YOUR_PROJECT_FOLDER/(Libs|App) directory
   • Always select the include or Inc folder for the include paths
   • If the path you want to add is not in the list, refresh the project with F5 in the Project Explorer and try again
4. Repeat for TACOS, sta-core, rtos2-utils and the App folder
5. Right click your project in the Project Explorer and select Properties -> C/C++ General -> Paths and Symbols -> Source Location -> Add Folder...
   • Add the App and Libs folders

Note

You often want to add more submodules during development. Here, a faster way to add the include path for a library is to right click the library's include folder in the Project Explorer and select Add/remove include path.

Starting TACOS

Navigate to the Core/Src/freertos.c file and add the following code to the StartDefaultTask function:

void StartDefaultTask(void *argument)
{
  /* USER CODE BEGIN StartDefaultTask */
	extern void startTACOS(void *);
	startTACOS(argument);

  /* Infinite loop */
  for(;;)
  {
    osDelay(1);
  }
  /* USER CODE END StartDefaultTask */
}

This will start the TACOS startup and initialize all TACOS threads (which will then initialize yours).

Configuring TACOS

In order to use TACOS, you need to provide a configuration file in the path sta/config.hpp. The following code is an example for a TACOS-project using default configuration:

#ifndef INC_STA_CONFIG_HPP_
#define INC_STA_CONFIG_HPP_

// Use the STM32F407 microprocessor.
#include <sta/devices/stm32/mcu/STM32F407xx.hpp>

// Enable debug serial output and assertions.
#define STA_ASSERT_ENABLED
#define STA_DEBUGGING_ENABLED

// Enable Features

// Statemachine settings. How many states does your statemachine have?
#define STA_TACOS_NUM_STATES 3

// Uses the default configuration for TACOS.
#include<sta/tacos/configs/default.hpp>

#endif /* INC_STA_CONFIG_HPP_ */

Warning

If you want to use debug printing (enabled using the macro STA_DEBUGGING_ENABLED) in a TACOS project, you should also enable float formatting under Project Settings -> C/C++ Build -> MPU/MCU Settings -> Use float with printf from newlib-nano. This allows you to format print floats using STA_DEBUG_PRINTF. If this setting is not enabled, your software will crash when debug printing floats.

The configuration file shown in the example above initializes the project assuming that you are working on a STM32 Nucleo of type F407. Typically, you are using a different microcontroller, however. In this case you can replace the line

#include <sta/devices/stm32/mcu/STM32F407xx.hpp>

with the include

#include <sta/devices/stm32/mcu/STM32_YOUR_MCU_HERE.hpp>

So far, only a few chips are officially supported. For not officially supported chips use this as the include:

#define STA_STM32_SWD_USART_IDX <IDX OF YOUR UART>

#include <sta/devices/stm32/mcu/common.hpp>
#define STA_MCU_LITTLE_ENDIAN
#define STA_PLATFORM_STM32

Note

The definition of STA_STM32_SWD_USART_IDX allows you to specify which UART handle to use for debug printing. If undefined, a default handle for Nucleos will be used. You can also add the macro STA_STM32_ASEAG instead if you are a cool kid using ASEAG-based hardware 😎.

Warning

The definition of STA_STM32_SWD_USART_IDX has to be placed before the include cpp #include <sta/devices/stm32/mcu/STM32_YOUR_MCU_HERE.hpp>

Warning

Make sure you actually enable the UART bus in the under Pinout & Configuration -> Connectivity in the IOC.

Implementing Your Own Threads

Let's create a simple thread that prints "Hello World" every second. First create a new file in the App/Inc/tasks folder called spam_task.hpp. Then add the following code:

#ifndef INC_TASKS_SPAM_TASK_HPP_
#define INC_TASKS_SPAM_TASK_HPP_

#include <sta/tacos.hpp>

namespace tasks
{
	class SpamTask : public sta::tacos::TacosThread {
	public:
		SpamTask();

    // One time function that is called when the thread is created.
		void init() override;

    // Repeatable function that is called every time the thread is executed.
		void func() override;
	};
} // namespace tasks

#endif /* INC_TASKS_SPAM_TASK_HPP_ */

This code defines a new thread that inherits from TacosThread and implements the init and func functions. The init function is called once when the thread is created and the func function is called every time the thread is executed.

Now create a new file in the App/Src/tasks folder called spam_task.cpp and add the following code:

#include <tasks/spam_task.hpp>
#include <sta/debug/debug.hpp>

namespace tasks {
  SpamTask::SpamTask() :
    TacosThread("SPAM", osPriorityNormal){}

  void SpamTask::init() {
    // Nothing to init...
  }

  void SpamTask::func() {
    // Print "Hello World" every second.
    STA_DEBUG_PRINTLN("Hello World");
    this->periodicDelay(1); // Execute this function with 1 Hz.
  }
} // namespace tasks

Warning

A thread's priority must be strictly lower than the statemachine's priority. Unless manually changed, this is always osPriorityHigh.

To start this thread, we first need to fill out the startup.cpp file. This file may look like this:

#include <sta/tacos.hpp>
#include <tasks/spam_task.hpp>

#include <sta/debug/debug.hpp>

namespace sta
{
	namespace tacos
	{
		void startup()
		{
			// ###### Register different threads for different states here. ######
      		// Register a "Spam Task" thread for all states except 1 and 2.
      		sta::tacos::addThread<tasks::SpamTask>(ALL_STATES - state_set{1,2});

			STA_DEBUG_PRINTF("The answer to everything is %d", 42);
		}
	} // namespace tacos
} // namespace sta

The function startup() is a weakly implemented function that is executed right before TACOS initializes its statemachine task. It serves as an entry point for the user to initialize all busses, threads and rtos2-utils stuff that is needed for the application to fulfill its purpose.

And that's it! Now you have a thread that prints "Hello World" every second. Simply build the project and flash it to your microcontroller and be amazed by the Spam!

[Optional] Setting up the CAN Bus

To enable the CAN Bus two things need to be done:

1. Enable CAN in the IOC with the RX0 and RX1 Interrupts enabled.
2. Add the following code to the sta/config.hpp file:

#define STA_TACOS_CAN_BUS_ENABLE

PS: For not officially supported chips add this:

#define STA_STM32_CAN_HANDLE {YOUR_HCAN_HANDLE}

There are two options for handling incoming CAN messages:

1. If #define STA_CAN_BUS_FWD_ENABLE is set, the messages will be forwarded to the task with the ID of the message.

• Tasks set their ID with setID(uint32_t id) in their constructor.
• From here they can handle the message by going through their CAN_queue_ with CanSysMsg msg; CAN_queue_.get(&msg);

2. All messages will trigger the weakly defined handleSysMessage callback.

• This could be implemented like this:

namespace sta
{
	namespace tacos
	{
		bool handleSysMessage(CanMsgHeader &header, uint8_t *payload)
		{
      // Print the message ID and the first byte of the payload. 
      //(please don't do this in production, it will crash the system sooner or later)
			STA_DEBUG_PRINTF("> ID: %d", header.sid);

			switch (header.sid)
			{
			// State transition message
			case STA_TACOS_CAN_BUS_SYS_MSG_ID:
				// First byte of payload is the origin state, second byte is the destination state
				tacos::setState(payload[0], payload[1], 0, true);
				return true;

		  case MODULE_SW_RESET_CAN_ID:
        HAL_NVIC_SystemReset();

        return true; // :)

      // ...

		  default:
				return false;
			}

			return false; // I know, i know, this is not necessary, but it's good practice. And you know what they say about good practice: Do it!
		}
	}
}

TACOS Usage Guide

Almost all of the important aspects of working with TACOS have already been discussed when setting up the project itself. The following sections will give you an in-depth explanation of how to use the statemachine, inter-thread communication and the CAN-Bus.

Using the Statemachine

The statemachine forms the heart and soul of a TACOS-based project. Upon initialization, TACOS starts a statemachine that manages the system state and the currently active threads. As seen before, whenever we pass a new thread to TACOS we also have to provide all states in which the thread should run. After each state transition from state x to state y the statemachine task performs two actions:

1. All threads that should run in state y but are not currently running are started.
2. All threads that should not run in state y but are currently running are stopped.

Important

The statemachine does not immediately stop a thread and deletes it from memory. Instead, the thread is allowed to finish the current execution of its func before entering a blocked state. This allows the thread to release all its resources.

In order to fully understand the statemachine, we have to take a look at the lockout and failsafe timer. These lockout and failsafe timers are the result of design choices made during early stages of STAHR. The goal was to combine the state estimation (i.e. sensor fusion using a Kalman filter) with timer-based safety mechanisms. For example, our goal was to block any state transition to the state DROGUE before 60 seconds after liftoff. Additionally, a timer was started to automatically switch to state DROGUE after 120 seconds after liftoff.

These safety mechanisms resulted in the implementation of the lockout and failsafe timer in TACOS:

1. Lockout Timer: The lockout timer can be started after a state transition. As long as it is running, all state transitions are blocked by the statemachines, unless the user actively chooses to bypass the safety mechanism using forceState().
2. Failsafe Timer The failsafe timer can be used to schedule a state transition after a certain period of time has elapsed. This transition will be blocked if the lockout timer is running at that time. The failsafe timer obeys the following rules:
   • A timed state transition can be requested even when the lockout timer is active. It only matters if the lockout timer is running at the end of the time span of the lockout timer.
   • If a state transition is triggered before the end of the time span, the failsafe timer is stopped.

A state transition can be triggered by calling the functions requestState(), forceState() or setStateTimed() that are provided in sta/tacos.hpp. Take a look at include/sta/README.md for more details on the functions. Additionally, state transitions can be triggered remotely using the CAN-Bus, however, this is discussed in more detail in the section on the CAN Bus.

Example Usage

Generally, the state transitions are requested in the startup() function or in TacosThread instances implemented by the user. It is good practise to give your states names by defining an enum in a header file states.hpp that can be included everywhere in your project.

#ifndef MY_PROJECT_STATES_HPP
#define MY_PROJECT_STATES_HPP

namespace my_project
{
	enum class States : uint16_t
	{
		STARTUP			= 0,
		PING			= 1,
		PONG			= 2
	};
}

#endif // MY_PROJECT_STATES_HPP

This gives us three states: STARTUP, PING and PONG. Generally, these names have no meaning for TACOS but they make your software more readable. Next, we define two modified tasks based on SpamTask for our project:

#include <tasks/ping_task.hpp>
#include <tasks/pong_task.hpp>
#include <path/to/states.hpp>

namespace tasks {
  PingTask::PingTask() :
    TacosThread("PING", osPriorityNormal){}

  void PingTask::func() {
	sleep(100);

    STA_DEBUG_PRINTLN("PING");

	sta::tacos::requestState(my_project::PING, my_project::PONG);
  }

  PongTask::PongTask() :
    TacosThread("PONG", osPriorityNormal){}

  void PongTask::func() {
	sleep(100);

    STA_DEBUG_PRINTLN("PONG");

	sta::tacos::requestState(my_project::PONG, my_project::PING);
  }
} // namespace tasks

Important

Generally, you want both tasks to be implemented in separate .cpp files.

Using these two threads we can implement our startup() function:

#include <sta/tacos.hpp>
#include <tasks/spam_task.hpp>
#include <path/to/states.hpp>

#include <sta/debug/debug.hpp>

namespace sta
{
	namespace tacos
	{
		void startup()
		{
      		// Register a "PingTask" thread for the state PING.
      		sta::tacos::addThread<tasks::PingTask>({my_project::PING});
			sta::tacos::addThread<tasks::PongTask>({my_project::PONG});

			// Start with the spam after one second.
			sta::tacos::setStateTimed(my_project::STARTUP, my_project::PING, 1000);
		}
	} // namespace tacos
} // namespace sta

The resulting program switches between the states PING and PONG and alternately outputs "PING" and "PONG" via UART. While this is just a toy example, building more complicated applications is not much harder!

Using Inter-Thread Communication

Important

Coming soon!

Further information

To look into other function of TACOS please consult the READMEs in the include folder or the doxygen documentation. Also consult the sta-core and rtos2-utils READMEs for further information on the features that TACOS uses.