Provided by: python-evdev-doc_0.7.0+dfsg-2_all bug

NAME

       python-evdev - python-evdev Documentation

       This  package  provides  bindings to the generic input event interface in Linux. The evdev
       interface serves the purpose of  passing  events  generated  in  the  kernel  directly  to
       userspace through character devices that are typically located in /dev/input/.

       This  package  also  comes  with bindings to uinput, the userspace input subsystem. Uinput
       allows userspace programs to create and  handle  input  devices  that  can  inject  events
       directly into the input subsystem.

       In  other words, python-evdev allows you to read and write input events on Linux. An event
       can be a key or button press, a mouse movement or a tap on a touchscreen.

FROM A BINARY PACKAGE

       Python-evdev has been packaged for the following GNU/Linux distributions:

       Consult  the  relevant  documentation  of  your  OS  package  manager   for   installation
       instructions.

FROM SOURCE

       The  latest  stable  version of python-evdev can be installed from pypi, provided that you
       have gcc/clang, pip and the Python and Linux development headers installed on your system.
       Installing  them  is  distribution  specific  and  typically falls in one of the following
       categories:

       On a Debian compatible OS:

          $ apt-get install python-dev python-pip gcc
          $ apt-get install linux-headers-$(uname -r)

       On a Redhat compatible OS:

          $ yum install python-devel python-pip gcc
          $ yum install kernel-headers-$(uname -r)

       On Arch Linux and derivatives:

          $ pacman -S core/linux-api-headers python-pip gcc

       Once all dependencies are available, you may install python-evdev using pip:

          $ sudo pip install evdev

SPECIFYING HEADER LOCATIONS

       By default, the setup script will look for the input.h and input-event-codes.h [1]  header
       files /usr/include/linux.

       You  may use the --evdev-headers option to the build_ext setuptools command to specify the
       location of these header files. It accepts one or more colon-separated paths. For example:

          $ python setup.py build_ext \
              --evdev-headers buildroot/input.h:buildroot/input-event-codes.h \
              --include-dirs  buildroot/ \
              install  # or any other command (e.g. develop, bdist, bdist_wheel)

       [1]  input-event-codes.h is found only in more recent kernel versions.

QUICK START

   Listing accessible event devices
          >>> import evdev

          >>> devices = [evdev.InputDevice(fn) for fn in evdev.list_devices()]
          >>> for device in devices:
          ...    print(device.fn, device.name, device.phys)
          /dev/input/event1    USB Keyboard        usb-0000:00:12.1-2/input0
          /dev/input/event0    USB Optical Mouse   usb-0000:00:12.0-2/input0

   Reading events from a device
          >>> import evdev

          >>> device = evdev.InputDevice('/dev/input/event1')
          >>> print(device)
          device /dev/input/event1, name "USB Keyboard", phys "usb-0000:00:12.1-2/input0"

          >>> for event in device.read_loop():
          ...     if event.type == evdev.ecodes.EV_KEY:
          ...         print(categorize(event))
          ... # pressing 'a' and holding 'space'
          key event at 1337016188.396030, 30 (KEY_A), down
          key event at 1337016188.492033, 30 (KEY_A), up
          key event at 1337016189.772129, 57 (KEY_SPACE), down
          key event at 1337016190.275396, 57 (KEY_SPACE), hold
          key event at 1337016190.284160, 57 (KEY_SPACE), up

   Accessing event codes
       The evdev.ecodes module provides reverse and forward mappings between the names and values
       of the event subsystem constants.

          >>> from evdev import ecodes

          >>> ecodes.KEY_A
          ... 30
          >>> ecodes.ecodes['KEY_A']
          ... 30
          >>> ecodes.KEY[30]
          ... 'KEY_A'
          >>> ecodes.bytype[ecodes.EV_KEY][30]
          ... 'KEY_A'

          # A single value may correspond to multiple event codes.
          >>> ecodes.KEY[152]
          ... ['KEY_COFFEE', 'KEY_SCREENLOCK']

   Listing and monitoring input devices
       The  python-evdev  package  also  comes  with a small command-line program for listing and
       monitoring input devices:

          $ python -m evdev.evtest

