events Package

AbsAxisScaling Module

pi3d.event.AbsAxisScaling.EVIOCGABS(axis)

class pi3d.event.AbsAxisScaling.AbsAxisScaling(stream, axis)

Bases: object

Fetches and implements the EV_ABS axis scaling.

The constructor fetches the scaling values from the given stream for the given axis using an ioctl.

There is a scale method, which scales a given value to the range -1..+1.

Fetch the scale values for this stream and fill in the instance variables accordingly.

scale(value)

scales the given value into the range -1..+1

Constants Module

Event Module

pi3d.event.Event.key_to_code(key)

pi3d.event.Event.code_to_key(code)

class pi3d.event.Event.InputEvents(keyboardHandler=None, mouseHandler=None, joystickHandler=None, synHandler=None, unhandledHandler=None, wantKeyboard=True, wantMouse=True, wantJoystick=True)

Bases: object

Encapsulates the entire InputEvents subsystem.

This is generally all you need to import. For efficiency reasons you may want to make use of CodeOf[ ], but everything else is hidden behind this class.

On instantiation, we open all devices that are keyboards, mice or joysticks. That means we might have two of one sort of another, and that might be a problem, but it would be rather rare.

There are several ABS (joystick, touch) events that we do not handle, specifically THROTTLE, RUDDER, WHEEL, GAS, BRAKE, HAT1, HAT2, HAT3, PRESSURE, DISTANCE, TILT, TOOL_WIDTH. Implementing these is left as an exercise for the interested reader. Similarly, we make no attempt to handle multi-touch.

Handlers can be supplied, in which case they are called for each event, but it isn’t necessary; API exists for all the events.

The handler signatures are:

def mouse_handler_func(sourceType, SourceIndex, x, y, v, h) def joystick_handler_func(sourceType, SourceIndex, x1, y1, z1, x2, y2, z2, hatx, haty) def key_handler_func(sourceType, SourceIndex, key, value) def syn_handler_func(sourceType, SourceIndex, code, value) def unhandled_handler_func(event)

where:

sourceType:

the device type string (keyboard, mouse, joystick),

sourceIndex:

an incrementing number for each device of that type, starting at zero, and event is an EventStruct object.

key:

the key code, not its ASCII value or anything simple.

Use key_to_code() to convert from the name of a key to its code, and code_to_key() to convert a code to a name.

The keys are listed in pi3d.event.Constants.py or /usr/include/linux/input.h Note that the key names refer to a US keyboard.

do_input_events()

Handle all events that have been triggered since the last call.

key_state(key)

Returns the state of the given key.

The returned value will be 0 for key-up, or 1 for key-down. This method returns a key-held(2) as 1 to aid in using the returned value as a movement distance.

This function accepts either the key code or the string name of the key. It would be more efficient to look-up and store the code of the key with KEY_CODE[ ], rather than using the string every time. (Which involves a dict look-up keyed with a string for every key_state call, every time around the loop.)

Gamepad keys are: Select = BTN_BASE3, Start = BTN_BASE4 L1 = BTN_TOP R1 = BTN_BASE L2 = BTN_PINKIE R2 = BTN_BASE2 The action buttons are:

BTN_THUMB

BTN_TRIGGER BTN_TOP

BTN_THUMB2

Analogue Left Button = BTN_BASE5 Analogue Right Button = BTN_BASE6

Some of those may clash with extended mouse buttons, so if you are using both at once, you’ll see some overlap.

The direction pad is hat0 (see get_hat)

clear_key(key)

Clears the state of the given key.

Emulates a key-up, but does not call any handlers.

get_keys()

get_joystick(index=0)

Returns the x,y coordinates for a joystick or left gamepad analogue stick.

index is the device index and defaults to 0 – the first joystick device

The values are returned as a tuple. All values are -1.0 to +1.0 with 0.0 being centred.

get_joystick3d(index=0)

Returns the x,y,z coordinates for a joystick or left gamepad analogue stick

index is the device index and defaults to 0 – the first joystick device

The values are returned as a tuple. All values are -1.0 to +1.0 with 0.0 being centred.

get_joystickR(index=0)

