unicorn_hat/

lib.rs

//! Rust library for controlling the Pimoroni Unicorn HAT (8x8) on Raspberry Pi
//!
//! This library provides a safe, ergonomic API for controlling the 8x8 WS2812 LED grid
//! on the Pimoroni Unicorn HAT.
//!
//! # Hardware Requirements
//!
//! - Pimoroni Unicorn HAT (8x8, NOT the HD version)
//! - Raspberry Pi with GPIO access
//! - SPI enabled via raspi-config
//! - Root/sudo privileges (required for PWM hardware access)
//!
//! # Quick Start
//!
//! ```no_run
//! use unicorn_hat::{UnicornHat, RGB8};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Initialize the HAT
//! let mut hat = UnicornHat::new()?;
//!
//! // Set a pixel and display
//! hat.set_pixel_raw(0, RGB8::RED)?;
//! hat.display()?;
//!
//! // Clear all pixels
//! hat.clear();
//! hat.display()?;
//! # Ok(())
//! # }
//! ```

use rs_ws281x::{ChannelBuilder, Controller, ControllerBuilder, StripType, WS2811Error};
use thiserror::Error;

pub mod buffer;
mod color;
mod mapper;
pub mod primitives;
mod rotation;

pub use buffer::{PixelBuffer, TestBuffer};
pub use color::{Palette, RGB8, HSV};
pub use mapper::{PixelMapper, ZigzagMapping};
pub use rotation::{Origin, Rotate};

/// Hardware configuration constants
const GPIO_PIN: i32 = 18;
const DMA_CHANNEL: i32 = 10;
const LED_COUNT: usize = 64;
const FREQUENCY: u32 = 800_000; // 800kHz for WS2812

/// Errors that can occur when using the Unicorn HAT
#[derive(Error, Debug)]
pub enum Error {
    /// Invalid pixel index (must be 0-63 for 8x8 grid)
    #[error("invalid pixel index {0}, must be 0-63")]
    InvalidIndex(usize),

    /// Invalid coordinate (x or y must be 0-7)
    #[error("invalid coordinate ({0}, {1}), x and y must be 0-7")]
    InvalidCoordinate(usize, usize),

    /// Hardware error from the WS2812 controller
    #[error("hardware error: {0}")]
    Hardware(#[from] WS2811Error),
}

/// Main interface for controlling the Unicorn HAT
///
/// This struct provides low-level access to the 64 LEDs on the Unicorn HAT.
/// Pixels are addressed by raw index (0-63) in this core implementation.
///
/// # Examples
///
/// ```no_run
/// use unicorn_hat::{UnicornHat, RGB8};
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let mut hat = UnicornHat::new()?;
///
/// // Light up first LED in red
/// hat.set_pixel_raw(0, RGB8::RED)?;
/// hat.display()?;
///
/// // Clear all
/// hat.clear();
/// hat.display()?;
/// # Ok(())
/// # }
/// ```
pub struct UnicornHat {
    controller: Controller,
    buffer: [RGB8; LED_COUNT],
    mapper: ZigzagMapping,
    rotation: Rotate,
    origin: Origin,
    brightness: u8,
}

impl UnicornHat {
    /// Creates a new UnicornHat instance and initializes the hardware
    ///
    /// This will initialize the WS2812 controller with the correct GPIO pin (18),
    /// DMA channel (10), and LED count (64).
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Hardware initialization fails
    /// - Insufficient permissions (must run with sudo)
    /// - PWM hardware is in use by another process
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::UnicornHat;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn new() -> Result<Self, Error> {
        let controller = ControllerBuilder::new()
            .freq(FREQUENCY)
            .dma(DMA_CHANNEL)
            .channel(
                0,
                ChannelBuilder::new()
                    .pin(GPIO_PIN)
                    .count(LED_COUNT as i32)
                    .strip_type(StripType::Ws2812)
                    .brightness(255)
                    .build(),
            )
            .build()?;

        Ok(UnicornHat {
            controller,
            buffer: [RGB8::BLACK; LED_COUNT],
            mapper: ZigzagMapping,
            rotation: Rotate::default(),
            origin: Origin::default(),
            brightness: 128, // 50% default brightness
        })
    }

