teensy4-rs

A collection of crates for Rust development on the Teensy 4. Supports both the Teensy 4.0 and 4.1 boards.

[API Docs (`master`)]

Dependencies

A Rust installation. Install Rust using rustup. We support the latest, stable Rust toolchain.
The thumbv7em-none-eabihf Rust target, which may be installed using rustup:
```
rustup target add thumbv7em-none-eabihf
```
A capable objcopy for transforming Rust binaries into hex files. The documentation and tooling in the project uses the LLVM objcopy provided by [cargo binutils]. Install [cargo binutils] if you want to precisely follow this documentation.
To download programs to your Teensy 4, you'll need either a build of [teensy_loader_cli], or the [Teensy Loader Application]. The latter is available with the Teensyduino add-ons.

Getting started

Use our cargo generate template, [teensy4-rs-template], to bootstrap your own teensy4-rs project based on these libraries:

cargo install cargo-generate
cargo generate --git https://github.com/mciantyre/teensy4-rs-template --name hello-world
cd hello-world
cargo objcopy --release -- -O ihex hello-world.hex

Download hello-world.hex to your Teensy 4!

See the Rust documentation for API information. In particular, study the [imxrt-hal APIs], since the BSP forwards many of the HAL's interfaces:

cargo doc --open

Try the various examples in this project's [examples directory] if you'd like to test your system.

Project Structure

The project has a model similar to other embedded Rust projects. We have a custom runtime crate to support our processor and memory layout. We use a separate iMXRT register access layer (RAL) and hardware abstraction layer (HAL). The RAL and HAL are provided by the [imxrt-rs project].

The main crate is a board support package (BSP), teensy4-bsp, for the Teensy 4. The BSP lets you use the Teensy 4's pins and peripherals. It also provides an implementation of the [log crate], allowing users to log over USB. If you would like to develop Rust applications for the Teensy 4, start by depending on the teensy4-bsp.

The BSP depends on the these additional crates, which are part of the BSP's workspace:

teensy4-fcb: an FCB specific to the Teensy 4. It auto-generates the FCB using the [imxrt-boot-gen] crate.
teensy4-pins: a helper library to convert the processor's pads into the pins available on a Teensy 4.0 or 4.1 board.

See the API docs for information on runtime support and BSP features.

Contributing

We welcome support! A great way to contribute is to start using the crates to develop Teensy 4 applications. Submit an issue to help us identify bugs, feature requests, or documentation gaps. See [CONTRIBUTING.md] to learn about the best issue tracker for your request.

If you want to directly contribute to the teensy4-rs project, read the development guidance in [CONTRIBUTING.md].

Q/A

There's more C than Rust! How is this a Rust project?

There used to be more Rust code here. But today, most Rust development happens in the [imxrt-rs project].

We have C sources in this project because

we can't easily express the equivalent Rust code on a stable compiler (runtime support)
we haven't written a Rust implementation to replace it (USB support)

We precompile these C sources so that our users do not need an ARM toolchain to compile the crates.

Acknowledgements and References

The [Teensy 4] is wonderful, and that's thanks to the hard work of PJRC and friends. We can find the Teensy code used in the Arduino plugins [here]. The code greatly influenced this library.
The Rust Cortex M team, specifically the [cortex-m-rt] crate.

License

Licensed under either of

Apache License, Version 2.0 ([LICENSE-APACHE] or http://www.apache.org/licenses/LICENSE-2.0)
MIT license ([LICENSE-MIT] or http://opensource.org/licenses/MIT)

at your option.