RPiSense Tutorial¶

The main purpose of RPiSense is to set macros for the Sense HAT that can quickly demonstrate some of the features of the board. This section covers some of the commands that you can use.

Type the following into a Terminal window and observe the results:

sensehat color --bg red
sensehat scroll --message Hello World
sensehat date --bg blue --fg white

You should see that the first command displays red pixels on the LED matrix, the second has scrolling text that says “Hello World”, and the third shows the date in white lettering on a blue background. These commands will be covered below. The macro uses the argparse module, so you also have a help option:

sensehat --help

This should give you an output that looks like:

usage: sensehat [-h] [--fg FG [FG ...]] [--bg BG [BG ...]]
                [--char CHAR [CHAR ...]] [--msg MSG [MSG ...]] [--time TIME]
                [--number NUMBER] [--speed SPEED] [--dim] [--convert]
                [--scale SCALE] [--makey] [--script SCRIPT [SCRIPT ...]]
                {clear,color,letter,scroll,ip,date,time,datetime,temperature,
                 pressure,humidity,level,compass,repeat,exec}

This macro allows for quick control over the Sense HAT during demonstrations
or for the execution of scripts.

positional arguments:
  {clear,color,letter,scroll,ip,date,time,datetime,temperature,pressure,
   humidity,level,compass,repeat,exec}
                        command to run

optional arguments:
  -h, --help            show this help message and exit
  --fg FG [FG ...]      name of foreground color (can also be "random")
  --bg BG [BG ...]      name of background color (can also be "random")
  --char CHAR [CHAR ...]
                        character to display
  --msg MSG [MSG ...]   message to display
  --time TIME           duration (seconds) for display
  --number NUMBER       number of times to display
  --speed SPEED         speed of text scroll
  --dim                 force LED matrix dim
  --convert             convert to American units
  --scale SCALE         scale sensitivity
  --makey               use keyboard (e.g. Makey Makey) for input
  --script SCRIPT [SCRIPT ...]
                        specify a script to execute

Common Options¶

There are a few options that will be pertinent to several of the command that will follow, so they are summarized here.

Colors¶

[--fg <name1 name2 name3 ...>] [--bg <name4 name5 name6 ...>]

These control the colors sent to the LED matrix. The first is a foreground color, which is the color of your message. It is defaulted to “white”. The second is a background color, which is the color that message will be displayed on. It is defaulted to “black”.

Both options use the Colors module. The arguments are names of colors that have been defined in the colors.csv file. You can choose “random” or one of the names defined within this file. All other strings are considered invalid references.

You can specify more than one fg color and more than one bg color. If the length of one list is longer than the other, then the shorter list will be extended by repeating its last entry. For example:

--fg white --bg red green blue

These options will result in three different iterations: white on red, white on green, and white on blue.

--fg red green blue --bg white black

These options will also result in three different iterations: red on white, green on black, and blue on black.

Brightness¶

The LED matrix is quite bright by default. You can dim this with a simple option.

[--dim]

This option is a boolean that is defaulted to False. It is a configuration of the Sense HAT board itself, so you can use this as an option for any of the commands below.

Loops¶

Each of the colors in the list of fg and bg arguments will be shown at least once.

[--number NUMBER]

This option allows you to repeat the color cycle. It is defaulted to 1. For example:

sensehat color --fg red --number 3

This will display a messge with a foreground color of “red” three times.

sensehat color --fg red green --number 3

This will display a message with a foreground color of “red”, then with a foreground color of “green”, then “red”, then “green”, then “red”, then “green”.

You can control the amount of pause between iterations.

[--time TIME]

This option specifies the number of seconds (integer or float) to wait between iterations. It is defaulted to one second. For example:

sensehat color --fg red green --number 3 --time 2

This will display “red” for 2 seconds, “green” for 2 seconds, “red” for 2 seconds”, “green” for 2 seconds, “red” for 2 seconds, and finally “green” for 2 seconds.

It has been suggested that each color should have its own separate pause time and each loop number should have its own separate pause time. However, the pause time should be thought of as a clock that ticks according to the greatest common factor. For example, “green” will be displayed twice as long as the pauses between if you execute:

sensehat color --fg green green --number 3 --time 1

You can also display “blank” screens by using the color black for both the foreground and the background.

Commands¶

A few commands have been written simply to make the functionality of the Sense HAT accessible from a command prompt.

clear¶

Use this to quickly clear the LED matrix display. Often, you will be running a script that uses the LED matrix and you will encounter an unhandled exception or abort, especially during an indefinite loop. Rather than leaving the LED matrix in its last state, you might want to clear it. Use this command:

sensehat clear

There are no options to specify for this command.