    /// Sets a pixel color by raw index
    ///
    /// The index ranges from 0 to 63 for the 8x8 grid. This is a low-level method
    /// that directly addresses the LED buffer index without coordinate transformation.
    ///
    /// Note: Changes are not visible until [`display()`](Self::display) is called.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidIndex`] if the index is greater than 63.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Set first LED to red
    /// hat.set_pixel_raw(0, RGB8::RED)?;
    ///
    /// // Set last LED to blue
    /// hat.set_pixel_raw(63, RGB8::BLUE)?;
    ///
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_pixel_raw(&mut self, index: usize, color: RGB8) -> Result<(), Error> {
        if index >= LED_COUNT {
            return Err(Error::InvalidIndex(index));
        }
        self.buffer[index] = color;
        Ok(())
    }

    /// Gets the color of a pixel by raw index
    ///
    /// Returns the current color in the buffer (not necessarily what's displayed
    /// on the hardware if [`display()`](Self::display) hasn't been called).
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidIndex`] if the index is greater than 63.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    /// hat.set_pixel_raw(0, RGB8::RED)?;
    ///
    /// let color = hat.get_pixel_raw(0)?;
    /// assert_eq!(color, RGB8::RED);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_pixel_raw(&self, index: usize) -> Result<RGB8, Error> {
        if index >= LED_COUNT {
            return Err(Error::InvalidIndex(index));
        }
        Ok(self.buffer[index])
    }

    /// Renders the current buffer to the physical LEDs
    ///
    /// All changes made via [`set_pixel_raw()`](Self::set_pixel_raw) or
    /// [`clear()`](Self::clear) are not visible until this method is called.
    ///
    /// # Errors
    ///
    /// Returns an error if the hardware render operation fails.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// hat.set_pixel_raw(0, RGB8::GREEN)?;
    /// hat.display()?; // Now the LED is actually green
    /// # Ok(())
    /// # }
    /// ```
    pub fn display(&mut self) -> Result<(), Error> {
        // Copy buffer to controller in BGR format with brightness scaling
        let brightness_factor = self.brightness as u16;

        for (i, color) in self.buffer.iter().enumerate() {
            // Apply brightness scaling to each component
            let scaled = RGB8::new(
                ((color.r as u16 * brightness_factor) / 255) as u8,
                ((color.g as u16 * brightness_factor) / 255) as u8,
                ((color.b as u16 * brightness_factor) / 255) as u8,
            );
            self.controller.leds_mut(0)[i] = scaled.to_hardware_format();
        }

        // Render to hardware
        self.controller.render()?;
        Ok(())
    }

    /// Clears all pixels to black
    ///
    /// Sets all pixels in the buffer to black (RGB8::BLACK).
    /// Note: Changes are not visible until [`display()`](Self::display) is called.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::UnicornHat;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Turn off all LEDs
    /// hat.clear();
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn clear(&mut self) {
        self.buffer.fill(RGB8::BLACK);
    }

    /// Sets a pixel color using (x, y) coordinates
    ///
    /// Coordinates are in the range 0-7, where (0, 0) is top-left and (7, 7) is bottom-right.
    /// Takes rotation into account - coordinates are relative to the current rotation setting.
    ///
    /// Note: Changes are not visible until [`display()`](Self::display) is called.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidCoordinate`] if x or y is greater than 7.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Set top-left corner to red
    /// hat.set_pixel(0, 0, RGB8::RED)?;
    ///
    /// // Set bottom-right corner to blue
    /// hat.set_pixel(7, 7, RGB8::BLUE)?;
    ///
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_pixel(&mut self, x: usize, y: usize, color: RGB8) -> Result<(), Error> {
        if x >= 8 || y >= 8 {
            return Err(Error::InvalidCoordinate(x, y));
        }

        // Apply origin transform, then rotation, then mapping
        let (ox, oy) = self.origin.apply(x, y);
        let (rx, ry) = self.rotation.apply(ox, oy);
        let index = self.mapper.coord_to_index(rx, ry);

        self.buffer[index] = color;
        Ok(())
    }