Returns the x,y coordinates for a right gamepad analogue stick.

index is the device index and defaults to 0 – the first joystick device

The values are returned as a tuple. For some odd reason, the gamepad returns values in the Z axes of both joysticks, with y being the first.

All values are -1.0 to +1.0 with 0.0 being centred.

get_joystickB3d(index=0)

Returns the x,y,z coordinates for a 2nd joystick control

index is the device index and defaults to 0 – the first joystick device

The values are returned as a tuple. All values are -1.0 to +1.0 with 0.0 being centred.

get_hat(index=0)

Returns the x,y coordinates for a joystick hat or gamepad direction pad

index is the device index and defaults to 0 – the first joystick device

The values are returned as a tuple. All values are -1.0 to +1.0 with 0.0 being centred.

get_mouse_movement(index=0)

Returns the accumulated mouse movements since the last call.

index is the device index and defaults to 0 – the first mouse device

The returned value is a tuple: (X, Y, WHEEL, H-WHEEL)

grab_by_type(deviceType, deviceIndex=None, grab=True)

Grab (or release) exclusive access to all devices of the given type.

The devices are grabbed if grab is True and released if grab is False. If the deviceIndex is given, only that device is grabbed, otherwise all the devices of the same type are grabbed.

All devices are grabbed to begin with. We might want to ungrab the keyboard for example to use it for text entry. While not grabbed, all key-down and key-hold events are filtered out, but that only works if the events are received and handled while the keyboard is still grabbed, and the loop may not have been running. So if we are grabbing a device, we call the handling loop first, so there are no outstanding events.

Note that the filtering means that if you trigger the ungrab from a key-down event, the corrosponding key-up will be actioned before the subsequent grab, and you wont end up looping continuously. However it also means that you will see key-up events for all the text entry. Since it only affects a user-supplied key-handler, and key-ups do not usually trigger actions anyway, this is not likely to be a problem. If it is, you will have to filter them yourself.

release()

Ungrabs all streams and closes all files.

Only do this when you’re finished with this object. You can’t use it again.

EventHandler Module

class pi3d.event.EventHandler.EventHandler(keyHandler=None, relHandler=None, absHandler=None, synHandler=None)

Bases: object

A class to handle events.

Four types of events are handled: REL (mouse movement), KEY (keybaord keys and other device buttons), ABS (joysticks and gamepad analogue sticks) and SYN (delimits simultaneous events such as mouse movements)

event(event)

Handles the given event.

If the event is passed to a handler or otherwise handled then returns None, else returns the event. All handlers are optional.

All key events are handled by putting them in the self.buttons dict, and optionally by calling the supplied handler.

REL X, Y and wheel V and H events are all accumulated internally and also optionally passed to the supplied handler. All these events are handled.

ABS X, Y, Z, RX, RY, RZ, Hat0X, Hat0Y are all accumulated internally and also optionally passed to the supplied handler. Other ABS events are not handled.

All SYN events are passed to the supplied handler.

There are several ABS events that we do not handle. In particular: THROTTLE, RUDDER, WHEEL, GAS, BRAKE, HAT1, HAT2, HAT3, PRESSURE, DISTANCE, TILT, TOOL_WIDTH. Implementing these is left as an exercise for the interested reader.

Likewise, since one handler is handling all events for all devices, we may get the situation where two devices return the same button. The only way to handle that would seem to be to have a key dict for every device, which seems needlessly profligate for a situation that may never arise.

get_rel_movement(index)

Returns the accumulated REL (mouse or other relative device) movements since the last call.

The returned value is a tuple: (X, Y, WHEEL, H-WHEEL, DIAL)

key_state(buttonCode)

Returns the last event value for the given key code.

Key names can be converted to key codes using codeOf[str]. If the key is pressed the returned value will be 1 (pressed) or 2 (held). If the key is not pressed, the returned value will be 0.

clear_key(buttonCode)

Clears the event value for the given key code.

Key names can be converted to key codes using codeOf[str]. This emulates a key-up but does not generate any events.

get_keys()

Returns the first of whichever keys have been pressed.

