unicorn-hat 0.1.0

# unicorn-hat

A Rust library for controlling the [Pimoroni Unicorn HAT](https://shop.pimoroni.com/products/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`:

```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:**
```bash
# Install dependencies
sudo apt-get install -y libclang-dev llvm-dev

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

## Quick Start

```rust
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:**
```bash
sudo cargo run
```

## Examples

### Rainbow Gradient (HSV)

```rust
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

```rust
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

```rust
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:

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

See the [unicorn-hat-extras documentation](https://docs.rs/unicorn-hat-extras) 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

```rust
// 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)

```bash
sudo cargo run
```

### Option 2: Set capabilities (Production)

```bash
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:

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

## Documentation

Generate full API documentation:

```bash
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](../LICENSE) for details.

## Links

- [Documentation](https://docs.rs/unicorn-hat)
- [Repository](https://github.com/PeterParker/unicorn-hat)
- [Pimoroni Unicorn HAT](https://shop.pimoroni.com/products/unicorn-hat)

## See Also

- [unicorn-hat-extras](https://crates.io/crates/unicorn-hat-extras) - Text, scrolling, and animations