Sense HAT Emulator¶

This package emulates the Raspberry Pi Sense HAT. An interactive GTK application is provided to permit manipulation of the emulated sensors, along with command line utilities for recording and playing back sensor readings from an actual HAT.

Links¶

The library code is licensed under the LGPL version 2.1 or above, while the applications sense_emu_gui, sense_rec, sense_play, and sense_csv are licensed under the GPL version 2.0 or above.
The source code can be obtained from GitHub, which also hosts the bug tracker
The documentation (which includes installation, API reference and example scripts) can be read on ReadTheDocs
Packages can be downloaded from PyPI, but reading the installation instructions is likely to be more useful

Table of Contents¶

Installation¶

Raspbian installation¶

If you are using the Raspbian distro, it is best to install the Sense HAT Emulator using the system’s package manager: apt. This will ensure that the emulator is easy to keep up to date, and easy to remove should you wish to do so. To install using apt simply:

$ sudo apt-get update
$ sudo apt-get install python-sense-emu python3-sense-emu sense-emu-tools

These three packages contain the following things:

sense-emu-tools: This package contains the Sense HAT Emulator application.
python-sense-emu: This is the Python 2 version of the Sense HAT Emulator library.
python3-sense-emu: This is the Python 3 version of the Sense HAT Emulator library.

To upgrade your installation when new releases are made you can simply use apt’s normal upgrade procedure:

$ sudo apt-get update
$ sudo apt-get upgrade

If you ever need to remove your installation:

$ sudo apt-get remove python-sense-emu python3-sense-emu sense-emu-tools

Ubuntu installation¶

To install from the author’s PPA:

$ sudo add-apt-repository ppa://waveform/ppa
$ sudo apt-get update
$ sudo apt-get install python-sense-emu python3-sense-emu sense-emu-tools

To upgrade your installation when new releases are made you can simply use apt’s normal upgrade procedure:

$ sudo apt-get update
$ sudo apt-get upgrade

To remove the installation:

$ sudo apt-get remove python-sense-emu python3-sense-emu sense-emu-tools

macOS installation¶

The following installation instructions assume you are using Homebrew as your macOS package manager:

$ brew install pygobject3 gtk+3

If you are using Python virtual environments for the Sense HAT Emulator, the system-site-packages option must be enabled within the virtualenv.

For existing virtual environments:

$ rm ${VIRTUAL_ENV}/lib/python*/no-global-site-packages.txt

For new virtual environments:

$ virtualenv --system-site-packages

Activate your virtual environment and install the Sense HAT Emulator:

$ pip install sense-emu

Alternate platforms¶

On platforms other than Raspbian or Ubuntu, it is probably simplest to install system wide using Python’s pip tool:

$ pip install sense-emu

To upgrade your installation when new releases are made:

$ pip install -U sense-emu

If you ever need to remove your installation:

$ pip uninstall sense-emu

Note

The emulator application requires PyGObject and cairo to be installed (GTK3 bindings for Python), but this cannot be obtained from PyPI; install PyGObject manually from your operating system’s package manager (e.g. python-gi, python3-gi, python-gi-cairo, and python3-gi-cairo on Raspbian/Ubuntu).

Also note that installation via pip won’t create short-cuts for the emulator application in your desktop’s start menu. Instead you will have to launch it manually by running sense_emu_gui from the command line.

Examples¶

Introduction¶

The Sense HAT emulator exactly mirrors the official Sense HAT API. The only difference (required because both the emulator and actual library can be installed simultaneously on a Pi) is the name: sense_emu instead of sense_hat. It is recommended to import the library in the following manner at the top of your code:

from sense_emu import SenseHat

Then, when you want to change your code to run on the actual HAT all you need do is change this line to:

from sense_hat import SenseHat

To run your scripts under the emulator, first start the emulator application, then start your script.

Several example scripts, with varying degrees of difficulty, are available from the File ‣ Open example menu within the emulator. Selecting an example from this menu will open it in Python’s IDLE environment.

Note

The example will be opened directly from the installation. To edit the example for your own purposes, use File ‣ Save As in IDLE to save the file under your home directory (e.g. /home/pi).

A selection of example scripts is given in the following sections.

Temperature¶

Displays the current temperature reading on the Sense HAT’s screen:

from sense_emu import SenseHat

sense = SenseHat()

red = (255, 0, 0)
blue = (0, 0, 255)

while True:
    temp = sense.temp
    pixels = [red if i < temp else blue for i in range(64)]
    sense.set_pixels(pixels)

Humidity¶

Displays the current humidity reading on the Sense HAT’s screen:

from sense_emu import SenseHat

