Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/saibatizoku/sensehat-screen-rs

A Rust library for the Raspberry Pi Sense HAT LED-Matrix Screen.
https://github.com/saibatizoku/sensehat-screen-rs

led-matrix led-matrix-displays linux-framebuffer raspberry-pi rgb565 rust rust-lang sense-hat

Last synced: 2 days ago
JSON representation

A Rust library for the Raspberry Pi Sense HAT LED-Matrix Screen.

Awesome Lists containing this project

README 

        
A library for the Raspberry Pi Sense HAT LED Screen

====================================================



[![crates.io](https://img.shields.io/crates/v/sensehat-screen.svg)](https://crates.io/crates/sensehat-screen)

[![docs](https://docs.rs/sensehat-screen/badge.svg)](https://docs.rs/sensehat-screen)

[![Build Status](https://travis-ci.org/saibatizoku/sensehat-screen-rs.svg?branch=master)](https://travis-ci.org/saibatizoku/sensehat-screen-rs)



The [Raspberry Pi Sense HAT](https://www.raspberrypi.org/products/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](./CHANGELOG.md).



# Usage



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

```cargo

[dependencies]

sensehat-screen = "0.2"

```



or, to manually specify the features::



```cargo

[dependencies]

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

```



Then you can use it with your crate:



```rust

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](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](./examples/blink.rs)



  This example builds low-level `FrameLine`s by hand, writes them

  to the `Screen` at set intervals.



* [A letter from ゆにち (Yunichi) to Toño](./examples/letter.rs)



  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](https://github.com/saibatizoku/font8x8-rs) crate for more details.



* [Rotate demo](./examples/rotate.rs)



  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 `PixelFrame`s, 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](./examples/offset.rs)



  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](./examples/clip.rs)



  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](./examples/scroll-top-bottom.rs)



  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](./examples/scroll-bottom-top.rs)



  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](./examples/scroll-left-right.rs)



  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](./examples/scroll-right-left.rs)



  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



```rust

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 `PixelFrame`s by 90-degree steps.



### `clip`



In `default`. Support for combining, and clipping two `PixelFrame`s onto a single frame.



### `scroll`



In `default`. Support for joining a collection of `PixelFrame`s 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](https://en.wikipedia.org/wiki/Endianness#Current_architectures) for more information.



Feature Wish List

=================

* [X] `linux-framebuffer` - In `default`. Use the Linux framebuffer to write to the LED matrix.

* [X] `fonts` - In `default`. A collection of legacy 8x8 fonts, renderable on the LED matrix.

* [X] `offset` - In `default`. Support for offsetting the `PixelFrame` left/right/up/down.

* [X] `rotate` - In `default`. Support for rotating `PixelFrame`s by 90-degree steps.

* [X] `clip` - In `default`. Support for combining, and clipping two `PixelFrame`s onto a single frame.

* [X] `scroll` - In `default`. Support for joining a collection of `PixelFrame`s into a single `Scroll`. Requires `clip`.

* [X] `serde-support` - In `default`. Enables support for serialization/deserialization with `serde`.

* [X] `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!