Sense HAT API Reference

LED Matrix

set_rotation

If you're using the Pi upside down or sideways you can use this function to correct the orientation of the image being shown.

Parameter	Type	Valid values	Explanation
r	Integer	0 90 180 270	The angle to rotate the LED matrix though. 0 is with the Raspberry Pi HDMI port facing downwards.
redraw	Boolean	True False	Whether or not to redraw what is already being displayed on the LED matrix. Defaults to True

Returned type	Explanation
None

from sense_hat import SenseHat

sense = SenseHat()
sense.set_rotation(180)
# alternatives
sense.rotation = 180

---

flip_h

Flips the image on the LED matrix horizontally.

Parameter	Type	Valid values	Explanation
redraw	Boolean	True False	Whether or not to redraw what is already being displayed on the LED matrix. Defaults to True

Returned type	Explanation
List	A list containing 64 smaller lists of [R, G, B] pixels (red, green, blue) representing the flipped image.

from sense_hat import SenseHat

sense = SenseHat()
sense.flip_h()

---

flip_v

Flips the image on the LED matrix vertically.

Parameter	Type	Valid values	Explanation
redraw	Boolean	True False	Whether or not to redraw what is already being displayed on the LED matrix when flipped. Defaults to True

Returned type	Explanation
List	A list containing 64 smaller lists of [R, G, B] pixels (red, green, blue) representing the flipped image.

from sense_hat import SenseHat

sense = SenseHat()
sense.flip_v()

---

set_pixels

Updates the entire LED matrix based on a 64 length list of pixel values.

Parameter	Type	Valid values	Explanation
pixel_list	List	[[R, G, B] * 64]	A list containing 64 smaller lists of [R, G, B] pixels (red, green, blue). Each R-G-B element must be an integer between 0 and 255.

Returned type	Explanation
None

from sense_hat import SenseHat

sense = SenseHat()

X = [255, 0, 0]  # Red
O = [255, 255, 255]  # White

question_mark = [
O, O, O, X, X, O, O, O,
O, O, X, O, O, X, O, O,
O, O, O, O, O, X, O, O,
O, O, O, O, X, O, O, O,
O, O, O, X, O, O, O, O,
O, O, O, X, O, O, O, O,
O, O, O, O, O, O, O, O,
O, O, O, X, O, O, O, O
]

sense.set_pixels(question_mark)

---

get_pixels

Returned type	Explanation
List	A list containing 64 smaller lists of [R, G, B] pixels (red, green, blue) representing the currently displayed image.

from sense_hat import SenseHat

sense = SenseHat()
pixel_list = sense.get_pixels()

Note: You will notice that the pixel values you pass into set_pixels sometimes change when you read them back with get_pixels. This is because we specify each pixel element as 8 bit numbers (0 to 255) but when they're passed into the Linux frame buffer for the LED matrix the numbers are bit shifted down to fit into RGB 565. 5 bits for red, 6 bits for green and 5 bits for blue. The loss of binary precision when performing this conversion (3 bits lost for red, 2 for green and 3 for blue) accounts for the discrepancies you see.

The get_pixels function provides a correct representation of how the pixels end up in frame buffer memory after you've called set_pixels.

---

set_pixel

Sets an individual LED matrix pixel at the specified X-Y coordinate to the specified colour.

Parameter	Type	Valid values	Explanation
x	Integer	0 - 7	0 is on the left, 7 on the right.
y	Integer	0 - 7	0 is at the top, 7 at the bottom.
Colour can either be passed as an RGB tuple:
pixel	Tuple or List	(r, g, b)	Each element must be an integer between 0 and 255.
Or three separate values for red, green and blue:
r	Integer	0 - 255	The Red element of the pixel.
g	Integer	0 - 255	The Green element of the pixel.
b	Integer	0 - 255	The Blue element of the pixel.

Returned type	Explanation
None

from sense_hat import SenseHat

sense = SenseHat()