sense = SenseHat()

green = (0, 255, 0)
white = (255, 255, 255)

while True:
    humidity = sense.humidity
    humidity_value = 64 * humidity / 100
    pixels = [green if i < humidity_value else white for i in range(64)]
    sense.set_pixels(pixels)

Joystick¶

Scrolls a blip around the Sense HAT’s screen in response to joystick motions:

from sense_emu import SenseHat

x = y = 4
hat = SenseHat()

def update_screen():
    hat.clear()
    hat.set_pixel(x, y, 255, 255, 255)

def clamp(value, min_value=0, max_value=7):
    return min(max_value, max(min_value, value))

def move_dot(event):
    global x, y
    if event.action in ('pressed', 'held'):
        x = clamp(x + {
            'left': -1,
            'right': 1,
            }.get(event.direction, 0))
        y = clamp(y + {
            'up': -1,
            'down': 1,
            }.get(event.direction, 0))

update_screen()
while True:
    for event in hat.stick.get_events():
        move_dot(event)
        update_screen()

An alternative way to write this example using the joystick’s event handler attributes is given below:

from sense_emu import SenseHat
from signal import pause

x = y = 4
hat = SenseHat()

def update_screen():
    hat.clear()
    hat.set_pixel(x, y, 255, 255, 255)

def clamp(value, min_value=0, max_value=7):
    return min(max_value, max(min_value, value))

def move_dot(event):
    global x, y
    if event.action in ('pressed', 'held'):
        x = clamp(x + {
            'left': -1,
            'right': 1,
            }.get(event.direction, 0))
        y = clamp(y + {
            'up': -1,
            'down': 1,
            }.get(event.direction, 0))

update_screen()
hat.stick.direction_up = move_dot
hat.stick.direction_down = move_dot
hat.stick.direction_left = move_dot
hat.stick.direction_right = move_dot
hat.stick.direction_any = update_screen
pause()

Rainbow¶

Scrolls a rainbow of colours across the Sense HAT’s pixels:

from colorsys import hsv_to_rgb
from time import sleep
from sense_emu import SenseHat

# Hues represent the spectrum of colors as values between 0 and 1. The range
# is circular so 0 represents red, ~0.2 is yellow, ~0.33 is green, 0.5 is cyan,
# ~0.66 is blue, ~0.84 is purple, and 1.0 is back to red. These are the initial
# hues for each pixel in the display.
hues = [
    0.00, 0.00, 0.06, 0.13, 0.20, 0.27, 0.34, 0.41,
    0.00, 0.06, 0.13, 0.21, 0.28, 0.35, 0.42, 0.49,
    0.07, 0.14, 0.21, 0.28, 0.35, 0.42, 0.50, 0.57,
    0.15, 0.22, 0.29, 0.36, 0.43, 0.50, 0.57, 0.64,
    0.22, 0.29, 0.36, 0.44, 0.51, 0.58, 0.65, 0.72,
    0.30, 0.37, 0.44, 0.51, 0.58, 0.66, 0.73, 0.80,
    0.38, 0.45, 0.52, 0.59, 0.66, 0.73, 0.80, 0.87,
    0.45, 0.52, 0.60, 0.67, 0.74, 0.81, 0.88, 0.95,
    ]

hat = SenseHat()

def scale(v):
    return int(v * 255)

while True:
    # Rotate the hues
    hues = [(h + 0.01) % 1.0 for h in hues]
    # Convert the hues to RGB values
    pixels = [hsv_to_rgb(h, 1.0, 1.0) for h in hues]
    # hsv_to_rgb returns 0..1 floats; convert to ints in the range 0..255
    pixels = [(scale(r), scale(g), scale(b)) for r, g, b in pixels]
    # Update the display
    hat.set_pixels(pixels)
    sleep(0.04)

Sense HAT API¶

The main class which is used to interact with the Sense HAT emulator is SenseHat. This provides accesss to all sensors, the LED pixel display, and the joystick. It is recommended that you import the library using the following idiom:

from sense_emu import SenseHat

This way, when you wish to deploy your code on an actual Sense HAT the only change you need to make is to this line, changing it to:

from sense_hat import SenseHat

SenseHat¶

class sense_emu.SenseHat(imu_settings_file='RTIMULib', text_assets='sense_hat_text')[source]¶

The main interface the Raspberry Pi Sense HAT.

This class provides properties to query the various sensors on the Sense HAT (temp, pressure, humidity, gyro, etc.) and methods to control the LED “screen” on the HAT (set_pixel(), set_pixels()).