Key names can be converted to key codes using codeOf[str]. This emulates a key-up but does not generate any events.

EventStream Module

class pi3d.event.EventStream.EventStream(index, deviceType)

Bases: object

encapsulates the event* file handling

Each device is represented by a file in /dev/input called eventN, where N is a small number. (Actually, a keybaord is/can be represented by two such files.) Instances of this class open one of these files and provide means to read events from them.

Class methods also exist to read from multiple files simultaneously, and also to grab and ungrab all instances of a given type.

Opens the given /dev/input/event file and grabs it.

Also adds it to a class-global list of all existing streams. The index is a tuple: (deviceIndex, eventIndex). The deviceIndex can be used subsequently for differentiating multiple devices of the same type.

AllStreams = []

axisX = 0

axisY = 1

axisZ = 2

axisRX = 3

axisRY = 4

axisRZ = 5

axisHat0X = 6

axisHat0Y = 7

axisHat1X = 8

axisHat1Y = 9

axisHat2X = 10

axisHat2Y = 11

axisHat3X = 12

axisHat3Y = 13

axisThrottle = 14

axisRudder = 15

axisWheel = 16

axisGas = 17

axisBrake = 18

axisPressure = 19

axisDistance = 20

axisTiltX = 21

axisTiltY = 22

axisToolWidth = 23

numAxes = 24

axisToEvent = [0, 1, 2, 3, 4, 5, 16, 17, 18, 19, 20, 21, 22, 23, 6, 7, 8, 9, 10, 24, 25, 26, 27, 28]

acquire_abs_info()

Acquires the axis limits for all the ABS axes.

This will only be called for joystick-type devices.

scale(axis, value)

Scale the given value according to the given axis.

acquire_abs_info must have been previously called to acquire the data to do the scaling.

grab(grab=True)

Grab (or release) exclusive access to all devices of the given type.

The devices are grabbed if grab is True and released if grab is False.

All devices are grabbed to begin with. We might want to ungrab the keyboard for example to use it for text entry. While not grabbed, all key-down and key-hold events are filtered out.

next()

Returns the next waiting event.

If no event is waiting, returns None.

classmethod grab_by_type(deviceType, deviceIndex=None, grab=True, streams=None)

Grabs all streams of the given type.

classmethod allNext(streams=None)

A generator fuction returning all waiting events in the given streams

If the streams parameter is not given, then all streams are selected.

release()

Ungrabs the file and closes it.

EventStruct Module

class pi3d.event.EventStruct.EventStruct(stream, time=None, eventType=None, eventCode=None, eventValue=None)

Bases: object

A single event from the linux input event system.

Events are tuples: (Time, Type, Code, Value) In addition we remember the stream it came from.

Externally, only the unhandled event handler gets passed the whole event, but the SYN handler gets the code and value. (Also the keyboard handler, but those are renamed to key and value.)

This class is responsible for converting the Linux input event structure into one of these objects and back again.

Create a new event.

Generally all but the stream parameter are left out; we will want to populate the object from a Linux input event using decode.

encode()

Encode this event into a Linux input event structure.

The output is packed into a string. It is unlikely that this function will be required, but it might as well be here.

decode(s)

Decode a Linux input event into the fields of this object.

Arguments:

s

A binary structure packed into a string.

FindDevices Module

pi3d.event.FindDevices.test_bit(nlst, b)

pi3d.event.FindDevices.EvToStr(events)

class pi3d.event.FindDevices.DeviceCapabilities(firstLine, filehandle)

Bases: object

doesProduce(eventType, eventCode)

pi3d.event.FindDevices.get_devices(filename='/proc/bus/input/devices')

pi3d.event.FindDevices.find_devices(identifier, butNot=[])

finds the event indecies of all devices that have the given identifier.

The identifier is a string on the Handlers line of /proc/bus/input/devices. Keyboards use “kbd”, mice use “mouse” and joysticks (and gamepads) use “js”.

Returns a list of integer indexes N, where /dev/input/eventN is the event stream for each device.

If except is given it holds a list of tuples which the returned values should not match.

All devices of each type are returned; if you have two mice, they will both be used.

Format Module

ioctl Module

Keys Module