TUTORIAL

   Listing accessible event devices
          >>> import evdev

          >>> devices = [evdev.InputDevice(fn) for fn in evdev.list_devices()]
          >>> for device in devices:
          >>>     print(device.fn, device.name, device.phys)
          /dev/input/event1    Dell Dell USB Keyboard   usb-0000:00:12.1-2/input0
          /dev/input/event0    Dell USB Optical Mouse   usb-0000:00:12.0-2/input0

   Listing device capabilities
          >>> import evdev

          >>> device = evdev.InputDevice('/dev/input/event0')
          >>> print(device)
          device /dev/input/event0, name "Dell USB Optical Mouse", phys "usb-0000:00:12.0-2/input0"

          >>> device.capabilities()
          ... { 0: [0, 1, 2], 1: [272, 273, 274, 275], 2: [0, 1, 6, 8], 4: [4] }

          >>> device.capabilities(verbose=True)
          ... { ('EV_SYN', 0): [('SYN_REPORT', 0), ('SYN_CONFIG', 1), ('SYN_MT_REPORT', 2)],
          ...   ('EV_KEY', 1): [('BTN_MOUSE', 272), ('BTN_RIGHT', 273), ('BTN_MIDDLE', 274), ('BTN_SIDE', 275)], ...

   Listing device capabilities (devices with absolute axes)
          >>> import evdev

          >>> device = evdev.InputDevice('/dev/input/event7')
          >>> print(device)
          device /dev/input/event7, name "Wacom Bamboo 2FG 4x5 Finger", phys ""

          >>> device.capabilities()
          ... { 1: [272, 273, 277, 278, 325, 330, 333] ,
          ...   3: [(0, AbsInfo(min=0, max=15360, fuzz=128, flat=0)),
          ...       (1, AbsInfo(min=0, max=10240, fuzz=128, flat=0))] }

          >>> device.capabilities(verbose=True)
          ... { ('EV_KEY', 1): [('BTN_MOUSE', 272), ('BTN_RIGHT', 273), ...],
          ...   ('EV_ABS', 3): [(('ABS_X', 0), AbsInfo(min=0, max=15360, fuzz=128, flat=0)),
          ...                   (('ABS_Y', 1), AbsInfo(min=0, max=10240, fuzz=128, flat=0)),] }

          >>> device.capabilities(absinfo=False)
          ... { 1: [272, 273, 277, 278, 325, 330, 333],
          ...   3: [0, 1, 47, 53, 54, 57] }

   Getting and setting LED states
          >>> dev.leds(verbose=True)
          ... [('LED_NUML', 0), ('LED_CAPSL', 1)]

          >>> dev.leds()
          ... [0, 1]

          >>> dev.set_led(ecodes.LED_NUML, 1)  # enable numlock
          >>> dev.set_led(ecodes.LED_NUML, 0)  # disable numlock

   Getting currently active keys
          >>> dev.active_keys(verbose=True)
          ... [('KEY_3', 4), ('KEY_LEFTSHIFT', 42)]

          >>> dev.active_keys()
          ... [4, 42]

   Reading events
       Reading events from a single device in an endless loop.

          >>> from evdev import InputDevice, categorize, ecodes
          >>> dev = InputDevice('/dev/input/event1')

          >>> print(dev)
          device /dev/input/event1, name "Dell Dell USB Keyboard", phys "usb-0000:00:12.1-2/input0"

          >>> for event in dev.read_loop():
          ...     if event.type == ecodes.EV_KEY:
          ...         print(categorize(event))
          ... # pressing 'a' and holding 'space'
          key event at 1337016188.396030, 30 (KEY_A), down
          key event at 1337016188.492033, 30 (KEY_A), up
          key event at 1337016189.772129, 57 (KEY_SPACE), down
          key event at 1337016190.275396, 57 (KEY_SPACE), hold
          key event at 1337016190.284160, 57 (KEY_SPACE), up

   Reading events (using asyncore)
          >>> from asyncore import file_dispatcher, loop
          >>> from evdev import InputDevice, categorize, ecodes
          >>> dev = InputDevice('/dev/input/event1')

          >>> class InputDeviceDispatcher(file_dispatcher):
          ...     def __init__(self, device):
          ...         self.device = device
          ...         file_dispatcher.__init__(self, device)
          ...
          ...     def recv(self, ign=None):
          ...         return self.device.read()
          ...
          ...     def handle_read(self):
          ...         for event in self.recv():
          ...             print(repr(event))

          >>> InputDeviceDispatcher(dev)
          >>> loop()
          InputEvent(1337255905L, 358854L, 1, 30, 0L)
          InputEvent(1337255905L, 358857L, 0, 0, 0L)

       NOTE:
          The asyncore module is deprecated in recent versions of Python.  Please consider  using
          asyncio.

   Reading events from multiple devices (using select)
          >>> from evdev import InputDevice
          >>> from select import select

          # A mapping of file descriptors (integers) to InputDevice instances.
          >>> devices = map(InputDevice, ('/dev/input/event1', '/dev/input/event2'))
          >>> devices = {dev.fd: dev for dev in devices}

          >>> for dev in devices.values(): print(dev)
          device /dev/input/event1, name "Dell Dell USB Keyboard", phys "usb-0000:00:12.1-2/input0"
          device /dev/input/event2, name "Logitech USB Laser Mouse", phys "usb-0000:00:12.0-2/input0"

          >>> while True:
          ...    r, w, x = select(devices, [], [])
          ...    for fd in r:
          ...        for event in devices[fd].read():
          ...            print(event)
          event at 1351116708.002230, code 01, type 02, val 01
          event at 1351116708.002234, code 00, type 00, val 00
          event at 1351116708.782231, code 04, type 04, val 458782
          event at 1351116708.782237, code 02, type 01, val 01

   Reading events from multiple devices (using selectors)
       This can also be achieved using the selectors module in Python 3.4:

          from evdev import InputDevice
          from selectors import DefaultSelector, EVENT_READ

          selector = selectors.DefaultSelector()

          mouse = evdev.InputDevice('/dev/input/event1')
          keybd = evdev.InputDevice('/dev/input/event2')

          # This works because InputDevice has a `fileno()` method.
          selector.register(mouse, selectors.EVENT_READ)
          selector.register(keybd, selectors.EVENT_READ)

          while True:
              for key, mask in selector.select():
                  device = key.fileobj
                  for event in device.read():
                      print(event)

   Reading events from multiple devices (using asyncio)
       Yet another possibility is the asyncio module from Python 3.4:

          import asyncio, evdev

          @asyncio.coroutine
          def print_events(device):
              while True:
                  events = yield from device.async_read()
                  for event in events:
                      print(device.fn, evdev.categorize(event), sep=': ')

          mouse = evdev.InputDevice('/dev/input/eventX')
          keybd = evdev.InputDevice('/dev/input/eventY')

          for device in mouse, keybd:
              asyncio.async(print_events(device))

          loop = asyncio.get_event_loop()
          loop.run_forever()

       Since Python 3.5, the async/await syntax makes this even simpler:

          import asyncio, evdev

          mouse = evdev.InputDevice('/dev/input/event4')
          keybd = evdev.InputDevice('/dev/input/event5')

          async def print_events(device):
              async for event in device.async_read_loop():
                  print(device.fn, evdev.categorize(event), sep=': ')

          for device in mouse, keybd:
              asyncio.ensure_future(print_events(device))

          loop = asyncio.get_event_loop()
          loop.run_forever()

   Accessing evdev constants
          >>> from evdev import ecodes

          >>> ecodes.KEY_A, ecodes.ecodes['KEY_A']
          ... (30, 30)
          >>> ecodes.KEY[30]
          ... 'KEY_A'
          >>> ecodes.bytype[ecodes.EV_KEY][30]
          ... 'KEY_A'
          >>> ecodes.KEY[152]  # a single value may correspond to multiple codes
          ... ['KEY_COFFEE', 'KEY_SCREENLOCK']

   Getting exclusive access to a device
          >>> dev.grab()  # become the sole recipient of all incoming input events
          >>> dev.ungrab()

   Associating classes with event types
          >>> from evdev import categorize, event_factory, ecodes

          >>> class SynEvent(object):
          ...     def __init__(self, event):
          ...         ...

          >>> event_factory[ecodes.EV_SYN] = SynEvent

       See events for more information.

   Injecting input
          >>> from evdev import UInput, ecodes as e

          >>> ui = UInput()

          >>> # accepts only KEY_* events by default
          >>> ui.write(e.EV_KEY, e.KEY_A, 1)  # KEY_A down
          >>> ui.write(e.EV_KEY, e.KEY_A, 0)  # KEY_A up
          >>> ui.syn()

          >>> ui.close()

   Injecting events (using a context manager)
          >>> ev = InputEvent(1334414993, 274296, ecodes.EV_KEY, ecodes.KEY_A, 1)
          >>> with UInput() as ui:
          ...    ui.write_event(ev)
          ...    ui.syn()

   Specifying uinput device options
          >>> from evdev import UInput, AbsInfo, ecodes as e

          >>> cap = {
          ...     e.EV_KEY : [e.KEY_A, e.KEY_B],
          ...     e.EV_ABS : [
          ...         (e.ABS_X, AbsInfo(value=0, min=0, max=255,
          ...                           fuzz=0, flat=0, resolution=0)),
          ...         (e.ABS_Y, AbsInfo(0, 0, 255, 0, 0, 0)),
          ...         (e.ABS_MT_POSITION_X, (0, 255, 128, 0)) ]
          ... }

          >>> ui = UInput(cap, name='example-device', version=0x3)
          >>> print(ui)
          name "example-device", bus "BUS_USB", vendor "0001", product "0001", version "0003"
          event types: EV_KEY EV_ABS EV_SYN

          >>> print(ui.capabilities())
          {0: [0, 1, 3],
           1: [30, 48],
           3: [(0,  AbsInfo(value=0, min=0, max=0,   fuzz=255, flat=0, resolution=0)),
               (1,  AbsInfo(value=0, min=0, max=0,   fuzz=255, flat=0, resolution=0)),
               (53, AbsInfo(value=0, min=0, max=255, fuzz=128, flat=0, resolution=0))]}

          >>> # move mouse cursor
          >>> ui.write(e.EV_ABS, e.ABS_X, 20)
          >>> ui.write(e.EV_ABS, e.ABS_Y, 20)
          >>> ui.syn()

   Create uinput device with capabilities of another device
          >>> from evdev import UInput, InputDevice

          >>> mouse = InputDevice('/dev/input/event1')from evdev import UInput, InputDevice
          >>> keybd = '/dev/input/event2'

          >>> ui = UInput.from_device(mouse, keybd, name='keyboard-mouse-device')
          >>> ui.capabilities(verbose=True).keys()
          dict_keys([('EV_LED', 17), ('EV_KEY', 1), ('EV_SYN', 0), ('EV_REL', 2), ('EV_MSC', 4)])

API REFERENCE

   events
   eventio
   eventio_async
   device
   uinput
   util
   ecodes

SCOPE AND STATUS

       Python-evdev  exposes  most  of the more common interfaces defined in the evdev subsystem.
       Reading and injecting events is well supported and has been tested with nearly  all  event
       types.

       The  basic  functionality for reading and uploading force-feedback events is there, but it
       has not been exercised sufficiently. A major shortcoming of the uinput wrapper is that  it
       does not support force-feedback devices at all (see issue #23).

       Some  characters, such as : (colon), cannot be easily injected (see issue #7), Translating
       them into UInput events would require knowing the kernel keyboard translation table, which
       is  beyond  the scope of python-evdev. Please look into the following projects if you need
       more complete or convenient input injection support.

       · python-uinput

       · uinput-mapper

       · PyUserInput (cross-platform, works on the display server level)

       · pygame (cross-platform)

CHANGELOG

   0.7.0 (Jun 16, 2017)
       · InputDevice now accepts objects that support the path protocol.  For example:

            pth = pathlib.Path('/dev/input/event0')
            dev = evdev.InputDevice(pth)

       · Support path protocol in InputDevice. This  means  that  InputDevice  instances  can  be
         passed to callers that expect a os.PathLike object.

       · Exceptions raised during InputDevice.async_read() (and similar) are now handled properly
         (i.e. an exception is set on the returned future instead of leaking that exception  into
         the event loop) (Fixes
         `#67`_
         ).

   0.6.4 (Oct 07, 2016)
       · Exclude ecodes.c from source distribution (Fixes
         `#63`_
         ).

   0.6.3 (Oct 06, 2016)
       · Add  the  UInput.from_device class method, which allows uinput device to be created with
         the capabiltiies of one or more existing input devices:

            ui = UInput.from_device('/dev/input1', '/dev/input2', **constructor_kwargs)

       · Add the build_ecodes distutils command, which generates the ecodes.c  extension  module.
         The new way of overwriting the evdev header locations is:

            python setup.py build \
              build_ecodes --evdev-headers path/input.h:path/input-event-codes.h \
              build_ext --include-dirs  path/ \
              install

         The build* and install commands no longer have to be part of the same command-line (i.e.
         running install will reuse the outputs of the last build).

   0.6.1 (Jun 04, 2016)
       · Dissable tty echoing while evtest is running.

       · Allow evtest to listen to more than one devices.

       · The setup.py script now allows the location of the input header files to be overwritten.
         For example:

            python setup.py build_ext \
              --evdev-headers path/input.h:path/input-event-codes.h \
              --include-dirs  path/ \
              install

   0.6.0 (Feb 14, 2016)
       · Asyncio and async/await support (many thanks to @paulo-raca).

       · Add the ability to set the phys property of uinput devices (thanks @paulo-raca).

       · Add a generic InputDevice.set() method (thanks @paulo-raca).

       · Distribute the evtest script along with evdev.

       · Fix issue with generating ecodes.c in recent kernels (>= 4.4.0).

       · Fix absinfo item indexes in UInput.uinput_create() (thanks @forsenonlhaimaisentito).

       · More robust comparison of InputDevice objects (thanks @isia).

   0.5.0 (Jun 16, 2015)
       · Write  access  to  the input device is no longer mandatory. Evdev will first try to open
         the device for reading and writing and fallback to read-only. Methods that require write
         access (e.g. set_led()) will raise EvdevError if the device is open only for reading.

   0.4.7 (Oct 07, 2014)
       · Fallback to distutils if setuptools is not available.

   0.4.6 (Oct 07, 2014)
       · Rework documentation and docstrings once more.

       · Fix install on Python 3.4 (works around issue21121).

       · Fix ioctl() requested buffer size (thanks Jakub Wojciech Klama).

   0.4.5 (Jul 06, 2014)
       · Add method for returning a list of the currently active keys - InputDevice.active_keys()
         (thanks @spasche).

       · Fix a potential buffer overflow in ioctl_capabilities() (thanks @spasche).

   0.4.4 (Jun 04, 2014)
       · Calling InputDevice.read_one() should always return None, when there is  nothing  to  be
         read, even in case of a EAGAIN errno (thanks JPP).

   0.4.3 (Dec 19, 2013)
       · Silence OSError in destructor (thanks @polyphemus).

       · Make  InputDevice.close()  work  in  cases in which stdin (fd 0) has been closed (thanks
         @polyphemus).

   0.4.2 (Dec 13, 2013)
       · Rework documentation and docstrings.

       · Call InputDevice.close() from InputDevice.__del__().

   0.4.1 (Jul 24, 2013)
       · Fix reference counting in InputDevice.device_read(), InputDevice.device_read_many()  and
         ioctl_capabilities().

   0.4.0 (Jul 01, 2013)
       · Add FF_* and FF_STATUS codes to ecodes() (thanks @bgilbert).

       · Reverse  event  code mappings (ecodes.{KEY,FF,REL,ABS} and etc.)  will now map to a list
         of codes, whenever a value corresponds to multiple codes:

            >>> ecodes.KEY[152]
            ... ['KEY_COFFEE', 'KEY_SCREENLOCK']
            >>> ecodes.KEY[30]
            ... 'KEY_A'

       · Set the state of a LED through InputDevice.set_led() (thanks @accek).

       · Open InputDevice.fd in O_RDWR mode from now on.

       · Fix segfault in InputDevice.device_read_many() (thanks @bgilbert).

   0.3.3 (May 29, 2013)
       · Raise IOError from  InputDevice.device_read()  and  InputDevice.device_read_many()  when
         InputDevice.read() fails.

       · Several stability and style changes (thank you debian code reviewers).

   0.3.2 (Apr 05, 2013)
       · Fix vendor id and product id order in DeviceInfo() (thanks @kived).

   0.3.1 (Nov 23, 2012)
       · InputDevice.read()  will  return  an  empty  tuple  if  the  device has nothing to offer
         (instead of segfaulting).

       · Exclude unnecessary package data in sdist and bdist.

   0.3.0 (Nov 06, 2012)
       · Add ability to set/get auto-repeat settings with EVIOC{SG}REP.

       · Add InputDevice.version() - the value of EVIOCGVERSION.

       · Add InputDevice.read_loop().

       · Add InputDevice.grab() and InputDevice.ungrab() - exposes EVIOCGRAB.

       · Add InputDevice.leds() - exposes EVIOCGLED.

       · Replace DeviceInfo class with a namedtuple.

       · Prevent InputDevice.read_one() from skipping events.

       · Rename AbsData to AbsInfo (as in struct input_absinfo).

   0.2.0 (Aug 22, 2012)
       · Add the ability to set arbitrary device capabilities on uinput devices (defaults to  all
         EV_KEY ecodes).

       · Add UInput.device which is an open InputDevice to the input device that uinput ‘spawns’.

       · Add UInput.capabilities() which is just a shortcut to UInput.device.capabilities().

       · Rename UInput.write() to UInput.write_event().

       · Add a simpler UInput.write(type, code, value)() method.

       · Make   all   UInput()  constructor  arguments  optional  (default  device  name  is  now
         py-evdev-uinput).

       · Add the ability to set absmin, absmax, absfuzz and absflat when  specifying  the  uinput
         device’s capabilities.

       · Remove the nophys argument - if a device fails the EVIOCGPHYS ioctl, phys will equal the
         empty string.

       · Make InputDevice.capabilities() perform a  EVIOCGABS  ioctl  for  devices  that  support
         EV_ABS and return that info wrapped in an AbsData namedtuple.

       · Split ioctl_devinfo into ioctl_devinfo and ioctl_capabilities.

       · Split UInput.uinput_open() to UInput.uinput_open() and UInput.uinput_create()

       · Add more uinput usage examples and documentation.

       · Rewrite uinput tests.

       · Remove mouserel and mouseabs from UInput.

       · Tie the sphinx version and release to the distutils version.

       · Set ‘methods-before-attributes’ sorting in the docs.

       · Remove KEY_CNT and KEY_MAX from ecodes.keys().

   0.1.1 (May 18, 2012)
       · Add events.keys, which is a combination of all BTN_ and KEY_ event codes.

       · ecodes.c was not generated when installing through pip.

   0.1.0 (May 17, 2012)
       Initial Release

       This package is released under the terms of the Revised BSD License.

AUTHOR

       Georgi Valkov

COPYRIGHT

       2012-2017, Georgi Valkov