rust/sat-rs
rust/sat-rs
5
1
Fork 0
Code Issues 9 Pull Requests Projects Releases 23 Wiki Activity

README and license files
All checks were successful
Rust/sat-rs/pipeline/head This commit looks good
Details

Browse Source
This commit is contained in:
Robin Müller 2024-05-19 21:50:29 +02:00
parent f1a1cd6054
commit fd2a8f3e99
Signed by: muellerr
GPG Key ID: A649FB78196E3849
4 changed files with 80 additions and 221 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
embedded-examples/stm32f3-disco-rtic/README.md
View File

@ -4,7 +4,7 @@ sat-rs example for the STM32F3-Discovery board
This example application shows how the [sat-rs framework](https://egit.irs.uni-stuttgart.de/rust/satrs-launchpad) This example application shows how the [sat-rs framework](https://egit.irs.uni-stuttgart.de/rust/satrs-launchpad)
can be used on an embedded target. can be used on an embedded target.
It also shows how a relatively simple OBSW could be built when no standard runtime is available. It also shows how a relatively simple OBSW could be built when no standard runtime is available.
It uses [RTIC](https://rtic.rs/1/book/en/) as the concurrency framework and the It uses [RTIC](https://rtic.rs/2/book/en/) as the concurrency framework and the
[defmt](https://defmt.ferrous-systems.com/) framework for logging. [defmt](https://defmt.ferrous-systems.com/) framework for logging.
The STM32F3-Discovery device was picked because it is a cheap Cortex-M4 based device which is also The STM32F3-Discovery device was picked because it is a cheap Cortex-M4 based device which is also

2
embedded-examples/stm32h7-rtic/LICENSE-APACHE
View File

@ -192,7 +192,7 @@ Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. you may not use this file except in compliance with the License.
You may obtain a copy of the License at You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, distributed under the License is distributed on an "AS IS" BASIS,

23
embedded-examples/stm32h7-rtic/LICENSE-MIT
View File

@ -1,23 +0,0 @@
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

274
embedded-examples/stm32h7-rtic/README.md
View File

@ -1,231 +1,113 @@
# `app-template` sat-rs example for the STM32F3-Discovery board
=======
> Quickly set up a [`probe-rs`] + [`defmt`] + [`flip-link`] embedded project This example application shows how the [sat-rs framework](https://egit.irs.uni-stuttgart.de/rust/satrs-launchpad)
can be used on an embedded target.
It also shows how a relatively simple OBSW could be built when no standard runtime is available.
It uses [RTIC](https://rtic.rs/2/book/en/) as the concurrency framework and the
[defmt](https://defmt.ferrous-systems.com/) framework for logging.
[`probe-rs`]: https://crates.io/crates/probe-rs The STM32H743ZIT device was picked because it is one of the more powerful Cortex-M based devices
[`defmt`]: https://github.com/knurling-rs/defmt available for STM with which also has a little bit more RAM available and also allows commanding
[`flip-link`]: https://github.com/knurling-rs/flip-link via TCP/IP.
## Dependencies ## Pre-Requisites
#### 1. `flip-link`: Make sure the following tools are installed:
```console 1. [`probe-rs`](https://probe.rs/): Application used to flash and debug the MCU.
$ cargo install flip-link 2. Optional and recommended: [VS Code](https://code.visualstudio.com/) with
[probe-rs plugin](https://marketplace.visualstudio.com/items?itemName=probe-rs.probe-rs-debugger)
for debugging.
## Preparing Rust and the repository
Building an application requires the `thumbv7em-none-eabihf` cross-compiler toolchain.
If you have not installed it yet, you can do so with
```sh
rustup target add thumbv7em-none-eabihf
``` ```
#### 2. `probe-rs`: A default `.cargo` config file is provided for this project, but needs to be copied to have
the correct name. This is so that the config file can be updated or edited for custom needs
without being tracked by git.
``` console ```sh
$ # make sure to install v0.2.0 or later cp def_config.toml config.toml
$ cargo install probe-rs --features cli
``` ```
#### 3. [`cargo-generate`]: The configuration file will also set the target so it does not always have to be specified with
the `--target` argument.
``` console ## Building
$ cargo install cargo-generate
After that, assuming that you have a `.cargo/config.toml` setting the correct build target,
you can simply build the application with
```sh
cargo build
``` ```
[`cargo-generate`]: https://crates.io/crates/cargo-generate ## Flashing from the command line
> *Note:* You can also just clone this repository instead of using `cargo-generate`, but this involves additional manual adjustments. You can flash the application from the command line using `probe-rs`:
## Setup ```sh
probe-rs run --chip STM32H743ZITx
#### 1. Initialize the project template
``` console
$ cargo generate \
--git https://github.com/knurling-rs/app-template \
--branch main \
--name my-app
``` ```
If you look into your new `my-app` folder, you'll find that there are a few `TODO`s in the files marking the properties you need to set. ## Debugging with VS Code
Let's walk through them together now. The STM32F3-Discovery comes with an on-board ST-Link so all that is required to flash and debug
the board is a Mini-USB cable. The code in this repository was debugged using [`probe-rs`](https://probe.rs/docs/tools/debuggerA)
and the VS Code [`probe-rs` plugin](https://marketplace.visualstudio.com/items?itemName=probe-rs.probe-rs-debugger).
Make sure to install this plugin first.
#### 2. Set `probe-rs` chip Sample configuration files are provided inside the `vscode` folder.
Use `cp vscode .vscode -r` to use them for your project.
Pick a chip from ` probe-rs chip list` and enter it into `.cargo/config.toml`. Some sample configuration files for VS Code were provided as well. You can simply use `Run` and `Debug`
to automatically rebuild and flash your application.
If, for example, you have a nRF52840 Development Kit from one of [our workshops], replace `{{chip}}` with `nRF52840_xxAA`. The `tasks.json` and `launch.json` files are generic and you can use them immediately by opening
the folder in VS code or adding it to a workspace.
[our workshops]: https://github.com/ferrous-systems/embedded-trainings-2020 ## Commanding with Python
``` diff When the SW is running on the Discovery board, you can command the MCU via a serial interface,
# .cargo/config.toml using COBS encoded PUS packets.
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
-runner = "probe-rs run --chip {{chip}}" It is recommended to use a virtual environment to do this. To set up one in the command line,
+runner = "probe-rs run --chip nRF52840_xxAA" you can use `python3 -m venv venv` on Unix systems or `py -m venv venv` on Windows systems.
After doing this, you can check the [venv tutorial](https://docs.python.org/3/tutorial/venv.html)
on how to activate the environment and then use the following command to install the required
dependency:
```sh
pip install -r requirements.txt
``` ```
#### 2.1 Pass custom log format The packets are exchanged using a dedicated serial interface. You can use any generic USB-to-UART
converter device with the TX pin connected to the PA3 pin and the RX pin connected to the PA2 pin.
You need to use an array of strings instead of a single string for the `runner` if you use a custom log format. A default configuration file for the python application is provided and can be used by running
```toml ```sh
runner = ["probe-rs", "run", "--chip", "$CHIP", "--log-format", "{L} {s}"] cp def_tmtc_conf.json tmtc_conf.json
``` ```
#### 3. Adjust the compilation target After that, you can for example send a ping to the MCU using the following command
In `.cargo/config.toml`, pick the right compilation target for your board. ```sh
./main.py -p /ping
``` diff
# .cargo/config.toml
[build]
-target = "thumbv6m-none-eabi" # Cortex-M0 and Cortex-M0+
-# target = "thumbv7m-none-eabi" # Cortex-M3
-# target = "thumbv7em-none-eabi" # Cortex-M4 and Cortex-M7 (no FPU)
-# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
+target = "thumbv7em-none-eabihf" # Cortex-M4F (with FPU)
``` ```
Add the target with `rustup`. You can configure the blinky frequency using
``` console ```sh
$ rustup target add thumbv7em-none-eabihf ./main.py -p /change_blink_freq
``` ```
#### 4. Add a HAL as a dependency All these commands will package a PUS telecommand which will be sent to the MCU using the COBS
format as the packet framing format.
In `Cargo.toml`, list the Hardware Abstraction Layer (HAL) for your board as a dependency.
For the nRF52840 you'll want to use the [`nrf52840-hal`].
[`nrf52840-hal`]: https://crates.io/crates/nrf52840-hal
``` diff
# Cargo.toml
[dependencies]
-# some-hal = "1.2.3"
+nrf52840-hal = "0.14.0"
```
⚠️ Note for RP2040 users ⚠️
You will need to not just specify the `rp-hal` HAL, but a BSP (board support crate) which includes a second stage bootloader. Please find a list of available BSPs [here](https://github.com/rp-rs/rp-hal-boards#packages).
#### 5. Import your HAL
Now that you have selected a HAL, fix the HAL import in `src/lib.rs`
``` diff
// my-app/src/lib.rs
-// use some_hal as _; // memory layout
+use nrf52840_hal as _; // memory layout
```
#### (6. Get a linker script)
Some HAL crates require that you manually copy over a file called `memory.x` from the HAL to the root of your project. For nrf52840-hal, this is done automatically so no action is needed. For other HAL crates, you can get it from your local Cargo folder, the default location is under:
```
~/.cargo/registry/src/
```
Not all HALs provide a `memory.x` file, you may need to write it yourself. Check the documentation for the HAL you are using.
#### 7. Run!
You are now all set to `cargo-run` your first `defmt`-powered application!
There are some examples in the `src/bin` directory.
Start by `cargo run`-ning `my-app/src/bin/hello.rs`:
``` console
$ # `rb` is an alias for `run --bin`
$ cargo rb hello
Finished dev [optimized + debuginfo] target(s) in 0.03s
flashing program ..
DONE
resetting device
0.000000 INFO Hello, world!
(..)
$ echo $?
0
```
If you're running out of memory (`flip-link` bails with an overflow error), you can decrease the size of the device memory buffer by setting the `DEFMT_RTT_BUFFER_SIZE` environment variable. The default value is 1024 bytes, and powers of two should be used for optimal performance:
``` console
$ DEFMT_RTT_BUFFER_SIZE=64 cargo rb hello
```
#### (8. Set `rust-analyzer.linkedProjects`)
If you are using [rust-analyzer] with VS Code for IDE-like features you can add following configuration to your `.vscode/settings.json` to make it work transparently across workspaces. Find the details of this option in the [RA docs].
```json
{
"rust-analyzer.linkedProjects": [
"Cargo.toml",
"firmware/Cargo.toml",
]
}
```
[RA docs]: https://rust-analyzer.github.io/manual.html#configuration
[rust-analyzer]: https://rust-analyzer.github.io/
## Running tests
The template comes configured for running unit tests and integration tests on the target.
Unit tests reside in the library crate and can test private API; the initial set of unit tests are in `src/lib.rs`.
`cargo test --lib` will run those unit tests.
``` console
$ cargo test --lib
(1/1) running `it_works`...
└─ app::unit_tests::__defmt_test_entry @ src/lib.rs:33
all tests passed!
└─ app::unit_tests::__defmt_test_entry @ src/lib.rs:28
```
Integration tests reside in the `tests` directory; the initial set of integration tests are in `tests/integration.rs`.
`cargo test --test integration` will run those integration tests.
Note that the argument of the `--test` flag must match the name of the test file in the `tests` directory.
``` console
$ cargo test --test integration
(1/1) running `it_works`...
└─ integration::tests::__defmt_test_entry @ tests/integration.rs:13
all tests passed!
└─ integration::tests::__defmt_test_entry @ tests/integration.rs:8
```
Note that to add a new test file to the `tests` directory you also need to add a new `[[test]]` section to `Cargo.toml`.
## Support
`app-template` is part of the [Knurling] project, [Ferrous Systems]' effort at
improving tooling used to develop for embedded systems.
If you think that our work is useful, consider sponsoring it via [GitHub
Sponsors].
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
licensed as above, without any additional terms or conditions.
[Knurling]: https://knurling.ferrous-systems.com
[Ferrous Systems]: https://ferrous-systems.com/
[GitHub Sponsors]: https://github.com/sponsors/knurling-rs