    /// Gets the color of a pixel using (x, y) coordinates
    ///
    /// Coordinates are in the range 0-7, where (0, 0) is top-left and (7, 7) is bottom-right.
    /// Takes rotation into account - coordinates are relative to the current rotation setting.
    ///
    /// Returns the current color in the buffer (not necessarily what's displayed
    /// on the hardware if [`display()`](Self::display) hasn't been called).
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidCoordinate`] if x or y is greater than 7.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    /// hat.set_pixel(0, 0, RGB8::RED)?;
    ///
    /// let color = hat.get_pixel(0, 0)?;
    /// assert_eq!(color, RGB8::RED);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_pixel(&self, x: usize, y: usize) -> Result<RGB8, Error> {
        if x >= 8 || y >= 8 {
            return Err(Error::InvalidCoordinate(x, y));
        }

        // Apply origin transform, then rotation, then mapping
        let (ox, oy) = self.origin.apply(x, y);
        let (rx, ry) = self.rotation.apply(ox, oy);
        let index = self.mapper.coord_to_index(rx, ry);

        Ok(self.buffer[index])
    }

    /// Sets the rotation of the display
    ///
    /// Changes how coordinates map to physical LEDs. Useful when the HAT is
    /// mounted in different orientations.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, Rotate, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Rotate 90° clockwise
    /// hat.set_rotation(Rotate::RotCW90);
    ///
    /// // Now (0,0) maps to what was the top-right corner
    /// hat.set_pixel(0, 0, RGB8::RED)?;
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_rotation(&mut self, rotation: Rotate) {
        self.rotation = rotation;
    }

    /// Gets the current rotation setting
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, Rotate};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let hat = UnicornHat::new()?;
    /// assert_eq!(hat.get_rotation(), Rotate::RotNone);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_rotation(&self) -> Rotate {
        self.rotation
    }

    /// Sets the coordinate system origin
    ///
    /// Changes where (0,0) is located on the display. Use `Origin::BottomLeft`
    /// for bar graphs where Y represents a value that increases upward.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, Origin, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Use bottom-left origin for bar graph
    /// hat.set_origin(Origin::BottomLeft);
    ///
    /// // Draw a bar at x=0 with height 5
    /// for y in 0..5 {
    ///     hat.set_pixel(0, y, RGB8::GREEN)?;
    /// }
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_origin(&mut self, origin: Origin) {
        self.origin = origin;
    }

    /// Gets the current coordinate system origin
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, Origin};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let hat = UnicornHat::new()?;
    /// assert_eq!(hat.get_origin(), Origin::TopLeft);
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_origin(&self) -> Origin {
        self.origin
    }

    /// Sets the brightness level
    ///
    /// Brightness is applied during [`display()`](Self::display) by scaling all RGB values.
    /// Does not modify the buffer, only affects rendering.
    ///
    /// # Arguments
    ///
    /// * `brightness` - Brightness level (0-255)
    ///   - 0 = All LEDs off
    ///   - 128 = 50% brightness (default)
    ///   - 255 = Full brightness
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Set to 25% brightness
    /// hat.set_brightness(64);
    ///
    /// hat.set_pixel(0, 0, RGB8::WHITE)?;
    /// hat.display()?;  // White pixel appears at 25% brightness
    /// # Ok(())
    /// # }
    /// ```
    pub fn set_brightness(&mut self, brightness: u8) {
        self.brightness = brightness;
    }

    /// Gets the current brightness level
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::UnicornHat;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let hat = UnicornHat::new()?;
    /// assert_eq!(hat.get_brightness(), 128);  // Default 50%
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_brightness(&self) -> u8 {
        self.brightness
    }