# examples using (x, y, r, g, b)
sense.set_pixel(0, 0, 255, 0, 0)
sense.set_pixel(0, 7, 0, 255, 0)
sense.set_pixel(7, 0, 0, 0, 255)
sense.set_pixel(7, 7, 255, 0, 255)

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

# examples using (x, y, pixel)
sense.set_pixel(0, 0, red)
sense.set_pixel(0, 0, green)
sense.set_pixel(0, 0, blue)

---

get_pixel

Parameter	Type	Valid values	Explanation
x	Integer	0 - 7	0 is on the left, 7 on the right.
y	Integer	0 - 7	0 is at the top, 7 at the bottom.

Returned type	Explanation
List	Returns a list of [R, G, B] representing the colour of an individual LED matrix pixel at the specified X-Y coordinate.

from sense_hat import SenseHat

sense = SenseHat()
top_left_pixel = sense.get_pixel(0, 0)

Note: Please read the note under get_pixels

---

load_image

Loads an image file, converts it to RGB format and displays it on the LED matrix. The image must be 8 x 8 pixels in size.

Parameter	Type	Valid values	Explanation
file_path	String	Any valid file path.	The file system path to the image file to load.
redraw	Boolean	True False	Whether or not to redraw the loaded image file on the LED matrix. Defaults to True

from sense_hat import SenseHat

sense = SenseHat()
sense.load_image("space_invader.png")

Returned type	Explanation
List	A list containing 64 smaller lists of [R, G, B] pixels (red, green, blue) representing the loaded image after RGB conversion.

from sense_hat import SenseHat

sense = SenseHat()
invader_pixels = sense.load_image("space_invader.png", redraw=False)

---

clear

Sets the entire LED matrix to a single colour, defaults to blank / off.

Parameter	Type	Valid values	Explanation
colour	Tuple or List	(r, g, b)	A tuple or list containing the RGB (red, green, blue) values of the colour. Each element must be an integer between 0 and 255. Defaults to (0, 0, 0).
Alternatively, the RGB values can be passed individually:
r	Integer	0 - 255	The Red element of the colour.
g	Integer	0 - 255	The Green element of the colour.
b	Integer	0 - 255	The Blue element of the colour.

from sense_hat import SenseHat
from time import sleep

sense = SenseHat()

red = (255, 0, 0)

sense.clear()  # no arguments defaults to off
sleep(1)
sense.clear(red)  # passing in an RGB tuple
sleep(1)
sense.clear(255, 255, 255)  # passing in r, g and b values of a colour

---

show_message

Scrolls a text message from right to left across the LED matrix and at the specified speed, in the specified colour and background colour.

Parameter	Type	Valid values	Explanation
text_string	String	Any text string.	The message to scroll.
scroll_speed	Float	Any floating point number.	The speed at which the text should scroll. This value represents the time paused for between shifting the text to the left by one column of pixels. Defaults to 0.1
text_colour	List	[R, G, B]	A list containing the R-G-B (red, green, blue) colour of the text. Each R-G-B element must be an integer between 0 and 255. Defaults to [255, 255, 255] white.
back_colour	List	[R, G, B]	A list containing the R-G-B (red, green, blue) colour of the background. Each R-G-B element must be an integer between 0 and 255. Defaults to [0, 0, 0] black / off.

Returned type	Explanation
None

from sense_hat import SenseHat

sense = SenseHat()
sense.show_message("One small step for Pi!", text_colour=[255, 0, 0])

---

show_letter

Displays a single text character on the LED matrix.

Parameter	Type	Valid values	Explanation
s	String	A text string of length 1.	The letter to show.
text_colour	List	[R, G, B]	A list containing the R-G-B (red, green, blue) colour of the letter. Each R-G-B element must be an integer between 0 and 255. Defaults to [255, 255, 255] white.
back_colour	List	[R, G, B]	A list containing the R-G-B (red, green, blue) colour of the background. Each R-G-B element must be an integer between 0 and 255. Defaults to [0, 0, 0] black / off.

Returned type	Explanation
None

