From f71332ce8a7403e6a3d0b75a976bacc6ffe30105 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Sat, 1 Aug 2020 15:45:50 +0200 Subject: [PATCH 1/3] Improve usage section in README, documnt io-* features --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a626a81a..afc5413a 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,78 @@ stm32l0xx-hal [![Build Status](https://travis-ci.com/stm32-rs/stm32l0xx-hal.svg?branch=master)](https://travis-ci.com/stm32-rs/stm32l0xx-hal) -[_stm32l0xx-hal_](https://github.com/stm32-rs/stm32l0xx-hal) is a Hardware Abstraction Layer (HAL) for the STMicro STM32L0xx family of microcontrollers. +[_stm32l0xx-hal_](https://github.com/stm32-rs/stm32l0xx-hal) is a Hardware +Abstraction Layer (HAL) for the STMicro STM32L0xx family of microcontrollers. -This crate relies on Adam Greig's [stm32l0](https://crates.io/crates/stm32l0) crate to provide appropriate register definitions and implements a partial set of the [embedded-hal](https://github.com/rust-embedded/embedded-hal) traits. +This crate relies on Adam Greig's [stm32l0](https://crates.io/crates/stm32l0) +crate to provide appropriate register definitions and implements a partial set +of the [embedded-hal](https://github.com/rust-embedded/embedded-hal) traits. -Based on the [stm32l1xx-hal](https://github.com/stm32-rs/stm32l1xx-hal) crate by Vitaly Domnikov and the [stm32f4xx-hal](https://github.com/stm32-rs/stm32f4xx-hal) crate by Daniel Egger. +Based on the [stm32l1xx-hal](https://github.com/stm32-rs/stm32l1xx-hal) crate +by Vitaly Domnikov and the [stm32f4xx-hal](https://github.com/stm32-rs/stm32f4xx-hal) +crate by Daniel Egger. +# Usage + +Add the [`stm32l0xx-hal` crate](https://crates.io/crates/stm32l0xx-hal) to your +dependencies in `Cargo.toml` and make sure to pick the appropriate `mcu-*` +Cargo feature to enjoy the full feature set for your MCU (see next section +"Supported Configurations" for more details). + +For example, when using the STM32L071KBTx MCU: + +```toml +[dependencies] +stm32l0xx-hal = { version = "0.6.2", features = ["mcu-STM32L071KBTx", "rt"] } +``` # Supported Configurations -* __stm32l0x1__ -* __stm32l0x2__ -* __stm32l0x3__ +The STM32L0 family consists of different subfamilies with different peripherals +and I/O configurations. Superficially, the family can be grouped into the +groups `stm32l0x1`, `stm32l0x2` and `stm32l0x3`. However, some aspects like +alternate function mappings for I/O pins do not follow these groups. + +In order for the HAL to properly support all those MCUs, we generate some +peripheral mappings and corresponding Cargo features using +[cube-parse](https://github.com/dbrgn/cube-parse/). + +## MCU Features (`mcu-*`) + +The easiest way for you to get started, is to use your appropriate `mcu-*` +feature. For example, when using the STM32L071KBTx MCU, you just set the +`mcu-STM32L071KBTx` feature in `Cargo.toml`: + +```toml +# Cargo.toml +[dependencies] +stm32l0xx-hal = { version = "0.6.2", features = ["mcu-STM32L071KBTx", "rt"] } +``` + +If you take a look at the [`Cargo.toml` +file](https://github.com/stm32-rs/stm32l0xx-hal/blob/master/Cargo.toml), you +can see that `mcu-STM32L071KBTx` is just an alias for `["io-STM32L071", +"stm32l0x1", "lqfp32"]`. + +## I/O Features (`io-*`) + +The `io-*` features are based on the GPIO peripheral version. This determines +the pin function mapping of the MCU. The features seem to correspond to the +product categories. + +Right now, the following features are supported: + +- `io-STM32L021` (Product category 1) +- `io-STM32L031` (Product category 2) +- `io-STM32L051` (Product category 3) +- `io-STM32L071` (Product category 5) + +The product categories should be listed in your MCU family datasheet. The name +of the `io-*` feature itself is derived from the internal name used in the +STM32CubeMX database. It does not necessarily match the name of the MCU, +for example the `STM32L062K8Tx` uses the GPIO peripheral version named +`io-STM32L051`. + # Build Dependencies @@ -27,21 +87,11 @@ Based on the [stm32l1xx-hal](https://github.com/stm32-rs/stm32l1xx-hal) crate by `$ rustup target add thumbv6m-none-eabi` + # Build Examples `$ cargo build --release --examples --features stm32l0x1,rt` -# Using as a Dependency - -To use the stm32l0xx-hal [crate](https://crates.io/crates/stm32l0xx-hal) as a dependency, add the following definition to your `Cargo.toml`: - -``` -[dependencies.stm32l0xx-hal] -version = "0.6.2" -features = ["stm32l0x1", "rt"] -``` - -Example Projects: [HABEXpico](https://github.com/arkorobotics/HABEXpico/tree/master/Firmware) # Dependecies for Flashing From f09dec6da2f91bce723ccb43f3ca28e47ac45556 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Sat, 1 Aug 2020 15:46:49 +0200 Subject: [PATCH 2/3] README: Double spaces between sections This improves readability in text mode. --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index afc5413a..5d1e5ad8 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Based on the [stm32l1xx-hal](https://github.com/stm32-rs/stm32l1xx-hal) crate by Vitaly Domnikov and the [stm32f4xx-hal](https://github.com/stm32-rs/stm32f4xx-hal) crate by Daniel Egger. + # Usage Add the [`stm32l0xx-hal` crate](https://crates.io/crates/stm32l0xx-hal) to your @@ -28,6 +29,7 @@ For example, when using the STM32L071KBTx MCU: stm32l0xx-hal = { version = "0.6.2", features = ["mcu-STM32L071KBTx", "rt"] } ``` + # Supported Configurations The STM32L0 family consists of different subfamilies with different peripherals @@ -117,6 +119,7 @@ for example the `STM32L062K8Tx` uses the GPIO peripheral version named https://github.com/cyrus-and/gdb-dashboard + # Flashing The following instructions outline how-to on flashing the 'serial' example code. This can be extended to any other example code. @@ -135,6 +138,7 @@ The following instructions outline how-to on flashing the 'serial' example code. $ ./openocd_flash.sh target/thumbv6m-none-eabi/release/examples/serial ``` + # Debugging ## Debugging with GDB @@ -166,12 +170,13 @@ The following instructions outline how-to on flashing the 'serial' example code. >>> dashboard -output /dev/ttys001 ``` -Contibutor Notes ---------- -- Revert local dependencies to external cargo and uncomment configurations before committing +# Contibutor Notes + +- Revert local dependencies to external cargo and uncomment configurations + before committing + -License -------- +# License 0-Clause BSD License, see [LICENSE-0BSD.txt](LICENSE-0BSD.txt) for more details. From 2e1f8901eb9db9a2b26007392d5ad4b698e1b311 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Sat, 1 Aug 2020 15:57:15 +0200 Subject: [PATCH 3/3] Simplify toolchain setup docs --- README.md | 53 ++++++++++++++++++++++++----------------------------- 1 file changed, 24 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 5d1e5ad8..db98b1e6 100644 --- a/README.md +++ b/README.md @@ -78,51 +78,46 @@ for example the `STM32L062K8Tx` uses the GPIO peripheral version named `io-STM32L051`. -# Build Dependencies +# Toolchain Setup -1. Rustup toolchain installer +In order to use this HAL, you need the following Setup: - https://rustup.rs +1. Install Rustup + See [rustup.rs](https://rustup.rs/) for details. You may als be able to + install Rustup directly through your distro. -# Toolchain Configuration +2. Install the `arm-none-eabi` compiler toolchain -`$ rustup target add thumbv6m-none-eabi` - - -# Build Examples - -`$ cargo build --release --examples --features stm32l0x1,rt` - - -# Dependecies for Flashing + https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads -1. Download and install the arm-none-eabi toolchain + If you cannot install the toolchain directly through your OS / distro, we + recommend installing the precompiled binaries to '/usr/local/opt'. Add the + bin folders (/bin & /arm-none-eabi/bin) to your environments variable 'PATH'. - https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads - We recommend installing the precompiled binaries to '/usr/local/opt'. - Add the bin folders (/bin & /arm-none-eabi/bin) to your environments variable 'PATH'. +3. Install the `thumbv6m-none-eabi` target for Rust -2. Install STLink Tool (>=v1.5.1) + Simply run `rustup target add thumbv6m-none-eabi` - https://github.com/texane/stlink +For more instructions on how to get started with ARM / Cortex-M programming +using Rust, check out the [Embedded Rust +Book](https://rust-embedded.github.io/book/). -3. Install OpenOCD (OPTIONAL) - NOTE: OpenOCD v0.10.0 does not fully support the stm32l0 family MCU. We recommend using `gnu-mcu-eclipse/openocd` instead: +# Build Examples - https://gnu-mcu-eclipse.github.io/openocd/install/ - We recommend installing the precompiled binaries to '/usr/local/opt'. - Add the bin folders (i.e. - /usr/local/opt/gnu-mcu-eclipse/openocd/0.10.0-12-20190422-2015/bin) to your environments variable 'PATH'. +You can build examples through Cargo: -4. Install GDB Dashboard (OPTIONAL) + $ cargo build --release --examples --features stm32l0x1,rt - https://github.com/cyrus-and/gdb-dashboard +Note that not all examples are compatible with all MCUs. You might need to peek +into the example source code. -# Flashing +# Flashing Using Helper Scripts -The following instructions outline how-to on flashing the 'serial' example code. This can be extended to any other example code. +The following instructions outline how-to on flashing the 'serial' example +code. This can be extended to any other example code. ## Flashing with ST-Flash: @@ -139,7 +134,7 @@ The following instructions outline how-to on flashing the 'serial' example code. ``` -# Debugging +# Debugging Using Helper Scripts ## Debugging with GDB