msp430-hal 0.8.0

Implementation of embedded-hal for MSP430 microcontrollers
Documentation

msp430-hal

A high-level Hardware Abstraction Layer (HAL) for the MSP430 family of microcontrollers, principally targetting the FR2xxx / 4xxx family, but seeking to support the all MSP430 devices eventually.

Crates.io Docs.rs CI License MSRV

This crate is primarily designed to be used as a dependency in another project, but the examples in the repo can be build and flashed directly to a device, provided the required dependencies are installed.

Dependencies

To build the examples msp430-gcc should be available on your PATH.

To flash an example mspdebug should also be available on your PATH.

Usage

The device-examples/ folder contains typical projects for various supported devices, each of which containing a number of examples They can be built by moving into the relevant project folder, then running cargo build --example <example_name>

An example can be flashed to a connected device with cargo run --example <example_name>

Supported Devices

The library currently supports a subset of the MSP430FR2xxx / 4xxx family: the MSP430FR2x5x and MSP430FR247x and MSP430FR25x2 subfamilies, and the MSP430FR2433. Adding support for a device in the MSP430FR2xxx/4xxx family is easy, see Supporting additional devices.

The device being targetted is must be specified by enabling exactly one device feature, such as msp430fr2355. This is required to build any code from this library.

Currently Supported Devices

Device Feature name
MSP430FR2476 msp430fr2476
MSP430FR2475 msp430fr2475
MSP430FR2433 msp430fr2433
MSP430FR2355 msp430fr2355
MSP430FR2353 msp430fr2353
MSP430FR2155 msp430fr2155
MSP430FR2153 msp430fr2153
MSP430FR2512 msp430fr2512
MSP430FR2522 msp430fr2522

The documentation on crates.rs (and example programs) target the MSP430FR2355. Documentation for a particular device can be built by running cargo doc --open --features <device> from within the hal/ folder, or cargo doc --open --package msp430fr2x5x-hal in a cargo project with msp430fr2x5x-hal correctly configured as a dependency, such as the projects in the device-examples/ folder.

Functionality

The library is mostly feature complete for the FR2xxx/4xxx family. There are a few edge cases not yet supported, such as:

  • Arbitrary DCO clock speed support (currently supports 1, 2, 4, 8, 12, 16, 20, 24 MHz)
  • External oscillator support
  • Some RTC clock sources (currently only supports SMCLK and VLOCLK)
  • ADC reference voltage selection

The following FR2xxx/4xxx peripherals do not yet have drivers:

  • LCD driver
  • CapTIvate
  • TIA
  • SAC-L1

PRs with implementations for these features or peripherals are welcome.

If you encounter any use cases not supported please open an issue (or submit a pull request).

Supporting additional devices

The maintainers don't have access to every device in the MSP430FR2xxx / 4xxx family, so if you want to add support for a particular device (or subfamily) we are happy to accept pull requests.

This repo contains two main parts - drivers for peripherals (shared across many devices), and pin mappings for a specific device. Many peripheral drivers have already been written, so adding support for a new device is usually just a matter of defining what peripherals a device has, and how they're connected to it's GPIO pins. The following section describes how to do this:

To add support for a device (or subfamily) you should fork this repo and:

  1. Add a new device feature in hal/cargo.toml and determine which features should be derived for your device.
  2. Create a new file in hal/src/device_specific/, import a Peripheral Access Crate (PAC) for your device, and follow hal/src/device_specific/msp430fr2x5x.rs as an example to see how to e.g. mark which GPIO pins are capable of what functionality.
    • (Note in some cases the PAC may be missing some register fields, as TI's .svd files aren't perfect. In this case the PAC should be modified if these missing register fields are used by the HAL).
  3. Append an entry to hal/src/device_specific.rs to re-export your PAC and any device-specific constants to the rest of the library.
  4. Add a project crate to device_examples/ and add some examples to test everything works (again refer to the msp430fr2355 as an example/template).
    • Ensure the memory.x file is correct, as this is usually unique to each device.
  5. Add the device name to the CI in .github/workflows/build.yml to make it automatically build all your device examples. Check that the CI passes.

For issues or concerns, feel free to open an issue.

Devices outside the FR2xxx/4xxx family

If your device exists outside the FR2xxx/4xxx family then the above still holds, but additionally it is up to you to ensure the drivers written here are compatible with your device's peripherals (e.g. by comparing the FR2xxx/4xxx user guide against your user guide). The drivers provided here have been written by referencing the 2xxx / 4xxx user guide, so if they support for other devices out-of-the-box this is incidental, however they may work regardless, require only minor modifications, or may at least serve as a reasonable starting point.

If you do find that a peripheral driver requires changes, we are happy to accept new drivers for devices outside the 2xxx / 4xxx family.

Feature Flags

In addition to the device feature flags mentioned above, this crate provides an implementation of the legacy 0.2.7 version of embedded-hal behind the embedded-hal-02 feature. Support for embedded-hal 1.0 is available by default.

Support for defmt is available through the defmt feature. See device_examples/msp430fr2355/defmt.rs for a defmt implementation on the MSP430.

Minimum Supported Rust Version (MSRV)

This crate requires the nightly toolchain to compile, currently targetting nightly-2024-09-01 (Rust 1.82) or later. It might compile with older versions but that may change in any new patch release.

Assumptions

The HAL provides a maximal set of GPIO pins (targetting the package with the most pins). If you are using one of the variants with fewer pins then it is up to you to ensure that the GPIO pins you use are in fact available. For example, on the 28-pin variant of the MSP430FR2355 eUSCI_B1 only supports I2C due to missing pins. This is not checked in the HAL.

Panics

The library is intended to be panic-free, though this hasn't been verified. If you encounter panics while using the library (or panic-never points to the existence of possible panics) please open an issue.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.