rust/sat-rs
12
1
Fork 0
Code Issues 6 Pull Requests 2 Projects Releases 29 Wiki Activity

typos and design chapter fixes

Browse Source
This commit is contained in:
Robin Mueller
2026-09-24 19:15:37 +02:00
parent 93fcd44f13
commit cec2c09a44
12 changed files with 69 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
satrs-book/src/TODO.md
+1 -1
View File
@@ -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
+12 -12
View File
@@ -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.
satrs-book/src/constrained-systems.md
+7 -7
View File
@@ -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<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
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:
satrs-book/src/design.md
+20 -15
View File
@@ -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.
satrs-book/src/events.md
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
View File
@@ -1 +1 @@
# Fault Detecion, Isolation And Recovery (FDIR)
# Fault Detection, Isolation And Recovery (FDIR)
satrs-book/src/housekeeping.md
+5 -5
View File
@@ -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
+5 -5
View File
@@ -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/).
satrs-book/src/modes-and-health.md
+6 -6
View File
@@ -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
+3 -3
View File
@@ -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
+6 -6
View File
@@ -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.