← Getting Started ← Home

Sense HAT API

The pi4j-drivers Sense HAT driver — the igfasouza fork used by this playground and the jar generator that publishes it.

Where does the API live?

The Sense HAT driver lives in the pi4j-drivers repository — a collection of device drivers built on top of Pi4J. The class you'll spend most of your time with is com.pi4j.drivers.hat.raspberry.SenseHat: it wraps the LED matrix, joystick, environmental sensors and the IMU behind one object.

Why a fork?

Every example in this playground pulls the driver from my igfasouza branch of pi4j-drivers. The fork carries a few extra helpers and version-detection fixes that haven't been merged upstream yet — most notably it exposes both Sense HAT v1 and v2 through the same API. The JBang scripts declare it as: 

//DEPS com.pi4j:pi4j-drivers-igfasouza:1.1.1-SNAPSHOT
//REPOS mavencentral,mavenlocal,sonatype-snapshots=https://s01.oss.sonatype.org/content/repositories/snapshots/

To build the driver locally so JBang can find it, clone the fork and install it into your local Maven repository: 

git clone -b igfasouza https://github.com/igfasouza/pi4j-drivers.git
cd pi4j-drivers
mvn install

sensehat-jar-generator

Building the driver from source works, but a lot of readers just want a ready-made jar. sensehat-jar-generator is a small companion project that packages the Sense HAT API from the igfasouza fork into a standalone jar so you can drop it into any Java project — Maven, Gradle, or a plain -cp command line — without having to build pi4j-drivers yourself.

Use it when:

  • You're integrating the Sense HAT into an existing app and don't want a SNAPSHOT dependency in your build.
  • You need to hand a colleague or student a self-contained jar.
  • You're building a distributable — an installer, a container image, a school kit.

What the API covers

  • LED matrix — setPixel, setPixels, fill, clear, showLetter, showMessage, rotation and flips.
  • Environmental sensors — humidity, pressure and two temperature readings.
  • IMU — raw accelerometer and gyroscope, plus derived orientation in degrees and radians.
  • Magnetometer — compass heading and raw magnetic field vector.
  • Joystick — polling, listener callbacks and blocking waitForEvent.
  • Colour sensor (Sense HAT v2) — clear + RGB channels.

The projects in this playground each exercise a small slice of the API — start from any one of them and read outward.

Slimming things down with sensehat-jar-generator

The pi4j-drivers-igfasouza artifact used in the JBang preamble is convenient, but it ships every driver the repository knows about — display controllers, ADCs, expanders, things you don't need if the only board you care about is the Sense HAT. As an alternative, you can grab the jar produced by sensehat-jar-generator and use that in place of the full dependency.

The public API is the same — same SenseHat class, same methods, same behaviour — so any example on this site keeps working unchanged. The difference is on disk: the generated jar contains only the classes needed for the Sense HAT, so you end up with a much smaller artifact to ship, cache or bundle into a container image.

In a Maven or JBang setup you'd point at the generated jar instead of the SNAPSHOT dependency, drop the sonatype-snapshots repository line, and everything else in your main stays identical. Same result, smaller footprint.

Links