TACOS/README.md

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

// Statemachine settings.
#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!

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!
		}
	}
}

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.