Merge pull request #8 from robamu-org/mueller/update-readme

Added proper README
This commit is contained in:
Robin Mueller 2021-11-08 11:27:28 +01:00 committed by GitHub
commit 74ec8a9315
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 139 additions and 3 deletions

View File

@ -1,6 +1,6 @@
on: [push]
name: build
name: ci
jobs:
check:

View File

@ -16,3 +16,4 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
- Also adds some examples and helper files to set up new binary crates
- RTT example application
- Added basic test binary in form of an example
- README with basic instructions how to set up own binary crate

View File

@ -1,2 +1,92 @@
# va108xx-hal-rs
Rust Hardware Abstraction Layer (HAL) crate for the Vorago VA108xx family of MCUs
[![Crates.io](https://img.shields.io/crates/v/va108xx-hal)](https://crates.io/crates/va108xx-hal)
[![ci](https://github.com/robamu-org/va108xx-hal-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/robamu-org/va108xx-hal-rs/actions/workflows/ci.yml)
[![docs.rs](https://img.shields.io/docsrs/va108xx-hal)](https://docs.rs/va108xx-hal)
# HAL for the Vorago VA108xx MCU family
This repository contains the **H**ardware **A**bstraction **L**ayer (HAL), which is an additional
hardware abstraction on top of the [peripheral access API](https://github.com/robamu-org/va108xx-rs).
It is the result of reading the datasheet for the device and encoding a type-safe layer over the
raw PAC. This crate also implements traits specified by the
[embedded-hal](https://github.com/rust-embedded/embedded-hal) project, making it compatible with
various drivers in the embedded rust ecosystem.
In contrats to other HAL implementations, there is only one chip variant available here so there
is no need to pass the chip variant as a feature.
## Supported Boards
The first way to use this HAL will probably be with the
[REB1 development board](https://www.voragotech.com/products/reb1-va108x0-development-board-0).
The BSP provided for this board also contains instructions how to flash the board.
| Crate | Version | Board Support Packages |
|:------|:--------|:-----------------------|
[WIP: vorago-reb1](https://github.com/robamu/vorago-reb1-rs) | 0.0.0 | |
## Building
Building an application requires the `thumbv6m-none-eabi` cross-compiler toolchain.
If you have not installed it yet, you can do so with
```sh
rustup target add thumbv6m-none-eabi
```
After that, you can use `cargo build` to build the development version of the crate.
If you have not done this yet, it is recommended to read some of the excellent resources
available to learn Rust:
- [Rust Embedded Book](https://docs.rust-embedded.org/book/)
- [Rust Discovery Book](https://docs.rust-embedded.org/discovery/)
## Examples
Some examples, which are not specific to a particular board were provided as well.
You can build the timer example with
```sh
cargo build --example timer-ticks
```
## Setting up your own binary crate
If you have a custom board, you might be interested in setting up a new binary crate for your
project. These steps aim to provide a complete list to get a binary crate working to flash
your custom board.
The hello world of embedded development is usually to blinky a LED. This example
is contained within the
[examples folder](https://github.com/robamu-org/va108xx-hal-rs/tree/main/examples/blinky.rs).
1. Set up your Rust cross-compiler if you have not done so yet. See more in the [build chapter](#Building)
2. Create a new binary crate with `cargo init`
3. To ensure that `cargo build` cross-compiles, it is recommended to create a `cargo/config.toml`
file. A sample `.cargo/config.toml` file is provided in this repository as well
4. Copy the `memory.x` file into your project. This file contains information required by the linker.
5. Copy the `blinky.rs` file to the `src/main.rs` file in your binary crate
6. You need to add some dependencies to your `Cargo.toml` file
```toml
[dependencies]
cortex-m = "0.7.3"
cortex-m-rt = "0.7.0"
panic-halt = "0.2"
embedded-hal = "0.2.6"
[dependencies.va108xx-hal]
version = "0.1"
features = ["rt"]
```
6. Build the application with
```sh
cargo build
```
7. Flashing the board might work differently for different boards and there is usually
more than one way. You can find example instructions for the REB1 development board
[here](https://github.com/robamu/vorago-reb1-rs).

45
examples/blinky.rs Normal file
View File

@ -0,0 +1,45 @@
//! Simple blinky example
//!
//! Additional note on LEDs when using the REB1 development board:
//! Be not afraid: Pulling the GPIOs low makes the LEDs blink. See REB1
//! schematic for more details.
#![no_main]
#![no_std]
use cortex_m_rt::entry;
use embedded_hal::digital::v2::ToggleableOutputPin;
use panic_halt as _;
use va108xx_hal::{pac, prelude::*};
#[entry]
fn main() -> ! {
let mut dp = pac::Peripherals::take().unwrap();
let porta = dp.PORTA.split(&mut dp.SYSCONFIG).unwrap();
let mut led1 = porta
.pa10
.into_push_pull_output(&mut dp.IOCONFIG, &mut dp.PORTA);
let mut led2 = porta
.pa7
.into_push_pull_output(&mut dp.IOCONFIG, &mut dp.PORTA);
let mut led3 = porta
.pa6
.into_push_pull_output(&mut dp.IOCONFIG, &mut dp.PORTA);
for _ in 0..10 {
led1.set_low().ok();
led2.set_low().ok();
led3.set_low().ok();
cortex_m::asm::delay(5_000_000);
led1.set_high().ok();
led2.set_high().ok();
led3.set_high().ok();
cortex_m::asm::delay(5_000_000);
}
loop {
led1.toggle().ok();
cortex_m::asm::delay(5_000_000);
led2.toggle().ok();
cortex_m::asm::delay(5_000_000);
led3.toggle().ok();
cortex_m::asm::delay(5_000_000);
}
}