import time
from sense_hat import SenseHat

sense = SenseHat()

for i in reversed(range(0,10)):
    sense.show_letter(str(i))
    time.sleep(1)

low_light

Toggles the LED matrix low light mode, useful if the Sense HAT is being used in a dark environment.

import time
from sense_hat import SenseHat

sense = SenseHat()
sense.clear(255, 255, 255)
sense.low_light = True
time.sleep(2)
sense.low_light = False

gamma

For advanced users. Most users will just need the low_light Boolean property above. The Sense HAT python API uses 8 bit (0 to 255) colours for R, G, B. When these are written to the Linux frame buffer they're bit shifted into RGB 5 6 5. The driver then converts them to RGB 5 5 5 before it passes them over to the ATTiny88 AVR for writing to the LEDs.

The gamma property allows you to specify a gamma lookup table for the final 5 bits of colour used. The lookup table is a list of 32 numbers that must be between 0 and 31. The value of the incoming 5 bit colour is used to index the lookup table and the value found at that position is then written to the LEDs.

Type	Valid values	Explanation
Tuple or List	Tuple or List of length 32 containing Integers between 0 and 31	Gamma lookup table for the final 5 bits of colour

import time
from sense_hat import SenseHat

sense = SenseHat()
sense.clear(255, 127, 0)

print(sense.gamma)
time.sleep(2)

sense.gamma = reversed(sense.gamma)
print(sense.gamma)
time.sleep(2)

sense.low_light = True
print(sense.gamma)
time.sleep(2)

sense.low_light = False

gamma_reset

A function to reset the gamma lookup table to default, ideal if you've been messing with it and want to get it back to a default state.

Returned type	Explanation
None

import time
from sense_hat import SenseHat

sense = SenseHat()
sense.clear(255, 127, 0)
time.sleep(2)
sense.gamma = [0] * 32  # Will turn the LED matrix off
time.sleep(2)
sense.gamma_reset()

---

Environmental sensors

get_humidity

Gets the percentage of relative humidity from the humidity sensor.

Returned type	Explanation
Float	The percentage of relative humidity.

from sense_hat import SenseHat

sense = SenseHat()
humidity = sense.get_humidity()
print("Humidity: %s %%rH" % humidity)

# alternatives
print(sense.humidity)

---

get_temperature

Calls get_temperature_from_humidity below.

from sense_hat import SenseHat

sense = SenseHat()
temp = sense.get_temperature()
print("Temperature: %s C" % temp)

# alternatives
print(sense.temp)
print(sense.temperature)

---

get_temperature_from_humidity

Gets the current temperature in degrees Celsius from the humidity sensor.

Returned type	Explanation
Float	The current temperature in degrees Celsius.

from sense_hat import SenseHat

sense = SenseHat()
temp = sense.get_temperature_from_humidity()
print("Temperature: %s C" % temp)

---

get_temperature_from_pressure

Gets the current temperature in degrees Celsius from the pressure sensor.

Returned type	Explanation
Float	The current temperature in degrees Celsius.

from sense_hat import SenseHat

sense = SenseHat()
temp = sense.get_temperature_from_pressure()
print("Temperature: %s C" % temp)

---

get_pressure

Gets the current pressure in Millibars from the pressure sensor.

Returned type	Explanation
Float	The current pressure in Millibars.

from sense_hat import SenseHat

sense = SenseHat()
pressure = sense.get_pressure()
print("Pressure: %s Millibars" % pressure)

# alternatives
print(sense.pressure)

---

IMU Sensor

The IMU (inertial measurement unit) sensor is a combination of three sensors, each with an x, y and z axis. For this reason it's considered to be a 9 dof (degrees of freedom) sensor.

• Gyroscope
• Accelerometer
• Magnetometer (compass)

This API allows you to use these sensors in any combination to measure orientation or as individual sensors in their own right.

set_imu_config

Enables and disables the gyroscope, accelerometer and/or magnetometer contribution to the get orientation functions below.

