3 releases

0.1.2 Oct 11, 2022
0.1.1 Oct 8, 2022
0.1.0 Oct 8, 2022

#1585 in Embedded development


Used in navigator-rs

MIT license

26KB
550 lines

sk6812_rpi

Easy-to-use SK6812RGBW library for RaspberryPi.

Features

  • Easy strip creation - just set the SPI bus you wanna use, and set the number of LEDs.
  • Easy access to LED colors - LEDs are stored as a Vec inside Strip struct, so you can access them however you want.
  • palette integration - palette is a library dedicated for color manipulation, LED struct have implemented From/Into traits that allow for easy conversion from/to palette SRGB type. In other words - you can easely create, modify or blend LED colors in any way this library allows.
  • Gradient support - since palette has gradient support, you can just pass one to Strip and it'll be automatically pushed onto LEDs.
  • Color position shifting support - you can shift the positions of LED colors to make smooth animations using <<= and >>= operators on Strip structure instance.

Compatibility

RaspberryPi compatibility is enforced by rppal library. In other words - it should work with any RaspberryPi with GPIO header. See rppal readme for details.

Should work with any SK6812RGBW strip, or similar (WS2812-like) assuming that it uses GRBW color format. Modifying it for different formats should be pretty straighforward, but i currenlty have no time or need to extend this library like that, so feel free to fork it and modify it yourself. It should be fairly simple, see below for more details.

Installation

Just add it to your Cargo.toml

[dependencies]
sk6812_rpi = "0.1"

Usage and examples

Creating a strip

use sk6812_rpi::strip::{Bus, Strip};

let mut strip = Strip::new(Bus::Spi0, 144).unwrap()

// In case when you don't want to waste default slave-select pin, you can use this method and set it manually
let mut other_strip = Strip::new_with_custom_ss(Bus::Spi1, 20, SlaveSelect::Ss10);

Setting the strip to a specific RGB(W) color

use sk6812_rpi::strip::{Bus, Strip};
use sk6812_rpi::led::Led;

let mut strip = Strip::new(Bus::Spi0, 144).unwrap()

strip.fill(Led {
    r: 200,
    g: 0,
    b: 150,
    w: 0,
});

strip.update().unwrap();

Setting the strip to a gradient color

use sk6812_rpi::strip::{Bus, Strip}
use palette::{FromColor, Gradient, Hsv, LinSrgb, Srgb};

let mut strip = Strip::new(Bus::Spi0, 144).unwrap();

let colors: Vec<LinSrgb> = (0..=360)
    .map(|i| Srgb::from_color(Hsv::new(i as f32, 1.0, 0.8)).into_linear())
    .collect();

let gradient = Gradient::new(colors);

strip.set_gradient(gradient);
strip.update().unwrap();

Manually accessing LEDs

use sk6812_rpi::strip::{Bus, Strip}
use sk6812_rpi::led::Led;
use palette::{Hsv, Hsl, Srgb};

let mut strip = Strip::new(Bus::Spi0, 10).unwrap();

// Direct access to Led fields
strip.leds[0].r = 100;
strip.leds[1].g = 150;
strip.leds[2].b = 200;

// Conversion from arrays (RGB and RGBW, depending on the amount of items)
strip.leds[3] = [100, 150, 200].into();
strip.leds[4] = [100, 150, 200, 50].into();

// Alternative way - use functions. Works exactly the same.
strip.leds[5] = Led::from_rgb(100, 150, 200);
strip.leds[6] = Led::from_rgbw(100, 150, 200, 50);

// Conversion from `palette` types
// Only f32 color types are currently supported
strip.leds[7] = Srgb::new(0.2, 0.4, 0.6).into();
strip.leds[8] = Hsv::new(0.5, 1.0, 1.0).into();
strip.leds[9] = Hsl::new(0.85, 0.8, 0.5).into();

// Mathematical operations are also supported
strip.leds[7] /= 2;
strip.leds[8] *= 1.5;
strip.leds[9] += 20;

// You can also iterate over LEDs via `iter`/`iter_mut`, and do anything else you can do on `Vec`.
strip
    .leds
    .iter_mut()
    .enumerate()
    .for_each(|(index, led)| led.w = index as u8);

For more examples and extended usage, look into tests and src directory. There are tests for every module, presenting how to use most of the functions available.

Common issues

SPI message is too long, Strip::update throws an error

This is caused by default Raspbian SPI buffer size of 4096 bytes. To change it, edit /boot/cmdline.txt file and spidev.bufsiz=65535 to the command line.

In my case, it looks like this:

console=tty1 root=PARTUUID=09632905-02 rootfstype=ext4 fsck.repair=yes spidev.bufsiz=65535 rootwait

Yours may look differently, but the important part is to add the spidev.bufsiz=65535 there. Reboot your Raspberry and it should work.

Modifying the library to use LEDs with different color format

If you want to use this library with LEDs that don't use GRBW format, you have to modify Led::to_raw_led_bytes function (it's in led.rs file). By default, it looks like this:

pub fn to_raw_led_bytes(&self) -> Vec<u8> {
    [self.g, self.r, self.b, self.w]
        .view_bits::<Msb0>()
        .iter()
        .map(|bit| match *bit {
            true => BIT_HIGH,
            false => BIT_LOW,
        })
        .collect()
}

As you can see, it creates an array of colors and gets the bits using view_bits from bitvec library. To change the order of colors, just change the order of elements in the array. If you don't have a white channel, remove it. That's it. Rest of the code is generic and will adapt to the changes automatically.

If you'll make a generic version of Led supporting multiple color , please make a pull request and i'll gladly merge it. Should be fairly simple, but i currently have no time nor need to do so.

Dependencies

~4.5MB
~105K SLoC