Tuesday, 12 May 2015

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 [name_of_example.py]
sudo python rainbow.py

Run each of the example program and see what they do:
  • colour_cycle.py - loops through all the colours on the led matrix.
  • compass.py - 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
  • rainbow.py - shows a rainbow of colours on the led matrix
  • rotation.py - shows how to rotate the led matrix and shows a question mark
  • space_invader.py - displays the space invader icon in the space_invader.png file on the led matrix
  • text_scroll.py - 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 http://pythonhosted.org/sense-hat/.


  1. Is there any way to buy one of these? They look awesome!

    1. The astro pi board (aka raspberry pi sense hat) will be available for purchase 'soon' see https://www.raspberrypi.org/forums/viewtopic.php?f=104&t=108520&sid=4ef10a2b5f77ba4fa5722d1d8f44f876

  2. Why is rpi-update called early on in air-pi-install.sh?
    Later on the kernel, modules, etc. are overwritten by the extraction of kinstall.tar.gz, negating any changes by rpi-update.
    My guess is the space qualification is only valid for the kernel, etc. in kinstall.tar.gz.
    Just curious.

    1. No idea, but its probably worth a post in the astro pi sub-forum https://www.raspberrypi.org/forums/viewforum.php?f=104&sid=4df0a062e5d56cc44ea5034510134f4e

  3. Hi, great set of examples. One error: under Reading Sensors you have this import line:
    from sense-hat import AstroPi

    As of 2016-01-06, my Pi wanted it to read with an underscore:
    from sense_hat import AstroPi


  4. I have the Sense Hat mounted on my Raspberry Pi 2 and it's showing a rainbow, unfortunately I'm getting a stream of error messages when I run > sudo pip-3.2 install pillow (I've tried rebooting):
    warning: no previously-included files found matching '.editorconfig'
    ValueError: jpeg is required unless explicitly disabled using --disable-jpeg, aborting
    Command /usr/bin/python3.2 -c "import setuptools;__file__='/home/pi/build/pillow/setup.py';exec(compile(open(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --single-version-externally-managed --record /tmp/pip-isnnsl-record/install-record.txt failed with error code 1 in /home/pi/build/pillow
    Storing complete log in /root/.pip/pip.log

    Has anyone else seen this?

    I've also tried running the Python examples but again get error messages:

    Command /usr/bin/python3.2 -c "import setuptools;__file__='/home/pi/build/pillow/setup.py';exec(compile(open(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --single-version-externally-managed --record /tmp/pip-isnnsl-record/install-record.txt failed with error code 1 in /home/pi/build/pillow
    Storing complete log in /root/.pip/pip.log

    1. Just installed after doing the following first for Jpeg modules:

      sudo apt-get install libjpeg-dev libfreetype6 libfreetype6-dev zlib1g-dev

    2. I got this until I started using a more powerful power supply (4amp)

    3. I got this until I started using a more powerful power supply (4amp)

  5. This comment has been removed by the author.

  6. HELP! When I enter: sense = SenseHat() I get an error! It says "Cannot detect RPi-Sense FB Device" Also it says "/usr/lib/python3/dist-packages/sense_hat/sense_hat.py line 36" also "cannot detect device" I ran: i2cdetect -y 1 and got, at 1b at UU, then 1c, 46, 5c, 5f, 6a

    1. I found this 'temporary' fix. It's a timing issue with
      jessie-2015-09-24. My SenseHat now excepts:
      sense = SenseHat() Yaaaaaa!

    2. Found the fix here: https://gist.github.com/Gadgetoid/57084ec5817142a118ac There's a timing issue in jessie-2015-09-24 Issuing an i2cdetect -y 1 now returns: 1c, UU at 46, 5c, 5f, 6a (notice the difference from above msg?)

  7. Hey,

    thanks for the great overview.

    I had a problem with the pip installer.
    I made update/upgrade, installed sense_hat and run into an error while installing pillow.


    ValueError: jpeg is required unless explicitly disabled using --disable-jpeg, aborting

    Installation of "libjpeg-dev" was the clue

    Reg Chris