Skip to content

Latest commit

 

History

History
204 lines (117 loc) · 7.78 KB

README.md

File metadata and controls

204 lines (117 loc) · 7.78 KB
Raw

A library for the Raspberry Pi Sense HAT LED Screen

crates.io docs Build Status

The Raspberry Pi Sense HAT has an 8×8 RGB LED matrix that provides its own driver for the Linux framebuffer.

This library provides a thread-safe, strong-typed, high-level API for the LED matrix, treating it as you would any other screen on a Linux box.

Requirements

This crate supports Rust stable version v1.32.0 and higher, and is tested on nightly continuously.

Changelog

For a detailed summary of how changes are incorporated into the code, we keep a CHANGELOG.

Usage

To use this crate with the default features, add this to your Cargo.toml:

[dependencies]
sensehat-screen = "0.2"

or, to manually specify the features::

[dependencies]
sensehat-screen = { version = "0.2", default-features = false, features = ["fonts"] }

Then you can use it with your crate:

extern crate sensehat_screen

use sensehat_screen::{FrameLine, PixelColor, Screen, FONT_COLLECTION};

Documentation

You can find the documentation for the latest release at: https://docs.rs/sensehat-screen.

It contains a general description of the types contained in the library, it is a good to place to get familiar with the methods available.

Examples

Source Code Examples

You can find working examples in the source code.

  • Blinking RGB shapes

    This example builds low-level FrameLines by hand, writes them to the Screen at set intervals.

  • A letter from ゆにち (Yunichi) to Toño

    This example makes use of the built-in 8x8 FontCollection. The collection is used to sanitize a user-provided &str, returning a FontString that includes only those characters provided by the FontCollection (basically, the full latin set, some greek, some hiragana, and legacy ascii box and ascii block sets).

    Each font is given stroke color of 50% white, PixelColor::WHITE.dim(0.5), and then it is converted into a FrameLine, which is finally written to the Screen.

    See the font8x8 crate for more details.

  • Rotate demo

    This example makes use of PixelFrame, an ergonomic wrapper for representing each pixel in the 8x8 LED Matrix: [PixelColor; 64].

    Like the letter example, it makes use of the built-in FontCollection, to create two hand-made PixelFrames, made from the a yellow-colored Ñ, and a magenta-colored ó.

    Each frame is then subject to counter-clockwise rotation in steps of 90°.

  • Offset demo

    Starts with an empty screen, and two font-symbols. Each symbol is then made to slide-in from the left by setting an Offset progressively.

    Once the symbol is fully displayed, it slides-out to the right, again by incrementing the offset, until the symbol disappears.

    The same process is done with the top-bottom offset directions.

  • Clip demo

    A Clip is a PixelFrame that is the result of merging two PixelFrame. They are useful for manually constructing sequences of frames. Generally, you will prefer to work with Scroll, and FrameSequence iterators.

  • Scroll - Top To Bottom

    The name says it all: it builds a scroll of frames, and displays it from top to bottom, one clipped-frame at a time.

    Makes use of FontString, Scroll, and FrameSequence to work.

  • Scroll - Bottom To Top

    The name says it all: it builds a scroll of frames, and displays it from bottom to top, one clipped-frame at a time.

    Makes use of FontString, Scroll, and FrameSequence to work.

  • Scroll - Left To Right

    The name says it all: it builds a scroll of frames, and displays it from left to right, one clipped-frame at a time.

    Makes use of FontString, Scroll, and FrameSequence to work.

  • Scroll - Right To Left

    The name says it all: it builds a scroll of frames, and displays it from right to left, one clipped-frame at a time.

    Makes use of FontString, Scroll, and FrameSequence to work.

A Simple, Low-Level Example

The following program shows how to:

  • Open the framebuffer file-descriptor for the LED matrix screen (screen)
  • Define a pixel color (red_pixel)
  • Define a slice of pixel colors that represents the screen (all_64_pixels)
  • Turn that slice into a valid pixel frame
  • Show the frame on the screen
extern crate sensehat_screen;

use sensehat_screen::{PixelFrame, PixelColor, Screen};

fn main() {
    let mut screen = Screen::new("/dev/fb1")
        .expect("Could not open the framebuffer for the screen");

    let red_pixel = PixelColor::new(255, 0, 0); // The pixel color's RGB components are each in the range of 0 <= c < 256.

    let all_64_pixels = &[red_pixel; 64];   // A single vector of 8 x 8 = 64 pixel colors (rows are grouped by chunks of 8)

    let all_red_screen = PixelFrame::from_pixels(&all_64_pixels); // a screen frame

    screen.write_frame(&all_red_screen.frame_line()); // show the frame on the LED matrix
}

Features

default features

By default, the basic, and linux-framebuffer features are included.

basic features

A set of features that don't require the hardware. This is mostly code that you will want to use if you are writing a simulator/emulator/etc. It includes, the fonts, offset, rotate, clip, scroll, and serde-support features.

fonts

In default. A collection of legacy 8x8 fonts, renderable on the LED matrix.

offset

In default. Support for offsetting the PixelFrame left/right/top/bottom. Requires clip.

rotate

In default. Support for rotating PixelFrames by 90-degree steps.

clip

In default. Support for combining, and clipping two PixelFrames onto a single frame.

scroll

In default. Support for joining a collection of PixelFrames into a single Scroll. Requires clip.

serde-support

In default. Enables support for serialization/deserialization with serde.

linux-framebuffer

In default. Use the Linux framebuffer to write to the LED matrix.

Extra features

big-endian

Uses big-endian format, suitable for non-AMD64/x86-64 processors. This is used when encoding/decoding 16-bit RGB565 to/from 24-bit RGB. See this for more information.

Feature Wish List

  • linux-framebuffer - In default. Use the Linux framebuffer to write to the LED matrix.
  • fonts - In default. A collection of legacy 8x8 fonts, renderable on the LED matrix.
  • offset - In default. Support for offsetting the PixelFrame left/right/up/down.
  • rotate - In default. Support for rotating PixelFrames by 90-degree steps.
  • clip - In default. Support for combining, and clipping two PixelFrames onto a single frame.
  • scroll - In default. Support for joining a collection of PixelFrames into a single Scroll. Requires clip.
  • serde-support - In default. Enables support for serialization/deserialization with serde.
  • big-endian - Uses big-endian format, suitable for non-AMD64/x86-64 processors.

Contribute

Please do contribute! Issues and pull requests are welcome.

Thank you for your help improving software one changelog at a time!