The imu_settings_file parameter specifies the base name of the configuration file used to calibrate the sensors on the HAT. An “.ini” suffix will be implicitly added to this filename. If a file with the resulting name is present in ~/.config/sense_hat, it will be used in the configuration. Otherwise, the file will be located within /etc, and will be copied to ~/.config/sense_hat before use.

The text_assets parameter provides the base name of the PNG image and text file which will be used to define the font used by the show_message() method.

clear(*args)[source]¶

Clears the LED matrix with a single colour, default is black / off

e.g. ap.clear() or ap.clear(r, g, b) or colour = (r, g, b) ap.clear(colour)

flip_h(redraw=True)[source]¶: Flip LED matrix horizontal

flip_v(redraw=True)[source]¶: Flip LED matrix vertical

gamma_reset()[source]¶: Resets the LED matrix gamma correction to default

get_accelerometer()[source]¶: Gets the orientation in degrees from the accelerometer only

get_accelerometer_raw()[source]¶: Accelerometer x y z raw data in Gs

get_compass()[source]¶: Gets the direction of North from the magnetometer in degrees

get_compass_raw()[source]¶: Magnetometer x y z raw data in uT (micro teslas)

get_gyroscope()[source]¶: Gets the orientation in degrees from the gyroscope only

get_gyroscope_raw()[source]¶: Gyroscope x y z raw data in radians per second

get_humidity()[source]¶: Returns the percentage of relative humidity

get_orientation_degrees()[source]¶: Returns a dictionary object to represent the current orientation in degrees, 0 to 360, using the aircraft principal axes of pitch, roll and yaw

get_orientation_radians()[source]¶: Returns a dictionary object to represent the current orientation in radians using the aircraft principal axes of pitch, roll and yaw

get_pixel(x, y)[source]¶: Returns a list of [R,G,B] representing the pixel specified by x and y on the LED matrix. Top left = 0,0 Bottom right = 7,7

get_pixels()[source]¶: Returns a list containing 64 smaller lists of [R,G,B] pixels representing what is currently displayed on the LED matrix

get_pressure()[source]¶: Returns the pressure in Millibars

get_temperature()[source]¶: Returns the temperature in Celsius

get_temperature_from_humidity()[source]¶: Returns the temperature in Celsius from the humidity sensor

get_temperature_from_pressure()[source]¶: Returns the temperature in Celsius from the pressure sensor

load_image(file_path, redraw=True)[source]¶: Accepts a path to an 8 x 8 image file and updates the LED matrix with the image

set_imu_config(compass_enabled, gyro_enabled, accel_enabled)[source]¶: Enables and disables the gyroscope, accelerometer and/or magnetometer input to the orientation functions

set_pixel(x, y, *args)[source]¶

Updates the single [R,G,B] pixel specified by x and y on the LED matrix Top left = 0,0 Bottom right = 7,7

e.g. ap.set_pixel(x, y, r, g, b) or pixel = (r, g, b) ap.set_pixel(x, y, pixel)

set_pixels(pixel_list)[source]¶: Accepts a list containing 64 smaller lists of [R,G,B] pixels and updates the LED matrix. R,G,B elements must intergers between 0 and 255

set_rotation(r=0, redraw=True)[source]¶: Sets the LED matrix rotation for viewing, adjust if the Pi is upside down or sideways. 0 is with the Pi HDMI port facing downwards

show_letter(s, text_colour=[255, 255, 255], back_colour=[0, 0, 0])[source]¶: Displays a single text character on the LED matrix using the specified colours

show_message(text_string, scroll_speed=0.1, text_colour=[255, 255, 255], back_colour=[0, 0, 0])[source]¶: Scrolls a string of text across the LED matrix using the specified speed and colours

stick¶: A SenseStick object representing the Sense HAT’s joystick.

SenseStick¶

class sense_emu.SenseStick[source]¶

Represents the joystick on the Sense HAT.

get_events()[source]¶: Returns a list of all joystick events that have occurred since the last call to get_events(). The list contains events in the order that they occurred. If no events have occurred in the intervening time, the result is an empty list.

wait_for_event(emptybuffer=False)[source]¶

Waits until a joystick event becomes available. Returns the event, as an InputEvent tuple.

If emptybuffer is True (it defaults to False), any pending events will be thrown away first. This is most useful if you are only interested in “pressed” events.

direction_any¶

The function to be called when the joystick is used. The function can either take a parameter which will be the InputEvent tuple that has occurred, or the function can take no parameters at all.

This event will always be called after events associated with a specific action. Assign None to prevent this event from being fired.

direction_down¶

The function to be called when the joystick is pushed down. The function can either take a parameter which will be the InputEvent tuple that has occurred, or the function can take no parameters at all.