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
provides several different paradigms for programming such an interface:
- At its simplest, you can poll the state of the joystick with various
- You can use event-driven programming by assigning handlers to attributes
- You can also treat the joystick like an iterable and write transformations the convert events into other useful outputs.
SenseStick(max_events=100, flush_input=True, emulate=False)¶
hat = SenseHAT() for event in hat.stick: if event.pressed and not event.held: print('%s pressed!' % event.direction)
rotationattribute 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
Truecontrols 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()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).
Wait up to timeout seconds for another joystick event. If one occurs, return it as a
StickEvent, otherwise return
Attempting to call this method when callbacks are assigned to attributes like
when_leftwill trigger a
SenseStickCallbackReadwarning. 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.
Trueif the joystick is currently pressed downward.
Trueif the joystick is currently held downward.
Trueif the joystick is currently pressed inward.
Trueif the joystick is currently held inward.
Trueif the joystick is currently pressed leftward.
Trueif the joystick is currently held leftward.
Trueif the joystick is currently pressed rightward.
Trueif the joystick is currently held rightward.
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.
This property is updated by the unifying
True, treating the joystick as an iterator will always yield immediately (yielding
Noneif no event has occurred). When
False(the default), the iterator will only yield when an event has occurred.
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.
Trueif the joystick is currently pressed upward.
Trueif the joystick is currently held upward.
The function to call when the joystick is moved downward.
The function to call when the joystick is pressed in or released.
The function to call when the joystick is moved leftward.
The function to call when the joystick is moved rightward.
The function to call when the joystick is moved upward.
StickEvent(timestamp, direction, pressed, held)¶
Represents a joystick event as a
namedtuple(). The fields of the event are defined below:
datetimeobject 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
datetimeobject in local time.
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).
A bool which is
Truewhen 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.