12. API - Joystick¶

The joystick on the Sense HAT is an excellent tool for providing a user interface on Pis without an attached keyboard. The SenseStick class provides several different paradigms for programming such an interface:

At its simplest, you can poll the state of the joystick with various attributes like SenseStick.up.
You can use event-driven programming by assigning handlers to attributes like SenseStick.when_up.
You can also treat the joystick like an iterable and write transformations the convert events into other useful outputs.

12.1. SenseStick¶

class pisense.SenseStick(max_events=100, flush_input=True, emulate=False)[source]¶

The SenseStick class represents the joystick on the Sense HAT. Users can either instantiate this class themselves, or can access an instance from SenseHAT.stick.

The read() method can be called to obtain StickEvent instances, or the instance can be treated as an iterator in which case events will be yielded as they come in:

hat = SenseHAT()
for event in hat.stick:
    if event.pressed and not event.held:
        print('%s pressed!' % event.direction)

Alternatively, handler functions can be assigned to the attributes when_up, when_down, when_left, when_right, when_enter. The assigned functions will be called when any matching event occurs.

Finally, the attributes up, down, left, right, and attr:enter can be polled to determine the current state of the joystick.

The rotation attribute can be modified to alter the orientation of events, and the aforementioned attributes.

The max_events parameter controls the size of the internal queue used to buffer joystick events. This defaults to 100 which should be more than sufficient to ensure events are not lost. The flush_input parameter, which defaults to True controls whether, when the instance is closed, it attempts to flush the stdin of the owning terminal. This is useful as the joystick also acts as a keyboard. On the command line, this can mean that joystick movements (buffered during a script’s execution) can inadvertently execute historical commands (e.g. Up a few times followed by Enter).

Finally, if the emulate parameter is True, the instance will connect to the joystick in the desktop Sense HAT emulator instead of the “real” Sense HAT joystick.

close()[source]¶: Call the close() method to close the joystick 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 joystick may return an error (but are not guaranteed to do so).

read(timeout=None)[source]¶: Wait up to timeout seconds for another joystick event. If one occurs, return it as a StickEvent, otherwise return None.

Note

Attempting to call this method when callbacks are assigned to attributes like when_left will trigger a SenseStickCallbackRead warning. This is because using the callback mechanism causes a background thread to continually read joystick events (removing them from the queue that read() accesses). Mixing these programming styles can result in missing events.

down¶: Returns True if the joystick is currently pressed downward.

down_held¶: Returns True if the joystick is currently held downward.

enter¶: Returns True if the joystick is currently pressed inward.

enter_held¶: Returns True if the joystick is currently held inward.

left¶: Returns True if the joystick is currently pressed leftward.

left_held¶: Returns True if the joystick is currently held leftward.

right¶: Returns True if the joystick is currently pressed rightward.

right_held¶: Returns True if the joystick is currently held rightward.

rotation¶

Specifies the rotation (really, the orientation) of the joystick as a multiple of 90 degrees. When rotation is 0 (the default), “up” is toward the GPIO pins:

When rotation is 90, “up” is towards the LEDs, and so on:

The other two rotations are trivial to derive from this.

Note

This property is updated by the unifying SenseHAT.rotation attribute.

stream¶: When True, treating the joystick as an iterator will always yield immediately (yielding None if no event has occurred). When False (the default), the iterator will only yield when an event has occurred.

Note

This property can be set while an iterator is active, but if the current value is False, the iterator will wait indefinitely for the next event before it will start returning None. It is better to set this property prior to obtaining the iterator.

up¶: Returns True if the joystick is currently pressed upward.

up_held¶: Returns True if the joystick is currently held upward.

when_down¶: The function to call when the joystick is moved downward.

when_enter¶: The function to call when the joystick is pressed in or released.

when_left¶: The function to call when the joystick is moved leftward.

when_right¶: The function to call when the joystick is moved rightward.

when_up¶: The function to call when the joystick is moved upward.

12.2. StickEvent¶

class pisense.StickEvent(timestamp, direction, pressed, held)[source]¶

Represents a joystick event as a namedtuple(). The fields of the event are defined below:

timestamp¶: A datetime object specifying when the event took place. This timestamp is derived from the kernel event so it should be accurate even when callbacks have taken time reacting to events. The timestamp is a naive datetime object in local time.

direction¶: A string indicating which direction the event pertains to. Can be one of “up”, “down”, “leftʺ, “right”, or “enter” (the last event refers to the joystick being pressed inward).

pressed¶: A bool which is True when the event indicates that the joystick is being pressed or held in the specified direction. When this is False, the event indicates that the joystick has been released from the specified direction.

held¶: A bool which is True when the event indicates that the joystick direction is currently held down (when pressed is also True) or that the direction was previously held down (when pressed is False buut held is still True).

12.3. Warnings¶

exception pisense.SenseStickBufferFull[source]¶: Warning raised when the joystick’s event buffer fills

exception pisense.SenseStickCallbackRead[source]¶: Warning raised when SenseStick.read() is called while callbacks are active