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

Added proper README

.github/workflows/ci.yml

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

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

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

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);
+    }
+}