Welcome to the Rust Bindings for rpi_ws281x

PSA - Higher Level Abstraction

If you are looking at this crate and thinking "boy, I'd like to add {insert higher abstraction}" then you may be interested in one of the below projects. This project is meant to stick strictly to the driver's feature set (and possibly a subset of that even).

• Candela: A networked LED control protocol

Remember to audit your dependencies, we take no responsibility for any security vulnerabilities resulting from the use of the above mentioned crates

If you have a crate that builds on this one and want it featured here, feel free to open a PR.

Usage Warning

This project is still a work-in-progress, and the API is very much subject to change. Most of the major stuff is covered by fairly idiomatic Rust. However, we are always striving to cover more to the level of @Meh who wrote manual bindings to this libray a while back.

Contributing

Code is licensed under the MIT license, so as long as you are cool with that, feel free to open an issue, talk about proposed changes, then open a PR! I would love a helping hand, just have to make sure things don't get too messy either.

Compiling on Raspbian

• Install Rust from https://rustup.rs/
• Run rustup target add arm-unknown-linux-gnueabihf
• Install sudo apt install libclang-dev

Cross-compiling on Ubuntu/Debian

• Install Rust from https://rustup.rs/
• Run rustup target add arm-unknown-linux-gnueabihf
• Install sudo apt install libclang-dev gcc-arm-linux-gnueabihf

AArch64 Builds

• Run rustup target add aarch64-unknown-linux-gnu
• Install cross-compiler toolchain: sudo apt install libclang-dev gcc-aarch64-linux-gnu
• Build with: cargo build --target=aarch64-unknown-linux-gnu [YOUR OPTIONS]

Cross-compiling on Windows

• Make sure Git is installed. This is used to clone the latest rpi-ws2811 lib.
• Download and install libclang from LLVM; 32-bit for Windows
• Download and install GCC for the Raspberry Pi.
• Using rustup, install the 32-bit GCC Rust toolchain and set as default:
  • rustup default stable-i686-pc-windows-gnu
• Add the Raspberry Pi architecture target to the GCC toolchain:
  • For all Raspberry Pi versions:
  • rustup target add arm-unknown-linux-gnueabihf
  • For an optimized Raspberry Pi 3 target (the ARMv7 architecture):
  • rustup target add armv7-unknown-linux-gnueabihf
• At the root of your Rust project, create a new directory and name it .cargo. Inside that directory, create a file and paste the contents:

  • [build]
    target = "arm-unknown-linux-gnueabihf"
    
    [target.arm-unknown-linux-gnueabihf]
    linker = "C:/SysGCC/raspberry/bin/arm-linux-gnueabihf-gcc.exe"
    

  • This informs Rust/Cargo to always use the arm-unknown-linux-gnueabihf target (so that --target doesn't always have to be passed to cargo) and so that the GCC linker for the given architecture is used.
  • Be sure to change the linker path or the target architecture if you installed the GCC ARM toolset in a different directory or are using the ARMv7 target instead.
• It is suggested to create a build script so that the necessary environment variables can be set. This library needs to know where to find the GCC toolset in order to cross compile the rpi-ws2811 C library for the Raspberry Pi.

An example build script might look like this (using Git for Windows Bash):

#!/usr/bin/env bash

# inform rpi-ws2811-rust where the GCC sysroot is
export RPI_WS281X_SYSROOT=C:/SysGCC/raspberry/arm-linux-gnueabihf/sysroot
# point to the GCC ARM compiler/linker.
export CC_arm_unknown_linux_gnueabihf=C:/SysGCC/raspberry/bin/arm-linux-gnueabihf-gcc.exe
# point to the GCC ARM archiver
export AR_arm_unknown_linux_gnueabihf=C:/SysGCC/raspberry/bin/arm-linux-gnueabihf-ar.exe

# run the build command
cargo build $@