Merge pull request 'typos and design chapter fixes' (#291) from book-design-update into main

Reviewed-on: #291

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)

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
+most of these systems have internet access during the development cycle. There are various standards
-provided by CCSDS and ECSS which can be useful to determine how to communicate with the satellite
+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
+from it are called telemetry (TM). One way to model the packet handling, which can be applied to most
-of a TC source and a TM sink can be applied to most satellites. The TM sink is the one entity where
+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.

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
+which are also constrained. This might make completely heap based memory management schemes which
-are oftentimes used on host and server based systems unfeasable. Still, completely forbidding
+are oftentimes used on host and server based systems infeasible. Still, completely forbidding
-heap allocations might make software development unnecessarilly difficult, especially in a
+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<u8>` 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
+This trait specifies the general API a pool structure should have without making assumptions
-of how the data is stored.
+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:

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
+around many light-weight components and a toolbox principle where you assemble everything
-solve certain problems. 
+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
+This library has special support for standards used in the space industry. The recommended
-includes standards provided by Consultative Committee for Space Data Systems (CCSDS) and European
+standards are provided by the Consultative Committee for Space Data Systems (CCSDS):
-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.
+- 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.
+   important because many vendor provided libraries are still C based.
-4. Modern tooling like a package managers and various development helper, which can further reduce
+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.
-

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

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

satrs-book/src/fdir.md

@@ -1 +1 @@
-# Fault Detecion, Isolation And Recovery (FDIR)
+# Fault Detection, Isolation And Recovery (FDIR)

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<Mutex<MgmData>>` or a `Arc<RwLock<MgmData>>` for this.
+you might simply use an `Arc<Mutex<MgmData>>` or an `Arc<RwLock<MgmData>>` 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.

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.
+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
+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/).

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.

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.

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
+If you add a new variant, you have to handle it as well and you can not forget to handle a
-to handle a variant.
+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.