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 fromSenseHAT.stick
.The
read()
method can be called to obtainStickEvent
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 returnNone
.Note
Attempting to call this method when callbacks are assigned to attributes like
when_left
will trigger aSenseStickCallbackRead
warning. This is because using the callback mechanism causes a background thread to continually read joystick events (removing them from the queue thatread()
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 (yieldingNone
if no event has occurred). WhenFalse
(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 returningNone
. 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 naivedatetime
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 isFalse
, the event indicates that the joystick has been released from the specified direction.
-