Parameter	Type	Valid values	Explanation
compass_enabled	Boolean	True False	Whether or not the compass should be enabled.
gyro_enabled	Boolean	True False	Whether or not the gyroscope should be enabled.
accel_enabled	Boolean	True False	Whether or not the accelerometer should be enabled.

Returned type	Explanation
None

from sense_hat import SenseHat

sense = SenseHat()
sense.set_imu_config(False, True, False)  # gyroscope only

---

get_orientation_radians

Gets the current orientation in radians using the aircraft principal axes of pitch, roll and yaw.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings pitch, roll and yaw. The values are Floats representing the angle of the axis in radians.

from sense_hat import SenseHat

sense = SenseHat()
orientation_rad = sense.get_orientation_radians()
print("p: {pitch}, r: {roll}, y: {yaw}".format(**orientation_rad))

# alternatives
print(sense.orientation_radians)

---

get_orientation_degrees

Gets the current orientation in degrees using the aircraft principal axes of pitch, roll and yaw.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings pitch, roll and yaw. The values are Floats representing the angle of the axis in degrees.

from sense_hat import SenseHat

sense = SenseHat()
orientation = sense.get_orientation_degrees()
print("p: {pitch}, r: {roll}, y: {yaw}".format(**orientation))

---

get_orientation

Calls get_orientation_degrees above.

from sense_hat import SenseHat

sense = SenseHat()
orientation = sense.get_orientation()
print("p: {pitch}, r: {roll}, y: {yaw}".format(**orientation))

# alternatives
print(sense.orientation)

---

get_compass

Calls set_imu_config to disable the gyroscope and accelerometer then gets the direction of North from the magnetometer in degrees.

Returned type	Explanation
Float	The direction of North.

from sense_hat import SenseHat

sense = SenseHat()
north = sense.get_compass()
print("North: %s" % north)

# alternatives
print(sense.compass)

---

get_compass_raw

Gets the raw x, y and z axis magnetometer data.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings x, y and z. The values are Floats representing the magnetic intensity of the axis in microteslas (µT).

from sense_hat import SenseHat

sense = SenseHat()
raw = sense.get_compass_raw()
print("x: {x}, y: {y}, z: {z}".format(**raw))

# alternatives
print(sense.compass_raw)

---

get_gyroscope

Calls set_imu_config to disable the magnetometer and accelerometer then gets the current orientation from the gyroscope only.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings pitch, roll and yaw. The values are Floats representing the angle of the axis in degrees.

from sense_hat import SenseHat

sense = SenseHat()
gyro_only = sense.get_gyroscope()
print("p: {pitch}, r: {roll}, y: {yaw}".format(**gyro_only))

# alternatives
print(sense.gyro)
print(sense.gyroscope)

---

get_gyroscope_raw

Gets the raw x, y and z axis gyroscope data.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings x, y and z. The values are Floats representing the rotational intensity of the axis in radians per second.

from sense_hat import SenseHat

sense = SenseHat()
raw = sense.get_gyroscope_raw()
print("x: {x}, y: {y}, z: {z}".format(**raw))

# alternatives
print(sense.gyro_raw)
print(sense.gyroscope_raw)

---

get_accelerometer

Calls set_imu_config to disable the magnetometer and gyroscope then gets the current orientation from the accelerometer only.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings pitch, roll and yaw. The values are Floats representing the angle of the axis in degrees.

from sense_hat import SenseHat

sense = SenseHat()
accel_only = sense.get_accelerometer()
print("p: {pitch}, r: {roll}, y: {yaw}".format(**accel_only))

# alternatives
print(sense.accel)
print(sense.accelerometer)

---

get_accelerometer_raw

Gets the raw x, y and z axis accelerometer data.

Returned type	Explanation
Dictionary	A dictionary object indexed by the strings x, y and z. The values are Floats representing the acceleration intensity of the axis in Gs.

from sense_hat import SenseHat

