From 13325056f6127724ca68fc0302fbc7e12b84f817 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Thu, 24 Sep 2026 19:14:57 +0200 Subject: [PATCH] typos and design chapter fixes --- satrs-book/src/TODO.md | 2 +- satrs-book/src/communication.md | 24 +++++++++--------- satrs-book/src/constrained-systems.md | 14 +++++------ satrs-book/src/design.md | 35 +++++++++++++++------------ satrs-book/src/events.md | 2 +- satrs-book/src/example.md | 4 +-- satrs-book/src/fdir.md | 2 +- satrs-book/src/housekeeping.md | 10 ++++---- satrs-book/src/introduction.md | 10 ++++---- satrs-book/src/modes-and-health.md | 12 ++++----- satrs-book/src/system-view.md | 6 ++--- satrs-book/src/tmtc-modelling.md | 12 ++++----- 12 files changed, 69 insertions(+), 64 deletions(-) diff --git a/satrs-book/src/TODO.md b/satrs-book/src/TODO.md index b22251b..5a10ad1 100644 --- a/satrs-book/src/TODO.md +++ b/satrs-book/src/TODO.md @@ -9,5 +9,5 @@ Refer to new sections in the system view page: -- [Fault, Detection, Isolation and Recovery (FDIR)](./fdir.md) +- [Fault Detection, Isolation and Recovery (FDIR)](./fdir.md) - and the [mode tree](./mode-tree.md) diff --git a/satrs-book/src/communication.md b/satrs-book/src/communication.md index 9ff1c6a..f49bb42 100644 --- a/satrs-book/src/communication.md +++ b/satrs-book/src/communication.md @@ -2,10 +2,10 @@ # Communication with sat-rs based software -Communication is a vital topic for remote system which are usually not (directly) +Communication is a vital topic for remote systems which are usually not (directly) connected to the internet and only have 1-2 communication links during nominal operation. However, -most of these systems have internet access during development cycle. There are various standards -provided by CCSDS and ECSS which can be useful to determine how to communicate with the satellite +most of these systems have internet access during the development cycle. There are various standards +provided by CCSDS which can be useful to determine how to communicate with the satellite and the primary On-Board Software. Most communication with space systems is usually packet based. For example, the CCSDS space @@ -15,7 +15,7 @@ provides some support for the [CCSDS space packet protocol](https://ccsds.org/Pu 1. [UDP TMTC Server](https://docs.rs/satrs/latest/satrs/hal/std/udp_server/index.html). UDP is already packet based which makes it an excellent fit for exchanging space packets. 2. [TCP TMTC Server Components](https://docs.rs/satrs/latest/satrs/hal/std/tcp_server/index.html). - TCP is a stream based protocol, so the library provides building blocks to parse telemetry + TCP is a stream based protocol, so the library provides building blocks to parse telecommands from an arbitrary bytestream. Two concrete implementations are provided: - [TCP spacepackets server](https://docs.rs/satrs/latest/satrs/hal/std/tcp_server/struct.TcpSpacepacketsServer.html) to parse tightly packed CCSDS Spacepackets. @@ -26,8 +26,8 @@ provides some support for the [CCSDS space packet protocol](https://ccsds.org/Pu # Working with telemetry and telecommands (TMTC) The commands sent to a space system are commonly called telecommands (TC) while the data received -from it are called telemetry (TM). One way to model the packet handling is to introduce the concept -of a TC source and a TM sink can be applied to most satellites. The TM sink is the one entity where +from it are called telemetry (TM). One way to model the packet handling, which can be applied to most +satellites, is to introduce the concept of a TC source and a TM sink. The TM sink is the one entity where all generated telemetry arrives in real-time. The most important task of the TM sink usually is to send all arriving telemetry to the ground segment of a satellite mission immediately. @@ -35,7 +35,7 @@ Another important task might be to store all arriving telemetry persistently. Th important for space systems which do not have permanent contact like low-earth-orbit (LEO) satellites. -The diagram below shows one concrete example of how this could look like. +The diagram below shows one concrete example of what this could look like. ```mermaid flowchart LR @@ -51,7 +51,7 @@ The most important task of a TC source is to deliver the telecommands to the cor For component oriented software using message passing, this usually includes demultiplexing to determine where a command needs to be sent. -The diagram below shows one concrete example of how this could look like. +The diagram below shows one concrete example of what this could look like. ```mermaid flowchart LR @@ -64,7 +64,7 @@ flowchart LR ``` Using a generic concept of a TC source and a TM sink as part of the software design simplifies -the flexibility of the TMTC infrastructure: Newly added TM generators and TC receiver only have to +the flexibility of the TMTC infrastructure: Newly added TM generators and TC receivers only have to forward their generated or received packets to those handler objects. # Packet format @@ -80,16 +80,16 @@ This is a protocol which already provides us with some useful fields: multiplexing - Basic sequence counter which can be used to determine missed packets -However, how does the actual payload that we want to send to or from the satellite actually look +However, what does the actual payload that we want to send to or from the satellite actually look like? We recommend a payload format which is created with the excellent [`serde`](https://serde.rs/) library. The [TMTC modelling](./tmtc-modelling.md) chapter provides more information. -# Low-level protocols and the bridge to the communcation subsystem +# Low-level protocols and the bridge to the communication subsystem Many satellite systems usually use the lower levels of the OSI layer in addition to the application layer. This oftentimes requires special hardware like dedicated FPGAs to handle forward error correction fast enough. `sat-rs` -might provide components to handle standard like the Unified Space Data Link Standard (USLP) in +might provide components to handle standards like the Unified Space Data Link Protocol (USLP) in software but most of the time the handling of communication is performed through custom software and hardware. Still, connecting this custom software and hardware to `sat-rs` can mostly be done by using the concept of TC sources and TM sinks mentioned previously. diff --git a/satrs-book/src/constrained-systems.md b/satrs-book/src/constrained-systems.md index 59736ff..95f2cd1 100644 --- a/satrs-book/src/constrained-systems.md +++ b/satrs-book/src/constrained-systems.md @@ -4,15 +4,15 @@ Software for space systems oftentimes has different requirements than the softwa systems or servers. Currently, most space systems are considered embedded systems. For these systems, the computation power and the available memory are important resources -which are also constrained. This might make completeley heap based memory management schemes which -are oftentimes used on host and server based systems unfeasable. Still, completely forbidding -heap allocations might make software development unnecessarilly difficult, especially in a +which are also constrained. This might make completely heap based memory management schemes which +are oftentimes used on host and server based systems infeasible. Still, completely forbidding +heap allocations might make software development unnecessarily difficult, especially in a time where the OBSW might be running on Linux based systems with hundreds of MBs of RAM. A useful pattern commonly used in space systems is to limit heap allocations to program initialization time and avoid frequent run-time allocations. This prevents issues like running out of memory (something even Rust can not protect from) or heap fragmentation on systems -without a MMU. +without an MMU. # Using an embedded allocator @@ -22,7 +22,7 @@ which allows run-time tracking of the memory usage. # Using pre-allocated pool structures -A candidate for heap allocations is the TMTC and handling. TC, TMs and IPC data are all +A candidate for heap allocations is the TMTC handling. TC, TMs and IPC data are all candidates where the data size might vary greatly. The regular solution for host systems might be to send around this data as a `Vec` until it is dropped. `sat-rs` provides another solution to avoid run-time allocations by offering pre-allocated static @@ -33,8 +33,8 @@ For example, a very small telecommand (TC) pool might look like this: The core of the pool abstractions is the [PoolProvider trait](https://docs.rs/satrs/latest/satrs/pool/trait.PoolProvider.html). -This trait specifies the general API a pool structure should have without making assumption -of how the data is stored. +This trait specifies the general API a pool structure should have without making assumptions +about how the data is stored. This trait is implemented by a static memory pool implementation. The code to generate this static pool would look like this: diff --git a/satrs-book/src/design.md b/satrs-book/src/design.md index 199f60e..9c98be4 100644 --- a/satrs-book/src/design.md +++ b/satrs-book/src/design.md @@ -2,37 +2,43 @@ Satellites and space systems in general are complex systems with a wide range of requirements for both the hardware and the software. Consequently, the general design of the library is centered -around many light-weight components which try to impose as few restrictions as possible on how to -solve certain problems. +around many light-weight components and a toolbox principle where you assemble everything +you need instead of plugging something into a larger framework. This approach allows the largest +amount of flexibility, including the operating system and platform choice. For example, `sat-rs` +can be used both in `async` and regular synchronous platforms. There are still a lot of common patterns and architectures across these systems where guidance of how to solve a problem and a common structure would still be extremely useful to avoid pitfalls which were already solved and to avoid boilerplate code. This library tries to provide this structure and guidance the following way: -1. Providing this book which explains the architecture and design patterns in respect to common +1. Providing this book which explains the architecture and design patterns with respect to common issues and requirements of space systems. 2. Providing an example application. Space systems still commonly have large monolithic - primary On-Board Softwares, so the choice was made to provide one example software which + primary On-Board Software, so the choice was made to provide one example software which contains the various features provided by sat-rs. -3. Providing a good test suite. This includes both unittests and integration tests. The integration +3. Providing a good test suite. This includes both unit tests and integration tests. The integration tests can also serve as smaller usage examples than the large `satrs-example` application. -This library has special support for standards used in the space industry. This especially -includes standards provided by Consultative Committee for Space Data Systems (CCSDS) and European -Cooperation for Space Standardization (ECSS). It does not enforce using any of those standards, -but it is always recommended to use some sort of standard for interoperability. +This library has special support for standards used in the space industry. The recommended +standards are provided by the Consultative Committee for Space Data Systems (CCSDS): + +- The CCSDS Space Packet Protocol as the basic packet format for telecommands and telemetry. +- The CCSDS File Delivery Protocol (CFDP) for file transfers. + +The library does not enforce using any of those standards, but it is always recommended to use +some sort of standard for interoperability. A lot of the modules and design considerations are based on the Flight Software Framework (FSFW). The FSFW has its own [documentation](https://documentation.irs.uni-stuttgart.de/fsfw/), which will be referred to when applicable. The FSFW was developed over a period of 10 years for the Flying Laptop Project by the University of Stuttgart with Airbus Defence and Space GmbH. -It has flight heritage through the 2 mssions [FLP](https://www.irs.uni-stuttgart.de/en/research/satellitetechnology-and-instruments/smallsatelliteprogram/flying-laptop/) +It has flight heritage through the 2 missions [FLP](https://www.irs.uni-stuttgart.de/en/research/satellitetechnology-and-instruments/smallsatelliteprogram/flying-laptop/) and [EIVE](https://www.irs.uni-stuttgart.de/en/research/satellitetechnology-and-instruments/smallsatelliteprogram/EIVE/). Therefore, a lot of the design concepts were ported more or less unchanged to the `sat-rs` library. FLP is a medium-size small satellite with a higher budget and longer development time than EIVE, -which allowed to build a highly reliable system while EIVE is a smaller 6U+ cubesat which had a +which allowed building a highly reliable system while EIVE is a smaller 6U+ cubesat which had a shorter development cycle and was built using cheaper COTS components. This library also tries to accumulate the knowledge of developing the OBSW and operating the satellite for both these different systems and provide a solution for a wider range of small satellite systems. @@ -42,16 +48,15 @@ engineering to provide a reliable and robust basis for space On-Board Software. of using the Rust programming language was made for the following reasons: 1. Rust has safety guarantees which are a perfect fit for space systems which generally have high - robustness and reliablity guarantees. + robustness and reliability guarantees. 2. Rust is suitable for embedded systems. It can also be run on smaller embedded systems like the STM32 which have also become common in the space sector. All space systems are embedded systems, which makes using large languages like Python challenging even for OBCs with more performance. 3. Rust has support for linking C APIs through its excellent FFI support. This is especially - important because many vendor provided libaries are still C based. -4. Modern tooling like a package managers and various development helper, which can further reduce + important because many vendor provided libraries are still C based. +4. Modern tooling like a package manager and various development helpers, which can further reduce development cycles for space systems. `cargo` provides tools like auto-formatters and linters which can immediately ensure a high software quality throughout each development cycle. 5. A large ecosystem with excellent libraries which also leverages the excellent tooling provided previously. Integrating these libraries is a lot easier compared to languages like C/C++ where there is still no standardized way to use packages. - diff --git a/satrs-book/src/events.md b/satrs-book/src/events.md index e1f5a86..e7a4b21 100644 --- a/satrs-book/src/events.md +++ b/satrs-book/src/events.md @@ -1,7 +1,7 @@ # Events Events are an important mechanism used for remote systems to monitor unexpected -or expected anomalies and events occuring on these systems. +or expected anomalies and events occurring 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 diff --git a/satrs-book/src/example.md b/satrs-book/src/example.md index 1b2b36e..26e8648 100644 --- a/satrs-book/src/example.md +++ b/satrs-book/src/example.md @@ -87,7 +87,7 @@ The most important components of the TMTC infrastructure include the following c - A TC source component which demultiplexes and routes telecommands based on parameters like packet APID and a target ID which is part of the packet payload. -- A TM sink sink component which is the target of all sent telemetry and sends it to downlink +- A TM sink component which is the target of all sent telemetry and sends it to downlink handlers like the UDP and TCP server. You can read the [Communications chapter](./communication.md) for more @@ -114,7 +114,7 @@ client and any connected TCP client. ### Application Group -The application group contain some components you might also find in a real satellite software. +The application group contains some components you might also find in a real satellite software. This includes an AOCS stack with various device handlers and system level objects. ### Shared components and functional interfaces diff --git a/satrs-book/src/fdir.md b/satrs-book/src/fdir.md index 074b2ad..8d62b50 100644 --- a/satrs-book/src/fdir.md +++ b/satrs-book/src/fdir.md @@ -1 +1 @@ -# Fault Detecion, Isolation And Recovery (FDIR) +# Fault Detection, Isolation And Recovery (FDIR) diff --git a/satrs-book/src/housekeeping.md b/satrs-book/src/housekeeping.md index 9987a1a..154f630 100644 --- a/satrs-book/src/housekeeping.md +++ b/satrs-book/src/housekeeping.md @@ -8,21 +8,21 @@ An example for this could be temperature or attitude data. Data like this is com referred to as housekeeping data, and is usually one of the most important and most resource heavy data sources received from a satellite. -First, we are going to list some assumption and requirements about Housekeeping (HK) data: +First, we are going to list some assumptions and requirements about Housekeeping (HK) data: 1. HK data is generated periodically by various system components throughout the - systems. + system. 2. An autonomous and periodic sampling of that HK data to be stored and sent to Ground is generally required. A minimum interface consists of requesting a one-shot sample of HK, enabling and disabling the periodic autonomous generation of samples and modifying the collection interval of the periodic autonomous generation. -3. HK data often needs to be shared to other software components. For example, a thermal controller +3. HK data often needs to be shared with other software components. For example, a thermal controller wants to read the data samples of all sensor components. ## Modelling our data Generally, it makes sense to model the data with Rust data structures for various reasons. For -example, the sensor data received from a 3-axis magnetometer might me modelled like this: +example, the sensor data received from a 3-axis magnetometer might be modelled like this: ```rust #[derive(Debug, Copy, Clone, serde::Serialize, serde::Deserialize)] @@ -93,7 +93,7 @@ Sometimes, you need to share the generated data as well. Furthermore, it might m decouple the HK generation from the data acquisition and only return the latest snapshot of the data. In this case, you can put the `MgmData` inside an appropriate lock structure for your platform/runtime to share it safely with other software components. For example, in a `std` system, -you might simply use an `Arc>` or a `Arc>` for this. +you might simply use an `Arc>` or an `Arc>` for this. Now, you can update that shared data structure when acquiring new data, and other software objects or the HK generation routine can safely read from it. diff --git a/satrs-book/src/introduction.md b/satrs-book/src/introduction.md index 2640809..daa94d8 100644 --- a/satrs-book/src/introduction.md +++ b/satrs-book/src/introduction.md @@ -4,8 +4,8 @@ The sat-rs book This book is the primary information resource for the [sat-rs library](https://egit.irs.uni-stuttgart.de/rust/sat-rs) in addition to the regular API documentation. It contains the following resources: -1. Architecture informations and consideration which would exceeds the scope of the regular API. -2. General information on how to build on-board Software and how `sat-rs` can help to fulfill +1. Architecture information and considerations which would exceed the scope of the regular API. +2. General information on how to build on-board software and how `sat-rs` can help to fulfill the unique requirements of writing software for remote systems. # Introduction @@ -20,7 +20,7 @@ through the 2 missions [FLP](https://www.irs.uni-stuttgart.de/en/research/satell and [EIVE](https://www.irs.uni-stuttgart.de/en/research/satellitetechnology-and-instruments/smallsatelliteprogram/EIVE/). However, `sat-rs` has a significantly reduced scope compared to those frameworks. Rust provides -a great ecosystem and a powerful standard library which reduced the need of large and complex +a great ecosystem and a powerful standard library which reduces the need for large and complex frameworks. # Getting started with the example @@ -28,7 +28,7 @@ frameworks. The [`satrs-example`](https://egit.irs.uni-stuttgart.de/rust/sat-rs/src/branch/main/satrs-example) provides various practical usage examples of the `sat-rs` framework. If you are more interested in the practical application of `sat-rs` inside an application, it is recommended to have a look at -the example application. The [`satrs-minisim`](https://egit.irs.uni-stuttgart.de/rust/sat-rs/src/branch/main/satrs-minisim) +the example application. The [`satrs-minisim`](https://egit.irs.uni-stuttgart.de/rust/sat-rs/src/branch/main/satrs-example/minisim) application complements the example application and can be used to simulate some physical devices for the `satrs-example` device handlers. @@ -44,5 +44,5 @@ Currently this library has the following flight heritage: of the experiment [here](https://egit.irs.uni-stuttgart.de/rust/ops-sat-rs). - Development and use of a sat-rs-based [demonstration on-board software](https://egit.irs.uni-stuttgart.de/rust/eurosim-obsw) alongside a Flight System Simulator in the context of a - [Bachelors Thesis](https://www.researchgate.net/publication/380785984_Design_and_Development_of_a_Hardware-in-the-Loop_EuroSim_Demonstrator) + [Bachelor's thesis](https://www.researchgate.net/publication/380785984_Design_and_Development_of_a_Hardware-in-the-Loop_EuroSim_Demonstrator) at [Airbus Netherlands](https://www.airbusdefenceandspacenetherlands.nl/). diff --git a/satrs-book/src/modes-and-health.md b/satrs-book/src/modes-and-health.md index 4a05081..fbd9771 100644 --- a/satrs-book/src/modes-and-health.md +++ b/satrs-book/src/modes-and-health.md @@ -5,9 +5,9 @@ system reasoning for both system operators and OBSW developers. They also provid the behaviour of a component and also provide observability of a system. A few examples of how to model the mode of different components within a space system with modes will be given. -## Pyhsical device component with modes +## Physical device component with modes -The following simple mode scheme with the following three mode +The following simple mode scheme with the following three modes - `OFF` - `ON` @@ -18,10 +18,10 @@ 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. +2. `ON` means that a device is physically switched on, but the device is not polled periodically. 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 +If a device 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 @@ -92,8 +92,8 @@ use-cases: 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. +could be power-cycled if there were multiple communication issues recently. 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 + example, an 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. diff --git a/satrs-book/src/system-view.md b/satrs-book/src/system-view.md index 6cb0d20..c5b5b56 100644 --- a/satrs-book/src/system-view.md +++ b/satrs-book/src/system-view.md @@ -23,7 +23,7 @@ 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: +The book has dedicated chapters for some of the topics: - [TMTC handling and Serialization](./tmtc-modelling.md) - [Events](./events.md) @@ -36,7 +36,7 @@ small set of additional crates. ![Linux architecture](./images/satrs-arch-linux.drawio.png) -The application layer uses `sat-rs` together with `spacepackets` for CCSDS/ECSS packet handling +The application layer uses `sat-rs` together with `spacepackets` for CCSDS packet handling and `cfdp` for file transfer. The platform layer relies on `std` for tasks, IPC, memory, time and filesystem access, `serde` and `postcard` for serialization and `log`/`fern` for logging. Hardware access typically goes through Linux mechanisms like `uio`. @@ -49,7 +49,7 @@ different, even though the application layer stays the same. ![Embassy/RTIC architecture](./images/satrs-arch-embassy.drawio.png) Here the platform layer is built around an async-centric executor, either -[Embassy](https://embassy.dev/) or [RTICv2](https://rtic.rs/). `alloc`-based crates like +[Embassy](https://embassy.dev/) or [RTICv2](https://rtic.rs/). `no_std` crates like `heapless` and `embedded-alloc` replace `std` collections and allocation, `defmt` replaces `log` for logging and hardware access goes through a board support package (BSP), a hardware abstraction layer (HAL) and a peripheral access crate (PAC) instead of the OS. diff --git a/satrs-book/src/tmtc-modelling.md b/satrs-book/src/tmtc-modelling.md index b92d7f7..82483ee 100644 --- a/satrs-book/src/tmtc-modelling.md +++ b/satrs-book/src/tmtc-modelling.md @@ -12,7 +12,7 @@ structures, fits perfectly into the data-driven approach that Rust programs tend allows us to use the excellent type system. The Rust ecosystem provides the [`serde`](https://serde.rs/) library for this task. The library -makes it trivial to add serialization support to custom datastructures by providing a +makes it trivial to add serialization support to custom data structures by providing a [`derive`](https://serde.rs/derive.html) macro. In almost all cases, you can just add this derive macro to a data structure to make it serializable with any `serde` compatible serializer. @@ -28,7 +28,7 @@ these requirements and also works well for embedded systems. Using a serializer library like `serde` allows us to do some interesting things. For example, let's assume you have a `Camera` object in software that you want to send some commands to. -This object should have the following capability: +This object should have the following capabilities: - Process a ping command - Capture an image @@ -69,16 +69,16 @@ to generate the byte representation of a `CameraRequest`, which is then sent as inside a CCSDS space packet. On the on-board software side, you can use [`postcard::from_bytes`](https://docs.rs/postcard/latest/postcard/fn.from_bytes.html) to deserialize the `CameraRequest` from the raw payload bytes. In both cases, you do not need to hand-write -the serialization and de-serialization code anymore. The only trade-off is that you need a Rust +the serialization and deserialization code anymore. The only trade-off is that you need a Rust conversion layer if you want to create your telecommands in another language like Python. Using Rust structures like this also has other advantages. Once you have the `CameraRequest` structure, you can `match` on it to cover **all** commands that the device handler needs to cover. -If you add a new field, you have to handle the new field variant as well and you can not forget -to handle a variant. +If you add a new variant, you have to handle it as well and you can not forget to handle a +variant. One trade-off to keep in mind is that a Rust `enum` will always have the size of its largest variant -in memory. If you need to send large payload to and from the on-board software, you can also +in memory. If you need to send large payloads to and from the on-board software, you can also add this data as a secondary data blob behind the primary `serde` payload, and still send something like small metadata as part of the payload. `postcard` can tell you the size of the deserialized payload which helps with determining the size of any additional payload data.