Proposal: Python-style high-level API for Raspberry Pi Sense HAT

[igfasouza]

Hi everyone,

I’ve been working with the Raspberry Pi Sense HAT using Pi4J, and I noticed that while the current driver implementation is solid and modular, it differs quite a bit from the official Python Sense HAT API in terms of usability and developer experience.

In Python, the API is very high-level and convenient:

sense.show_message("Hello world!")
sense.set_pixel(0, 0, 255, 0, 0)
humidity = sense.get_humidity()

With Pi4J, this requires interacting with multiple lower-level components (display, sensors, joystick, etc.). That’s powerful, but less approachable—especially for users coming from Python.

Proposal

Introduce an optional high-level compatibility layer that mirrors the Python API, while keeping the current low-level drivers unchanged.

Example usage in Java:

var sense = SenseHatCompat.create(pi4j);

sense.showMessage("Hello world!");
sense.setPixel(0, 0, 255, 0, 0);

double humidity = sense.getHumidity();
double pressure = sense.getPressure();

Proposed Class Structure

The idea is to implement this as a thin wrapper over the existing SenseHat driver:

SenseHatCompat
 ├── SenseHatDisplay
 ├── SenseHatEnvironment
 ├── SenseHatJoystick   (future)
 └── SenseHatColour     (future)

Main entry point

public final class SenseHatCompat {

    public static SenseHatCompat create(Context pi4j);

    // Display
    void setPixel(int x, int y, int r, int g, int b);
    int[] getPixel(int x, int y);
    void clear();
    void showMessage(String text);

    // Environment
    double getHumidity();
    double getPressure();
    double getTemperature();
}

Display wrapper

final class SenseHatDisplay {

    void setPixel(int x, int y, int r, int g, int b);
    int[] getPixel(int x, int y);

    void clear();
    void clear(int r, int g, int b);

    void showMessage(String text);
}

Environment wrapper

final class SenseHatEnvironment {

    double getHumidity();
    double getPressure();

    double getTemperature();
    double getTemperatureFromHumidity();
    double getTemperatureFromPressure();
}

Goals

• Improve developer experience
• Reduce friction for Python users migrating to Java
• Provide a simple API for common use cases
• Keep full backward compatibility

Scope (initial PR)

Start small and incremental:

1. LED matrix (setPixel, clear, showMessage)
2. Environmental sensors

Then expand to:

1. Joystick events (Python-style)
2. Colour sensor
3. IMU (later, more complex)

Questions

Would this fit within the goals of Pi4J?
Should this live inside pi4j-drivers or as a separate module?
Any preference on naming (e.g. SenseHatCompat vs SenseHatApi)?
Would you prefer starting with a smaller PR (LED only)?

I already have a working draft implementation and can open a PR if this direction makes sense 👍

Thanks!

[FDelporte]

@taartspi @stefanhaustein I think this is a right fit for the pi4j-drivers project, correct?

[eitch]

I agree too

[taartspi]

Yes. I read this over yesterday and was contemplating example versus driver. I think this goes into the driver repo (not sure if it is a new directory structure) and a usage example in example-devices/example

[stefanhaustein]

I think these could also just be convenience methods added to the existing SenseHat class?

• I'd prefer if we'd stick to using a single int for rgb for consistency though...

• Also, let's not add various "middle ground" things.... Let's have top level convenience or the existing sensor / display framework, let's not add a competing sense-hat only framwork...

• We should probably get the release out of the door before expanding (beyond adding convenience methods to existing drivers)

[taartspi]

My response is lost in the github process of moving text to email. It amounted to agreeing drivers and then demonstrate usage in examples

…

On Mon, May 11, 2026 at 8:39 AM Stefan Haustein ***@***.***> wrote: I think these could also just be convenience methods added to the existing SenseHat class? — Reply to this email directly, view it on GitHub <#633 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AK5A324LUS3U5OCSRDPYHNT42HJYXAVCNFSM6AAAAACYYAOTTCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTMOBXHE3DQMQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[igfasouza]

