Skip to content

Commit

Permalink
Merge pull request #119 from stm32-rs/improve-docs
Browse files Browse the repository at this point in the history 
Improve README
  • Loading branch information
@arkorobotics
arkorobotics committed Aug 2, 2020
2 parents d7f0e50 + 2e1f890 commit 9d7f50a
Showing 1 changed file with 92 additions and 42 deletions.
134 changes: 92 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,73 +3,121 @@ 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.

# Build Dependencies
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/).

1. Rustup toolchain installer
## MCU Features (`mcu-*`)

https://rustup.rs
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"] }
```

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

`$ rustup target add thumbv6m-none-eabi`
## I/O Features (`io-*`)

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

`$ cargo build --release --examples --features stm32l0x1,rt`
Right now, the following features are supported:

# Using as a Dependency
- `io-STM32L021` (Product category 1)
- `io-STM32L031` (Product category 2)
- `io-STM32L051` (Product category 3)
- `io-STM32L071` (Product category 5)

To use the stm32l0xx-hal [crate](https://crates.io/crates/stm32l0xx-hal) as a dependency, add the following definition to your `Cargo.toml`:
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`.

```
[dependencies.stm32l0xx-hal]
version = "0.6.2"
features = ["stm32l0x1", "rt"]
```

Example Projects: [HABEXpico](https://github.com/arkorobotics/HABEXpico/tree/master/Firmware)
# Toolchain Setup

# Dependecies for Flashing
In order to use this HAL, you need the following Setup:

1. Download and install the arm-none-eabi toolchain
1. Install Rustup

See [rustup.rs](https://rustup.rs/) for details. You may als be able to
install Rustup directly through your distro.

2. Install the `arm-none-eabi` compiler toolchain

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

2. Install STLink Tool (>=v1.5.1)
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'.

3. Install the `thumbv6m-none-eabi` target for Rust

https://github.com/texane/stlink
Simply run `rustup target add thumbv6m-none-eabi`

3. Install OpenOCD (OPTIONAL)
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/).

NOTE: OpenOCD v0.10.0 does not fully support the stm32l0 family MCU. We recommend using `gnu-mcu-eclipse/openocd` instead:

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'.
# Build Examples

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

The following instructions outline how-to on flashing the 'serial' example code. This can be extended to any other example code.
# 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.

## Flashing with ST-Flash:

Expand All @@ -85,7 +133,8 @@ The following instructions outline how-to on flashing the 'serial' example code.
$ ./openocd_flash.sh target/thumbv6m-none-eabi/release/examples/serial
```

# Debugging

# Debugging Using Helper Scripts

## Debugging with GDB

Expand Down Expand Up @@ -116,12 +165,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.

0 comments on commit 9d7f50a

Please sign in to comment.