diff --git a/embedded-examples/stm32f3-disco-rtic/README.md b/embedded-examples/stm32f3-disco-rtic/README.md index 090faea..0fa99ae 100644 --- a/embedded-examples/stm32f3-disco-rtic/README.md +++ b/embedded-examples/stm32f3-disco-rtic/README.md @@ -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 diff --git a/embedded-examples/stm32h7-rtic/LICENSE-APACHE b/embedded-examples/stm32h7-rtic/LICENSE-APACHE index 11069ed..16fe87b 100644 --- a/embedded-examples/stm32h7-rtic/LICENSE-APACHE +++ b/embedded-examples/stm32h7-rtic/LICENSE-APACHE @@ -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, diff --git a/embedded-examples/stm32h7-rtic/LICENSE-MIT b/embedded-examples/stm32h7-rtic/LICENSE-MIT deleted file mode 100644 index 468cd79..0000000 --- a/embedded-examples/stm32h7-rtic/LICENSE-MIT +++ /dev/null @@ -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. \ No newline at end of file diff --git a/embedded-examples/stm32h7-rtic/README.md b/embedded-examples/stm32h7-rtic/README.md index 7bc1f37..7da8627 100644 --- a/embedded-examples/stm32h7-rtic/README.md +++ b/embedded-examples/stm32h7-rtic/README.md @@ -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.