From 36c160e8e351c69db3377cd656b3224b844071f9 Mon Sep 17 00:00:00 2001 From: dario Date: Sun, 1 Dec 2024 15:11:42 +0100 Subject: [PATCH] Updated statemachine documentation to reference existing documentation --- README.md | 21 +++------------------ include/sta/README.md | 9 ++++++--- 2 files changed, 9 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index e75b21f..29c757b 100644 --- a/README.md +++ b/README.md @@ -260,27 +260,12 @@ The statemachine forms the heart and soul of a TACOS-based project. Upon initial 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. 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. The failsafe timer can be used to request a state transition after a certain period of time has elapsed. This transition will be blocked if the lockout time is running at that time. The failsafe timer obeys the following rules: +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`. 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. - -#### `requestState(uint32_t from, uint32_t to, uint32_t lockout = 0, bool publish = true)` - -Requests a state transition from state `from` to the state `to`. Will be blocked if `from` is not the current state or if the lockout time is running. Optinally, use the `lockout` parameter to also start the lockout timer if the state transition is successful. The argument `publish` tells the TACOS to also publish the state on via the CAN bus - -#### `forceState(uint32_t from, uint32_t to, uint32_t lockout = 0, bool publish = true)` - -Forces a state transition from state `from` to the state `to`, bypassing the lockout timer. However, in order to protect the integrity of the statemachine, `from` has to match the current state. Similar to `requestState()`, an optional lockout timer can be set and the state can be published via CAN. - -#### `setStateTimed(uint32_t from, uint32_t to, uint32_t millis, uint32_t lockout = 0, bool publish = false)` - -Schedules a state transition from state `from` to state `to` in `millis` milliseconds. Additionally, a lockout timer of `lockout` milliseconds can be set which will become active _after_ successful state transition from `from` to `to`. Similarly, setting `publish` to `true` will result in a successful state transition being broadcast on the CAN bus. - -> [!IMPORTANT] -> If the failsafe timer is already running with a different state transition, calling `setStateTimed` will overwrite this request. +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 diff --git a/include/sta/README.md b/include/sta/README.md index b39d0bc..31632bd 100644 --- a/include/sta/README.md +++ b/include/sta/README.md @@ -15,7 +15,7 @@ Retrieves the current state of the TACOS state machine. void requestState(uint32_t from, uint32_t to, uint32_t lockout = 0, bool publish = true) ``` -Requests a state transition. Invalid state transitions will be dismissed. First come, first serve. +Requests a state transition. Invalid state transitions will be dismissed. First come, first serve. Can be blocked by the lockout timer. - **Parameters**: - `from`: The starting state for the transition. @@ -27,7 +27,7 @@ Requests a state transition. Invalid state transitions will be dismissed. First void forceState(uint32_t from, uint32_t to, uint32_t lockout = 0, bool publish = true) ``` -Forces a state transition. Will be ignored if already in the given state. Triggers instantly. +Forces a state transition. Will be ignored if already in the given state. Triggers instantly. Ignores the lockout timer. - **Parameters**: - `from`: The starting state for the transition. @@ -41,7 +41,7 @@ Forces a state transition. Will be ignored if already in the given state. Trigge void setStateTimed(uint32_t from, uint32_t to, uint32_t millis, uint32_t lockout = 0, bool publish = false) ``` -Requests a state transition after a specified time. +Requests a state transition after a specified time. Equivalent to calling `requestState` after a specified time. - **Parameters**: - `from`: The starting state. @@ -49,6 +49,9 @@ Requests a state transition after a specified time. - `millis`: The wait time in milliseconds before requesting the transition. - `lockout`: (Optional) A timer for blocking subsequent transitions. +> [!IMPORTANT] +> If there is already a timed transition scheduled, calling `setStateTimed` will overwrite this request. + --- ```cpp