Updated Readme.md

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.