Astro Pi / Sense HAT - Getting Started Tutorial

Edit - this post has been updated to reflect the changes made in install and sense-hat module name.

You have managed to get your hands on an Astro-Pi Sense HAT board...  Lucky you.  If you need some help getting started - read on.

Install Sense HAT / Astro-Pi software
If you haven't got a recent version of Raspbian you will need to install the Sense HAT software.

Open up a terminal and run the following commands.

sudo apt-get update
sudo apt-get install sense-hat
sudo pip-3.2 install pillow

You will need to reboot your Raspberry Pi for the changes to take effect.

Example programs
The nice people at Raspberry Pi have provided some example programs which are a great way to test if everything is working

Open a terminal, create a director, copy the Astro-Pi example's and list the contents:

mkdir ~/sensehatexamples
cp /usr/src/sense-hat/examples ~/sensehatexamples -a
cd ~/sensehatexamples

Each of the files which ends in .py is an example python program and can be run from the terminal using

sudo python []


sudo python

Run each of the example program and see what they do:

  • - loops through all the colours on the led matrix.
  • - shows a dot on the led matrix which points north
  • pygame_joysticks - shows how to use the pygame module to read the mini joystick and display the joystick direction on the led matrix
  • - shows a rainbow of colours on the led matrix
  • - shows how to rotate the led matrix and shows a question mark
  • - displays the space invader icon in the space_invader.png file on the led matrix
  • - a scrolling text message appears on the led matrix

Hello Space
Writing your first program for the Astro Pi board is really simple, there is a great Astro Pi python library that takes away most of the complex code and leaves you to have fun.

Because the Astro Pi board needs access to the GPIO pins you will need to run your programs as a 'super user' using sudo. I think the easiest way of doing this is to start the Python editor IDLE using sudo that way you can run your programs without having to do anything special.

Open IDLE as a super user by starting a terminal and typing:

sudo idle3 &

The python shell will now start, click File -> New Window to create a new program.

Import the AstroPi class and create the object:

from sense_hat import AstroPi

ap = AstroPi()

You can use the show_message() function to display a message on the LED matrix:

ap.show_message("Hello Space")

To run your program, click Run -> Run Module.

You should see hello space scroll on the LED matrix.

LED Matrix

The AstroPi class allow you to interact with the colour LED matrix using the set_pixel(x, y, red, green, blue) function. x and y are the coordinates on the led matrix starting top left 0-7. red, green, blue are the colour values 0-255.

To make the top left pixel red you would use:

ap.set_pixel(0, 0, 255, 0, 0)

To make the bottom right pixel white (all colours) you would use:

ap.set_pixel(7, 7, 255, 255, 255)

Add the code above to your program and run it.

To turn a pixel off you would set it to black (no colours):

ap.set_pixel(7, 7, 0, 0, 0)

You can clear all the pixels using:


The clear() function can also be used to set all the pixels to one colour by passing the r,g,b values in a list i.e. blue:


Reading Sensors
The Astro Pi board comes with the following sensors which you can read:

  • Orientation (yaw, pitch & roll) via an accelerometer, 3D gyroscope and magnetometer
  • Pressure
  • Humidity
  • Temperature (via the pressure and humidity sensors)
Create a new program and as before import the AstroPi class and create the object:
from sense-hat import AstroPi

ap = AstroPi()

The pressure in millibars can read using the get_pressure() function:

pressure = ap.get_pressure()

The percentage of relative humidity can be read using the get_humidity function:

humidity = ap.get_humidity()

The temperature in degrees Celsius can be read using the get_temperature() function.

temp = ap.get_temperature()

The Astro Pi boards humidity and pressure sensors can both read temperature and you can specify which one you want to use with the get_temperature_from_humidity() and get_temperature_from_pressure() functions:

temp = ap.get_temperature_from_pressure()

temp = ap.get_temperature_from_humidity()

Orientation of the Astro Pi board can be read in degrees and radians using the functions get_orientation_radians() and get_orientation_degrees(). Both functions return the 3 flight axes of yaw, pitch and roll as a python dictionary:

orientation = ap.get_orientation_degrees()

orientation = ap.get_orientation_radians()

Run the program to see the sensor values displayed.

These are just a sample of the functions available you can view the full documentation here