Yes, keeping everything in the same class makes sense.

I added a lot of stuffs:
https://github.com/igfasouza/pi4j-drivers/blob/feature/sensehat-convenience-methods/src/main/java/com/pi4j/drivers/hat/raspberry/SenseHat.java

is only one class. but the PR will be a litle big

The Gain ones it will requere a change in Class Tcs3400Driver

• public int getColorGain() {
• public void setColorGain(int gain) {
• public int getIntegrationCycles() {
• public void setIntegrationCycles(int cycles) {

I can leave this for a second PR.
thoughts?

And I need think about tests.

[stefanhaustein]

Thanks!

I am all for convenience, but let's not re-implement stuff that's already in drivers.

For instance, why re-implement glyphs instead of using the BitmapFont? Ideally, looking at the convenience functions would teach users how to use the underlying APIs -- and ideally be as consistent with them as possible (rather than exactly matching python)?

Also, I'd really prefer if we could do this incrementally, e.g. start with convenience calls for temperature, humidity etc. and take it from there by topic group?

PS: Examples for using nearly everything in drivers can be found here: https://github.com/Pi4J/pi4j-example-devices/tree/master/src/main/java/com/pi4j/examples -- I'd really strongly recommend running the sense hat demo if you haven't yet.

[igfasouza]

Thank you very much for the validation.

Yes, I already refactored it using everything from BitmapFont instead of reinventing the wheel.

I’ll also review the other parts to see if there is any additional duplicated logic.

I’ll test everything properly, and yes, I can split the PR into smaller parts:

Display
Sensors
Joystick

thanks

[stefanhaustein]

Maybe we should also take a step back and try to align on what we want here, so we have a better foundation for reviews:

• Providing convenience functions avoiding some indirection of the drivers API

  • We probably want to align this with the drivers API, so code can be re-used if the user needs to "upgrade" to the full driver API, it doesn't need to be re-written. For instance, the color parameter for setting individual pixels should match the rgb integer format
  • It should be limited to most essential functionality -- or functionality that's relatively specific to the device

• Re-implement an existing Python API in Java, matching the original as closely as possible

  • I am not opposed to doing this, although I'd prefer the former
  • It's probably something that should live in examples or in a dedicated repository

Of course we could also do both

[igfasouza]

Hi @stefanhaustein

Yes, we don't need reproduce Python, we want just some similar methods.

My suggestion: Implementation priority:

1. Add framebuffer access methods to GraphicsDisplay (copyDisplayBuffer() and setDisplayBuffer()) so SenseHat convenience methods can operate directly on the display buffer without maintaining duplicated internal state.
2. clear, setPixel, setPixels, showLetter, showMessage
3. getHumidity, getPressure, getTemperature
4. getAccelerometerRaw, getGyroscopeRaw, getCompassRaw
5. flipH, flipV, rotation support

I can split each number in one separated PR.
1 only change GraphicsDisplay class
2 to 5 only changes SenseHat class

[stefanhaustein]

Why not start with (3) -- this seems to be straightforward and super agreeable, establishing some work process.

Why / how would (1) be needed for any of the rest? I am not against adding framebuffer read access (if it's not there already), but it probably should be in line with existing framebuffer write access....

I understand why one would want rotation support, but it's already there: When attaching a device driver to a framebuffer (=GraphicsDisplay), it supports a rotation parameter. It should be straightforward to add flip support there with the infrastructure available for roation support (basically breaking down rotation into x/y swap and x/y copy direction a an earlier stage)

[stefanhaustein]

PS: I am adding framebuffer read access in Pi4J/pi4j-drivers#122

[igfasouza]

Perhaps...

Instead of implementing all scrolling logic directly inside SenseHat, I think it would be beneficial to introduce a reusable MessageScroller that works with any GraphicsDisplay.

The SenseHat API would remain simple, while the scrolling implementation becomes reusable by other drivers and applications.

Motivation

Currently, showMessage() is a high-level feature rather than a hardware-specific capability.

The scrolling logic includes:

• text rendering
• frame generation
• scrolling animation
• timing
• direction
• optional looping
• cancellation

None of this is really specific to the Sense HAT itself. Any GraphicsDisplay could benefit from the same functionality.

Proposed API

MessageScroller.on(display)
    .foreground(Argb32.RED)
    .background(Argb32.BLACK)
    .delay(Duration.ofMillis(75))
    .direction(ScrollDirection.RIGHT_TO_LEFT)
    .scroll("Hello");

The SenseHat would simply expose a convenience method:

senseHat.showMessage("Hello");

which internally delegates to:

MessageScroller.on(getDisplay())
    .scroll("Hello");

Or alternatively expose the scroller directly:

MessageScroller scroller = senseHat.messageScroller();

scroller
    .foreground(Argb32.GREEN)
    .loop(true)
    .start("Pi4J");

Suggested Package

com.pi4j.drivers.display.graphics.text

Containing:

• MessageScroller
• ScrollDirection

Features

The class could support:

• configurable font
• foreground/background colors
• configurable delay
• configurable scroll speed (pixels per frame)
• left-to-right scrolling
• right-to-left scrolling
• looping
• synchronous execution
• asynchronous execution
• cancellation (stop())

Example:

MessageScroller.on(display)
    .foreground(Argb32.YELLOW)
    .background(Argb32.BLACK)
    .direction(ScrollDirection.LEFT_TO_RIGHT)
    .delay(Duration.ofMillis(50))
    .loop(true)
    .start("Hello");

Later:

scroller.stop();

Synchronous vs Asynchronous API

I would suggest supporting both:

Blocking:

scroller.scroll("Hello");

And non-blocking:

scroller.start("Hello");

// ...

scroller.stop();

This keeps the API flexible while remaining easy to use.

Benefits

• Keeps SenseHat focused on being a hardware abstraction
• Makes text scrolling reusable across all GraphicsDisplay implementations
• Avoids duplicating animation logic in multiple drivers
• Makes future features (different fonts, animation effects, vertical scrolling, etc.) easier to implement
• Provides a richer API (stop(), looping, scrolling direction) without increasing the complexity of SenseHat

Possible Future Extensions

Once the scrolling logic is separated, it becomes straightforward to add features such as:

• center alignment
• bounce animation
• vertical scrolling
• custom easing/animation
• frame listeners
• text effects (blink, fade, etc.)

without adding more responsibilities to the SenseHat class itself.

[stefanhaustein]

I really like it.

Some remarks:

• On bigger displays, we'll need a "frame" it governs
• If we support "blink" or "fade", this might make even sense without scrolling (this is mostly about the name)
• Scrolling might make sense on character displays, too -- but the api might be different. Still might make sense to consider an interface for overlap?
• I am not sure I like the fluent style as it always makes the getter / setter distinction a bit awkward(?)
• As the thing will remain mutable (I suppose -- changing text or color while running looks like a reasonable feature), I don't think we need a builder
• "on" seems arbitrary for construction, it looks like another setter. Perhaps explicitly create(display)? Or even just a regular ctor?

[igfasouza]

Thanks, these are good points.

I folow more or less this ...

• use a more general name such as TextAnimator rather than MessageScroller
• support a configurable frame/viewport
• use regular setters instead of a fluent builder style
• use a regular constructor or create(display) instead of on(display)
• keep SenseHat.showMessage(...) as a convenience wrapper
• keep the first implementation focused on scrolling text, without over-abstracting too early

I just added a Draft PR.

Perhaps instead of "TextAnimationDirection.java" it could be more like "TextScrollDireaction.java" as if we add fade and blink in a future the name could be a problem ...