diff --git a/satrs-book/src/actions.md b/satrs-book/src/actions.md index 1f3c921..6ad9c39 100644 --- a/satrs-book/src/actions.md +++ b/satrs-book/src/actions.md @@ -29,7 +29,7 @@ There are 3 requirements for the PUS 8 telecommand: 2. Bytes 0 to 4 of application data must contain the target ID in `u32` big endian format. 3. Bytes 4 to 8 of application data must contain the action ID in `u32` big endian format. 4. The rest of the application data are assumed to be command specific additional parameters. They - will be added to an IPC store, the the corresponding store address will be sent as part of the + will be added to an IPC store and the corresponding store address will be sent as part of the `ActionRequest`. ## Sending back telemetry diff --git a/satrs-book/src/modes-and-health.md b/satrs-book/src/modes-and-health.md index e69de29..4cb6878 100644 --- a/satrs-book/src/modes-and-health.md +++ b/satrs-book/src/modes-and-health.md @@ -0,0 +1,102 @@ +# Modes + +Modes are an extremely useful concept for complex system in general. They also allow simplified +system reasoning for both system operators and OBSW developers. They model the behaviour of a +component and also provide observability of a system. A few examples of how to model +different components of a space system with modes will be given. + +## Modelling a pyhsical devices with modes + +The following simple mode scheme with the following three mode + +- `OFF` +- `ON` +- `NORMAL` + +can be applied to a large number of simpler devices of a remote system, for example sensors. + +1. `OFF` means that a device is physically switched off, and the corresponding software component +does not poll the device regularly. +2. `ON` means that a device is pyhsically switched on, but the device is not polled perically. +3. `NORMAL` means that a device is powered on and polled periodically. + +If a devices is `OFF`, the device handler will deny commands which include physical communication +with the connected devices. In `NORMAL` mode, it will autonomously perform periodic polling +of a connected physical device in addition to handling remote commands by the operator. +Using these three basic modes, there are two important transitions which need to be taken care of +for the majority of devices: + +1. `OFF` to `ON` or `NORMAL`: The device first needs to be powered on. After that, the + device initial startup configuration must be performed. +2. `NORMAL` or `ON` to `OFF`: Any important shutdown configuration or handling must be performed + before powering off the device. + +## Modelling a controller with modes + +Controller components are not modelling physical devices, but a mode scheme is still the best +way to model most of these components. + +For example, a hypothetical attitude controller might have the following modes: + +- `SAFE` +- `TARGET IDLE` +- `TARGET POINTING GROUND` +- `TARGET POINTING NADIR` + +We can also introduce the concept of submodes: The `SAFE` mode can for example have a +`DEFAULT` submode and a `DETUMBLE` submode. + +## Achieving system observability with modes + +If a system component has a mode in some shape or form, this mode should be observable. This means +that the operator can also retrieve the mode for a particular component. This is especially +important if these components can change their mode autonomously. + +If a component is able to change its mode autonomously, this is also something which is relevant +information for the operator or for other software components. This means that a component +should also be able to announce its mode. + +This concept becomes especially important when applying the mode concept on the whole +system level. This will also be explained in detail in a dedicated chapter, but the basic idea +is to model the whole system as a tree where each node has a mode. A new capability is added now: +A component can announce its mode recursively. This means that the component will announce its +own mode first before announcing the mode of all its children. Using a scheme like this, the mode +of the whole system can be retrieved using only one command. The same concept can also be used +for commanding the whole system, which will be explained in more detail in the dedicated systems +modelling chapter. + +In summary, a component which has modes has to expose the following 4 capabilities: + +1. Set a mode +2. Read the mode +3. Announce the mode +4. Announce the mode recursively + +## Using ECSS PUS to perform mode commanding + +# Health + +Health is an important concept for systems and components which might fail. +Oftentimes, the health is tied to the mode of a system component in some shape or form, and +determines whether a system component is usable. Health is also an extremely useful concept +to simplify the Fault Detection, Isolation and Recovery (FDIR) concept of a system. + +The following health states are based on the ones used inside the FSFW and are enough to model most +use-cases: + +- `HEALTHY` +- `FAULTY` +- `NEEDS RECOVERY` +- `EXTERNAL CONTROL` + +1. `HEALTHY` means that a component is working nominally, and can perform its task without any issues. +2. `FAULTY` means that a component does not work properly. This might also impact other system +components, so the passivation and isolation of that component is desirable for FDIR purposes. +3. `NEEDS RECOVERY` is used to attempt a recovery of a component. For example, a simple sensor +could be power-cycled if there were multiple communication issues in the last time. +4. `EXTERNAL CONTROL` is used to isolate an individual component from the rest of the system. For + example, on operator might be interested in testing a component in isolation, and the interference + of the system is not desired. In that case, the `EXTERNAL CONTROL` health state might be used + to prevent mode commands from the system while allowing external mode commands. + +