From ed4ba392072c6c8eb2f03cfb2624c61e39f302c5 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Mon, 8 Nov 2021 11:06:25 +0100 Subject: [PATCH] Added proper README - Also contains new simple blinky example - Small CI update --- .github/workflows/ci.yml | 2 +- CHANGELOG.md | 1 + README.md | 94 +++++++++++++++++++++++++++++++++++++++- examples/blinky.rs | 45 +++++++++++++++++++ 4 files changed, 139 insertions(+), 3 deletions(-) create mode 100644 examples/blinky.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5a9dad0..e5692a4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,6 +1,6 @@ on: [push] -name: build +name: ci jobs: check: diff --git a/CHANGELOG.md b/CHANGELOG.md index 31a5b8b..2c89129 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 2211bc8..99c0584 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/examples/blinky.rs b/examples/blinky.rs new file mode 100644 index 0000000..8eab007 --- /dev/null +++ b/examples/blinky.rs @@ -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); + } +}