9. API - The Sense HAT

The pisense module is the main namespace for the pisense package; it imports (and exposes) all publically accessible classes, functions, and constants from all the modules beneath it for convenience. It also defines the top-level SenseHAT class.

9.1. SenseHAT

class pisense.SenseHAT(settings='/etc/RTIMULib.ini', *, fps=15, easing=<function linear>, max_events=100, flush_input=True, emulate=None)[source]

An instance of this class represents the Sense HAT as a whole. It provides attributes for objects that represent each component of the HAT, including:

  • stick for the joystick
  • screen for the display
  • environ for the environmental sensors
  • imu for the Inertial Measurement Unit (IMU)

The settings parameter can be used to point to alternate settings files but it is strongly recommended you leave this at the default as this can affect the calibration of the IMU. Other keyword arguments are used in the initialization of the subordinate objects; see the documentation for their classes for further information.

One particular keyword argument, emulate, takes its default from an environment variable: PISENSE_EMULATE. If set, this must be an integer number, typically 0 or 1 (0 is assumed if the variable is not set). This argument indicates whether the instance should attach to the “real” Sense HAT or the desktop Sense HAT emulator. The environment variable is particularly useful as it means scripts can be tested against the emulator without alteration. For example:

$ PISENSE_EMULATE=1 python examples/rainbow.py


Your script should not attempt to create more than one instance of this class (given it represents a single piece of hardware). If you attempt to do so a SenseHATReinit warning will be raised and the existing instance will be returned.


Call the close() method to close the Sense HAT interface and free up any background resources. The method is idempotent (you can call it multiple times without error) and after it is called, any operations on the Sense HAT may return an error (but are not guaranteed to do so).


Returns a SenseEnviron object representing the environmental sensors on the Sense HAT.


Returns a SenseIMU object representing the Inertial Measurement Unit (IMU) on the Sense HAT.


Gets or sets the rotation (around the Z-axis) of the Sense HAT. When querying this attribute, only the screen’s rotation is queried. When set, the attribute affects the screen, joystick, and IMU.


Returns a SenseScreen object representing the Sense HAT’s display.


Returns a SenseSettings object representing the Sense HAT’s configuration settings.


Returns a SenseStick object representing the Sense HAT’s joystick.

9.2. Warnings

exception pisense.SenseHATReinit[source]

Warning raised when the SenseHAT class is initialized twice (or more)