unicorn-hat

A Rust library for controlling the Pimoroni Unicorn HAT (8x8 LED matrix) on Raspberry Pi.

Features

• Pixel Control: Set pixels by coordinate (x, y) or raw index
• Color Models: RGB8 and HSV with seamless conversion
• Display Control: Brightness adjustment and rotation (0°, 90°, 180°, 270°)
• Drawing Primitives: Lines, rectangles, filled shapes
• Gradients: Horizontal and vertical color gradients
• Color Palettes: Built-in palettes with value-to-color mapping
• Hardware Abstraction: BGR format and zigzag LED mapping handled automatically

Installation

Add to your Cargo.toml:

[dependencies]
unicorn-hat = "0.1"

System Requirements

Hardware:

• Pimoroni Unicorn HAT (8×8, NOT the HD version)
• Raspberry Pi with 40-pin GPIO header

System Setup:

# Install dependencies
sudo apt-get install -y libclang-dev llvm-dev

# Enable SPI
sudo raspi-config
# Navigate to: Interface Options -> SPI -> Enable

Quick Start

use unicorn_hat::{UnicornHat, RGB8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hat = UnicornHat::new()?;

    // Set corner pixels
    hat.set_pixel(0, 0, RGB8::RED)?;
    hat.set_pixel(7, 0, RGB8::GREEN)?;
    hat.set_pixel(0, 7, RGB8::BLUE)?;
    hat.set_pixel(7, 7, RGB8::YELLOW)?;

    // Display changes
    hat.display()?;

    Ok(())
}

Run with sudo:

sudo cargo run

Examples

Rainbow Gradient (HSV)

use unicorn_hat::{UnicornHat, HSV};

let mut hat = UnicornHat::new()?;

for x in 0..8 {
    let hue = (x as f32 / 8.0) * 360.0;
    let color = HSV::new(hue, 1.0, 1.0).into();
    for y in 0..8 {
        hat.set_pixel(x, y, color)?;
    }
}

hat.display()?;

Drawing Primitives

use unicorn_hat::{primitives, UnicornHat, RGB8};

let mut hat = UnicornHat::new()?;

// Draw a horizontal line
primitives::draw_hline(&mut hat, 3, RGB8::RED)?;

// Draw a filled rectangle
primitives::fill_rect(&mut hat, 1, 1, 3, 3, RGB8::BLUE)?;

hat.display()?;

Color Gradients

use unicorn_hat::{primitives, UnicornHat, RGB8};

let mut hat = UnicornHat::new()?;

// Horizontal gradient from red to blue
primitives::gradient_h(&mut hat, RGB8::RED, RGB8::BLUE)?;

hat.display()?;

High-Level Features

For text rendering, scrolling animations, and frame buffers, see the companion crate:

[dependencies]
unicorn-hat = "0.1"
unicorn-hat-extras = "0.1"

See the unicorn-hat-extras documentation for details.

API Overview

Core Types

• UnicornHat - Main controller
• RGB8 - 8-bit RGB color (0-255 per channel)
• HSV - Hue/Saturation/Value color model
• Rotate - Display rotation
• Origin - Coordinate system origin (TopLeft or BottomLeft)

Main Methods

// Initialization
let mut hat = UnicornHat::new()?;

// Pixel operations
hat.set_pixel(x, y, color)?;
hat.get_pixel(x, y)?;
hat.fill(color);
hat.clear();

// Display
hat.display()?;

// Configuration
hat.set_brightness(128);        // 0-255
hat.set_rotation(Rotate::RotCW90);

// Bulk operations
hat.set_all(&grid)?;
let grid = hat.get_all()?;

Color Constants

RGB8::BLACK, RGB8::WHITE, RGB8::RED, RGB8::GREEN, RGB8::BLUE, RGB8::YELLOW, RGB8::CYAN, RGB8::MAGENTA, RGB8::ORANGE, RGB8::PURPLE

Permissions

The library requires hardware access. You have two options:

Option 1: Run with sudo (Development)

sudo cargo run

Option 2: Set capabilities (Production)

cargo build --release
sudo setcap cap_sys_rawio=ep target/release/your-program
./target/release/your-program  # No sudo needed

Note: Capabilities must be reset after each rebuild.

Examples

Run the included examples:

sudo cargo run --example simple
sudo cargo run --example rainbow
sudo cargo run --example gradients

Documentation

Generate full API documentation:

cargo doc --open

Hardware Details

• GPIO Pin: 18 (PWM)
• LED Type: WS2812
• LED Count: 64 (8×8)
• Frequency: 800 kHz
• Color Format: BGR (handled internally)

Known Limitations

• Audio Conflict: PWM conflicts with 3.5mm audio jack (use HDMI or USB audio)
• Single Instance: Only one process can control the HAT at a time
• Requires Root: Needs sudo or CAP_SYS_RAWIO capability

License

MIT License - see LICENSE for details.

Links

• Documentation
• Repository
• Pimoroni Unicorn HAT

See Also

• unicorn-hat-extras - Text, scrolling, and animations