diff --git a/README.md b/README.md index 9270b23..c624a7b 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ This is the Trajectory Analysis Control OS (TACOS) that serves as a framework fo To use TACOS one should implement threads, which fulfill the various roles of the module in the App directory. TACOS utilizes [ALPAKA](https://git.intern.spaceteamaachen.de/ALPAKA) features, in particular requiring [sta-core](https://git.intern.spaceteamaachen.de/ALPAKA/sta-core) and [rtos2-utils](https://git.intern.spaceteamaachen.de/ALPAKA/rtos2-utils), as such it requires these to be in it's include path. -## Setting up a TACOS project +## Setting up a TACOS Project -### Setting up the 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](https://git.intern.spaceteamaachen.de/ALPAKA/ioc-collection) to get a preconfigured IOC for the STM microcontroller you are using. From here follow the following steps: @@ -17,7 +17,7 @@ First one must create a new CubeIDE project with FreeRTOS. To avoid doing that h 5. Click "Finish" -### Setting up the folder structure +### 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`. @@ -34,7 +34,7 @@ Libs/ ... ``` -### Setting up the dependencies +### 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: ```bash @@ -113,7 +113,7 @@ PS: For not officially supported chips use this as the include: #define STA_PLATFORM_STM32 ``` -### Implementing your own threads +### 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: ```cpp @@ -190,7 +190,7 @@ The function `startup()` is a weakly implemented function that is executed right 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 +### \[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. @@ -245,5 +245,19 @@ namespace sta } ``` +## 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, CAN-Bus and inter-thread communication. + +### 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 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. + +A state transition can be triggered by calling the functions `requestState()`, `forceState()` or `setStateTimed()` that are provided in `sta/tacos.hpp`. Additionally, state transitions can be triggered remotely using the CAN-Bus. This is discussed in more detail in the section discussing the CAN Bus. + ### 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. \ No newline at end of file