Crate lpc82x_hal

LPC82x Hardware Abstraction Layer

Hardware Abstraction Layer (HAL) for the NXP LPC82x series of ARM Cortex-M0+ microcontrollers.

Using LPC82x HAL in a Library

Writing a library on top of LPC82x HAL is pretty simple. All you need to do is include it via Cargo, by adding the following to your Cargo.toml:

[dependencies]
lpc82x-hal = "0.2"

With that in place, you can just reference the crate in your Rust code, like this:

// lib.rs

extern crate lpc82x_hal;

That's it! Now you can start using the LPC82x HAL APIs. Take a look at Peripherals, which is the entry point to the whole API.

Please note that LPC82x HAL is an implementation of embedded-hal. If your library is not specific to LPC82x, please consider depending on embedded-hal instead. Doing so means that your library should work on top of all embedded-hal implementations.

Using LPC82x HAL in an Application

To use LPC82x HAL in your application, you need to go through a bit of additional trouble. This section tries to walk you through some of the basics, but it's not a complete tutorial. Please refer to cortex-m-quickstart for additional details.

Runtime Support

Including LPC82x HAL in your application via Cargo is mostly the same as it is for libraries, but with one addition. You need to enable runtime support when including the crate in your Cargo.toml:

[dependencies.lpc82x-hal]
version  = "0.2"
features = ["rt"]

The runtime support will provide you with some basics that are required for your program to run correctly. However, it needs to know how the memory on your microcontroller is set up.

You can get that information from the user manual. To provide it to LPC82x HAL, create a file called memory.x in your project root (the directory where Cargo.toml is located). memory.x should look something like this:

MEMORY
{
    FLASH : ORIGIN = 0x00000000, LENGTH = 16K
    RAM   : ORIGIN = 0x10000000, LENGTH = 4K
}

Runtime support is provided by the cortex-m-rt crate. Please refer to the cortex-m-rt documentation for additional details.

Build System

The LPC82x is a Cortex-M0+ microcontroller, which means it has an ARMv6-M core. In order to compile and link a binary for that architecture, we need to install a precompiled Rust core library.

The following example assumes you installed Rust using rustup.

$ rustup target add thumbv6m-none-eabi

This will install the precompiled core library we need, enabling us to cross-compile binaries for the LPC82x.

Additionally, we need to tell Cargo how to link your project. Create the file .cargo/config in your project directory, and add the following contents:

[build]
target = "thumbv6m-none-eabi"

[target.thumbv6m-none-eabi]
rustflags = [
    "-C", "link-arg=-Tlink.x",
    "-C", "linker=arm-none-eabi-ld",
    "-Z", "linker-flavor=ld"
]

This tells Cargo to use the arm-none-eabi-gcc toolchain for linking. You need to install this separately. How to do so is dependent on your platform and is left as an exercise to the reader.

If everything is set up correctly, you can build your project with the following command:

$ cargo build --release

Uploading the Binary

There are many ways to upload the binary to the microcontroller. How to do this is currently beyond the scope of this documentation, but this fork of lpc21isp is known to work.

Examples

There are a number of examples in the repository. A good place to start is the GPIO example.

References

Various places in this crate's documentation reference the LPC82x User manual, which is available from NXP.

Re-exports

pub extern crate lpc82x_pac as raw;

pub use self::dma::DMA;

pub use self::gpio::GPIO;

pub use self::i2c::I2C;

pub use self::pmu::PMU;

pub use self::swm::SWM;

pub use self::syscon::SYSCON;

pub use self::usart::USART;

pub use self::wkt::WKT;

Modules

clock	Common types for system clocks
dma	API for Direct Memory Access (DMA)
gpio	API for General Purpose I/O (GPIO)
i2c	API for the I2C peripherals
init_state	Contains types that encode the state of hardware initialization
pmu	API for the Power Management Unit (PMU)
prelude	Re-exports various traits that are required to use lpc82x-hal
sleep	Higher-level sleep API
swm	APIs for the switch matrix (SWM)
syscon	API for system configuration (SYSCON)
usart	API for USART
wkt	API for the self-wake-up timer (WKT)

Structs

Peripherals

Provides access to all peripherals