sense = SenseHat()
raw = sense.get_accelerometer_raw()
print("x: {x}, y: {y}, z: {z}".format(**raw))

# alternatives
print(sense.accel_raw)
print(sense.accelerometer_raw)

---

Joystick

InputEvent

A tuple describing a joystick event. Contains three named parameters:

• timestamp - The time at which the event occurred, as a fractional number of seconds (the same format as the built-in time function)

• direction - The direction the joystick was moved, as a string ("up", "down", "left", "right", "middle")

• action - The action that occurred, as a string ("pressed", "released", "held")

This tuple type is used by several joystick methods either as the return type or the type of a parameter.

---

wait_for_event

Blocks execution until a joystick event occurs, then returns an InputEvent representing the event that occurred.

from sense_hat import SenseHat
from time import sleep

sense = SenseHat()
event = sense.stick.wait_for_event()
print("The joystick was {} {}".format(event.action, event.direction))
sleep(0.1)
event = sense.stick.wait_for_event()
print("The joystick was {} {}".format(event.action, event.direction))

In the above example, if you briefly push the joystick in a single direction you should see two events output: a pressed action and a released action. The optional emptybuffer can be used to flush any pending events before waiting for new events. Try the following script to see the difference:

from sense_hat import SenseHat
from time import sleep

sense = SenseHat()
event = sense.stick.wait_for_event()
print("The joystick was {} {}".format(event.action, event.direction))
sleep(0.1)
event = sense.stick.wait_for_event(emptybuffer=True)
print("The joystick was {} {}".format(event.action, event.direction))

---

get_events

Returns a list of InputEvent tuples representing all events that have occurred since the last call to get_events or wait_for_event.

from sense_hat import SenseHat

sense = SenseHat()
while True:
    for event in sense.stick.get_events():
        print("The joystick was {} {}".format(event.action, event.direction))

---

direction_up, direction_left, direction_right, direction_down, direction_middle, direction_any

These attributes can be assigned a function which will be called whenever the joystick is pushed in the associated direction (or in any direction in the case of direction_any). The function assigned must either take no parameters or must take a single parameter which will be passed the associated InputEvent.

from sense_hat import SenseHat, ACTION_PRESSED, ACTION_HELD, ACTION_RELEASED
from signal import pause

x = 3
y = 3
sense = SenseHat()

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

def pushed_up(event):
    global y
    if event.action != ACTION_RELEASED:
        y = clamp(y - 1)

def pushed_down(event):
    global y
    if event.action != ACTION_RELEASED:
        y = clamp(y + 1)

def pushed_left(event):
    global x
    if event.action != ACTION_RELEASED:
        x = clamp(x - 1)

def pushed_right(event):
    global x
    if event.action != ACTION_RELEASED:
        x = clamp(x + 1)

def refresh():
    sense.clear()
    sense.set_pixel(x, y, 255, 255, 255)

sense.stick.direction_up = pushed_up
sense.stick.direction_down = pushed_down
sense.stick.direction_left = pushed_left
sense.stick.direction_right = pushed_right
sense.stick.direction_any = refresh
refresh()
pause()

Note that the direction_any event is always called after all other events making it an ideal hook for things like display refreshing (as in the example above).

Un autre exemple d'utilisation du joystick:

from sense_hat import SenseHat
from time import sleep
sense = SenseHat()

e = (0, 0, 0)
w = (255, 255, 255)

sense.clear()
while True:
  for event in sense.stick.get_events():
    # Check if the joystick was pressed
    if event.action == "pressed":
      
      # Check which direction
      if event.direction == "up":
        sense.show_letter("U")      # Up arrow
      elif event.direction == "down":
        sense.show_letter("D")      # Down arrow
      elif event.direction == "left": 
        sense.show_letter("L")      # Left arrow
      elif event.direction == "right":
        sense.show_letter("R")      # Right arrow
      elif event.direction == "middle":
        sense.show_letter("M")      # Enter key
      
      # Wait a while and then clear the screen
      sleep(0.5)
      sense.clear()