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

Update Embedded Examples #192

Closed
muellerr wants to merge 27 commits from restructure-embedded-examples into main
pull from: restructure-embedded-examples
merge into: rust:main
Conversation 0 Commits 27 Files Changed 50 +80 -221
4 changed files with 80 additions and 221 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit fd2a8f3e99 - Show all commits

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)
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/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.
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 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
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
[`defmt`]: https://github.com/knurling-rs/defmt
[`flip-link`]: https://github.com/knurling-rs/flip-link
The STM32H743ZIT device was picked because it is one of the more powerful Cortex-M based devices
available for STM with which also has a little bit more RAM available and also allows commanding
via TCP/IP.
## Dependencies
## Pre-Requisites
#### 1. `flip-link`:
Make sure the following tools are installed:
```console
$ cargo install flip-link
1. [`probe-rs`](https://probe.rs/): Application used to flash and debug the MCU.
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
$ # make sure to install v0.2.0 or later
$ cargo install probe-rs --features cli
```sh
cp def_config.toml config.toml
```
#### 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
$ cargo install cargo-generate
## Building
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
#### 1. Initialize the project template
``` console
$ cargo generate \
--git https://github.com/knurling-rs/app-template \
--branch main \
--name my-app
```sh
probe-rs run --chip STM32H743ZITx
```
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
# .cargo/config.toml
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
-runner = "probe-rs run --chip {{chip}}"
+runner = "probe-rs run --chip nRF52840_xxAA"
When the SW is running on the Discovery board, you can command the MCU via a serial interface,
using COBS encoded PUS packets.
It is recommended to use a virtual environment to do this. To set up one in the command line,
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
runner = ["probe-rs", "run", "--chip", "$CHIP", "--log-format", "{L} {s}"]
```sh
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.
``` 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)
```sh
./main.py -p /ping
```
Add the target with `rustup`.
You can configure the blinky frequency using
``` console
$ rustup target add thumbv7em-none-eabihf
```sh
./main.py -p /change_blink_freq
```
#### 4. Add a HAL as a dependency
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
All these commands will package a PUS telecommand which will be sent to the MCU using the COBS
format as the packet framing format.