Skip to content

Commit

Permalink
README and license files
Browse files Browse the repository at this point in the history
  • Loading branch information
@robamu
robamu committed May 19, 2024
1 parent f1a1cd6 commit fd2a8f3
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 214 deletions.
2 changes: 1 addition & 1 deletion embedded-examples/stm32f3-disco-rtic/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion embedded-examples/stm32h7-rtic/LICENSE-APACHE
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
23 changes: 0 additions & 23 deletions embedded-examples/stm32h7-rtic/LICENSE-MIT
View file

This file was deleted.

260 changes: 71 additions & 189 deletions embedded-examples/stm32h7-rtic/README.md
View file
Original file line number Diff line number Diff line change
@@ -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
```

#### 2. `probe-rs`:

``` console
$ # make sure to install v0.2.0 or later
$ cargo install probe-rs --features cli
```

#### 3. [`cargo-generate`]:

``` console
$ cargo install cargo-generate
```

[`cargo-generate`]: https://crates.io/crates/cargo-generate

> *Note:* You can also just clone this repository instead of using `cargo-generate`, but this involves additional manual adjustments.
## Setup

#### 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.

Let's walk through them together now.

#### 2. Set `probe-rs` chip

Pick a chip from ` probe-rs chip list` and enter it into `.cargo/config.toml`.

If, for example, you have a nRF52840 Development Kit from one of [our workshops], replace `{{chip}}` with `nRF52840_xxAA`.

[our workshops]: https://github.com/ferrous-systems/embedded-trainings-2020

``` 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"
```

#### 2.1 Pass custom log format

You need to use an array of strings instead of a single string for the `runner` if you use a custom log format.

```toml
runner = ["probe-rs", "run", "--chip", "$CHIP", "--log-format", "{L} {s}"]
```

#### 3. Adjust the compilation target

In `.cargo/config.toml`, pick the right compilation target for your board.
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.

``` 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)
```
## Preparing Rust and the repository

Add the target with `rustup`.
Building an application requires the `thumbv7em-none-eabihf` cross-compiler toolchain.
If you have not installed it yet, you can do so with

``` console
$ rustup target add thumbv7em-none-eabihf
```sh
rustup target add thumbv7em-none-eabihf
```

#### 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`].
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.

[`nrf52840-hal`]: https://crates.io/crates/nrf52840-hal

``` diff
# Cargo.toml
[dependencies]
-# some-hal = "1.2.3"
+nrf52840-hal = "0.14.0"
```sh
cp def_config.toml config.toml
```

⚠️ 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).
The configuration file will also set the target so it does not always have to be specified with
the `--target` argument.

#### 5. Import your HAL
## Building

Now that you have selected a HAL, fix the HAL import in `src/lib.rs`
After that, assuming that you have a `.cargo/config.toml` setting the correct build target,
you can simply build the application with

``` diff
// my-app/src/lib.rs
-// use some_hal as _; // memory layout
+use nrf52840_hal as _; // memory layout
```sh
cargo build
```

#### (6. Get a linker script)
## Flashing from the command line

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:
You can flash the application from the command line using `probe-rs`:

```
~/.cargo/registry/src/
```sh
probe-rs run --chip STM32H743ZITx
```

Not all HALs provide a `memory.x` file, you may need to write it yourself. Check the documentation for the HAL you are using.
## Debugging with VS Code

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.

#### 7. Run!
Sample configuration files are provided inside the `vscode` folder.
Use `cp vscode .vscode -r` to use them for your project.

You are now all set to `cargo-run` your first `defmt`-powered application!
There are some examples in the `src/bin` directory.
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.

Start by `cargo run`-ning `my-app/src/bin/hello.rs`:
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.

``` 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!
(..)
## Commanding with Python

$ echo $?
0
```
When the SW is running on the Discovery board, you can command the MCU via a serial interface,
using COBS encoded PUS packets.

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:
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:

``` console
$ DEFMT_RTT_BUFFER_SIZE=64 cargo rb hello
```sh
pip install -r requirements.txt
```

#### (8. Set `rust-analyzer.linkedProjects`)
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.

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].
A default configuration file for the python application is provided and can be used by running

```json
{
"rust-analyzer.linkedProjects": [
"Cargo.toml",
"firmware/Cargo.toml",
]
}
```sh
cp def_tmtc_conf.json tmtc_conf.json
```

[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.
After that, you can for example send a ping to the MCU using the following command

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
```sh
./main.py -p /ping
```

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.
You can configure the blinky frequency using

``` 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
```sh
./main.py -p /change_blink_freq
```

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.

0 comments on commit fd2a8f3

Please sign in to comment.