Merge branch 'update/readme' into feat/documentation

README.md

@@ -8,7 +8,7 @@ To use TACOS one should implement threads, which fulfill the various roles of th
 
 ### 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:
+First one must create a new CubeIDE project with FreeRTOS. To avoid doing that however we recommend using the [ioc-collection](https://git.spaceteamaachen.de/ALPAKA/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
@@ -84,14 +84,9 @@ In order to use TACOS, you need to provide a configuration file in the path `sta
 #ifndef INC_STA_CONFIG_HPP_
 #define INC_STA_CONFIG_HPP_
 
-// Using a board with an ASEAG module present.
-#define STA_STM32_ASEAG
 // Use the STM32F407 microprocessor.
 #include <sta/devices/stm32/mcu/STM32F407xx.hpp>
 
-// Doesn't really do too much right now. Has to be added for successful compilation.
-#define STA_PRINTF_USE_STDLIB
-
 // Enable debug serial output and assertions.
 #define STA_ASSERT_ENABLED
 #define STA_DEBUGGING_ENABLED
@@ -106,12 +101,34 @@ In order to use TACOS, you need to provide a configuration file in the path `sta
 
 #endif /* INC_STA_CONFIG_HPP_ */
 ```
-PS: For not officially supported chips use this as the include:
+
+> [!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
 ```cpp
+#include <sta/devices/stm32/mcu/STM32F407xx.hpp>
+```
+with the include
+```cpp
+#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:
+```cpp
+#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
 
@@ -143,6 +160,7 @@ This code defines a new thread that inherits from `TacosThread` and implements t
 Now create a new file in the `App/Src/tasks` folder called `spam_task.cpp` and add the following code:
 ```cpp
 #include <tasks/spam_task.hpp>
+#include <sta/debug/debug.hpp>
 
 namespace tasks {
   SpamTask::SpamTask() :