diff --git a/satrs-book/src/TODO.md b/satrs-book/src/TODO.md index 91f660f..b22251b 100644 --- a/satrs-book/src/TODO.md +++ b/satrs-book/src/TODO.md @@ -7,3 +7,7 @@ - [Modelling space systems](./modelling-space-systems.md) - [Ground Segments](./ground-segments.md) +Refer to new sections in the system view page: + +- [Fault, Detection, Isolation and Recovery (FDIR)](./fdir.md) +- and the [mode tree](./mode-tree.md) diff --git a/satrs-book/src/events.md b/satrs-book/src/events.md index 6961ad7..e1f5a86 100644 --- a/satrs-book/src/events.md +++ b/satrs-book/src/events.md @@ -2,3 +2,95 @@ Events are an important mechanism used for remote systems to monitor unexpected or expected anomalies and events occuring on these systems. +They can improve the observability of a system significantly and provide a +"paper trail" of what is happening or has happened on a satellite where regular +housekeeping packets might not be sufficient. They can also be used for fault +detection, isolation and recovery (FDIR) purposes. For example, higher level +system objects can listen on certain high criticality events to initiate +custom system responses. + + +## Event Severity + +Generally, it also makes sense to classify events according to a severity system +so operators can quickly judge the importance of an event. `sat-rs` does not +constrain the severity classes or enforce their usage, but a severity +classification like this can make sense: + +- INFO +- LOW ERROR +- MEDIUM ERROR +- HIGH ERROR + +## Modelling Events with Rust + +Usually, events will be associated with certain software objects or handlers. +Oftentimes, developers and operators want to supply parameters or metadata +associated with an event. This can all be done using the Rust `enum` type. + +Let's start with an example: a camera device +handler might have the following events: + +- Image taken event +- Communication error event including an error classifier +- Communication timeout event with the configured timeout +- Overheating event + +You can model these events using the following data structure, also including +a `severity` method. + +```rust +#[derive(Debug, serde::Serialize, serde::Deserialize, Clone)] +pub enum Event { + ImageTaken, + CommunicationError(ErrorType), + CommunicationTimeout(core::time::Duration), + Overheating +} + +impl Event { + pub fn severity(&self) -> Severity { + match self { + Event::ImageTaken => Severity::Info, + Event::CommunicationError(_) => Severity::Low, + Event::CommunicationTimeout(_) => Severity::Low, + Event::Overheating => Severity::High, + } + } +} +``` + +Depending on the requirements of your system, you might want to filter which +events are packaged and sent as telemetry. This requires an identification +system. A simple scheme would be to add something like this: + +```rust +impl Event { + pub fn id(&self) -> u32 { + match self { + Event::ImageTaken => 0, + Event::CommunicationError(_) => 1, + Event::CommunicationTimeout(_) => 2, + Event::Overheating => 3, + } + } +} + +``` + +## Handling events + +When an event occurs in the system, you want to trigger the event. +This usually includes sending the event to a centralized event funnel. The funnel +takes care of packing the event into a telemetry packet as well as forwarding +the event to any other objects which are interested in the event. A message +queue system is the best solution for this. For example, on an embedded Linux +system, you might have an event sender handle like this inside your camera +device handler: + +```rust +pub struct CameraHandler { + // (...) + event_sender: std::sync::mpsc::SyncSender +} +``` diff --git a/satrs-book/src/images/satrs-arch-embassy.drawio b/satrs-book/src/images/satrs-arch-embassy.drawio index 2614303..8dfa2f5 100644 --- a/satrs-book/src/images/satrs-arch-embassy.drawio +++ b/satrs-book/src/images/satrs-arch-embassy.drawio @@ -1,80 +1,97 @@ - + - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - - + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - - - - - - - - - - - - - - - - - - + + diff --git a/satrs-book/src/images/satrs-arch-embassy.drawio.png b/satrs-book/src/images/satrs-arch-embassy.drawio.png index 05576ee..2b5d2b1 100644 Binary files a/satrs-book/src/images/satrs-arch-embassy.drawio.png and b/satrs-book/src/images/satrs-arch-embassy.drawio.png differ diff --git a/satrs-book/src/images/satrs-arch-generic.drawio b/satrs-book/src/images/satrs-arch-generic.drawio index 6d92c79..fcf9588 100644 --- a/satrs-book/src/images/satrs-arch-generic.drawio +++ b/satrs-book/src/images/satrs-arch-generic.drawio @@ -1,14 +1,14 @@ - + - + - + @@ -17,58 +17,67 @@ - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - - + + - - + + - - + + - - + + + + + + + + + + + diff --git a/satrs-book/src/images/satrs-arch-generic.drawio.png b/satrs-book/src/images/satrs-arch-generic.drawio.png index e5ed605..24ead7b 100644 Binary files a/satrs-book/src/images/satrs-arch-generic.drawio.png and b/satrs-book/src/images/satrs-arch-generic.drawio.png differ diff --git a/satrs-book/src/images/satrs-arch-linux.drawio b/satrs-book/src/images/satrs-arch-linux.drawio index d2db392..49acf53 100644 --- a/satrs-book/src/images/satrs-arch-linux.drawio +++ b/satrs-book/src/images/satrs-arch-linux.drawio @@ -1,78 +1,98 @@ - + - - + + - + + + + - - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - - - - - - - - - - - - - - - - - - + + diff --git a/satrs-book/src/images/satrs-arch-linux.drawio.png b/satrs-book/src/images/satrs-arch-linux.drawio.png index 84a4fb7..a2dd436 100644 Binary files a/satrs-book/src/images/satrs-arch-linux.drawio.png and b/satrs-book/src/images/satrs-arch-linux.drawio.png differ diff --git a/satrs-book/src/system-view.md b/satrs-book/src/system-view.md index 189857d..6cb0d20 100644 --- a/satrs-book/src/system-view.md +++ b/satrs-book/src/system-view.md @@ -13,9 +13,7 @@ Flight software built with `sat-rs` is generally structured into three layers. ![Generic architecture](./images/satrs-arch-generic.drawio.png) - **Application**: The mission specific logic. This is the code a developer writes for a - particular mission. It covers mission logic, TMTC handling, event handling, FDIR and command - scheduling. `sat-rs` provides re-usable building blocks for all of these, but the concrete - wiring and mission behaviour lives here. + particular mission. - **System / platform**: The set of services the application is built on. This covers concepts like logging, serialization, IPC, task and memory management, hardware access, filesystem access and time. Most of these components are provided by external libraries @@ -25,6 +23,12 @@ Flight software built with `sat-rs` is generally structured into three layers. The application layer stays largely the same across missions and targets. The system / platform layer is where the target environment determines which concrete crates and mechanisms are used. +The book has specified chapters for some of the topics: + +- [TMTC handling and Serialization](./tmtc-modelling.md) +- [Events](./events.md) +- [Modes](./modes-and-health.md) + ## Embedded Linux On an embedded Linux target, the platform layer is provided by the Rust standard library and a