    /// Fills all pixels with a single color
    ///
    /// Sets every pixel in the 8x8 grid to the same color.
    /// Note: Changes are not visible until [`display()`](Self::display) is called.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Fill entire display with red
    /// hat.fill(RGB8::RED);
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn fill(&mut self, color: RGB8) {
        self.buffer.fill(color);
    }

    /// Sets all pixels from a 2D array
    ///
    /// Sets the entire 8x8 grid from a 2D array of colors.
    /// Array is indexed as `[y][x]` (row-major order).
    ///
    /// Note: Changes are not visible until [`display()`](Self::display) is called.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // Create a checkerboard pattern
    /// let mut grid = [[RGB8::BLACK; 8]; 8];
    /// for y in 0..8 {
    ///     for x in 0..8 {
    ///         if (x + y) % 2 == 0 {
    ///             grid[y][x] = RGB8::WHITE;
    ///         }
    ///     }
    /// }
    ///
    /// hat.set_all(&grid)?;
    /// hat.display()?;
    /// # Ok(())
    /// # }
    /// ```
    #[allow(clippy::needless_range_loop)]
    pub fn set_all(&mut self, grid: &[[RGB8; 8]; 8]) -> Result<(), Error> {
        for y in 0..8 {
            for x in 0..8 {
                self.set_pixel(x, y, grid[y][x])?;
            }
        }
        Ok(())
    }

    /// Gets all pixels as a 2D array
    ///
    /// Returns the current buffer contents as a 2D array.
    /// Array is indexed as `[y][x]` (row-major order).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// hat.set_pixel(3, 3, RGB8::RED)?;
    ///
    /// let grid = hat.get_all()?;
    /// assert_eq!(grid[3][3], RGB8::RED);
    /// # Ok(())
    /// # }
    /// ```
    #[allow(clippy::needless_range_loop)]
    pub fn get_all(&self) -> Result<[[RGB8; 8]; 8], Error> {
        let mut grid = [[RGB8::BLACK; 8]; 8];
        for y in 0..8 {
            for x in 0..8 {
                grid[y][x] = self.get_pixel(x, y)?;
            }
        }
        Ok(grid)
    }

    /// Shows a frame buffer on the display.
    ///
    /// Copies all pixels from a frame buffer to the display and renders them.
    /// This is useful for double-buffering and smooth animations.
    ///
    /// Note: This method calls [`display()`](Self::display) internally, so changes
    /// are immediately visible on the hardware.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # #[cfg(feature = "extras")]
    /// # {
    /// use unicorn_hat::{UnicornHat, RGB8};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mut hat = UnicornHat::new()?;
    ///
    /// // This example requires the unicorn-hat-extras crate
    /// # Ok(())
    /// # }
    /// # }
    /// ```
    pub fn show_frame(&mut self, frame: &[[RGB8; 8]; 8]) -> Result<(), Error> {
        self.set_all(frame)?;
        self.display()?;
        Ok(())
    }
}

// Implement PixelBuffer trait for UnicornHat
impl buffer::PixelBuffer for UnicornHat {
    fn set_pixel(&mut self, x: usize, y: usize, color: RGB8) -> Result<(), Error> {
        self.set_pixel(x, y, color)
    }

    fn get_pixel(&self, x: usize, y: usize) -> Result<RGB8, Error> {
        self.get_pixel(x, y)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_error_invalid_index() {
        let err = Error::InvalidIndex(100);
        let err_string = format!("{}", err);
        assert!(err_string.contains("100"));
        assert!(err_string.contains("0-63"));
    }

    #[test]
    fn test_error_invalid_coordinate() {
        let err = Error::InvalidCoordinate(10, 15);
        let err_string = format!("{}", err);
        assert!(err_string.contains("10"));
        assert!(err_string.contains("15"));
        assert!(err_string.contains("0-7"));
    }

    // Note: Hardware tests are in examples/
    // RGB8 and HSV tests are in src/color.rs
    // Mapping tests are in src/mapper.rs
    // Rotation tests are in src/rotation.rs
}