usb-gadget 0.2

A python library for creating and interfacing with USB Gadgets on Linux through libcomposite

USBGadget

A python library for creating and interfacing with USB Gadgets on Linux through libcomposite.

This library assumes the ConfigFS gadget directory to be /sys/kernel/config/usb_gadget. If this is not the case, specify the correct directory in the call to USBGadget(name, path).

Creating a gadget

Any gadget type that libcomposite supports can be created.

import usb_gadget
gadget = usb_gadget.USBGadget('my_test_gadget')
# ... set up gadget parameters, functions and configurations
gadget.activate()

Interfacing with a gadget

This library has an interface for HID gadgets. Specifically, keyboard, mouse and game controller.

import usb_gadget
gadget = usb_gadget.USBGadget('my_test_gadget')
function = usb_gadget.HIDFunction(gadget, 'keyboard0')
keyboard = usb_gadget.KeyboardGadget(function.device)
keyboard.press_and_release('a')

See also example.py for a full keyboard setup

Example HID Report Descriptors

Keyboard

• 1 byte modifier keys
• 1 byte empty
• 6 bytes scancodes currently pressed keys

Report length: 8

0x05, 0x01,        # Usage Page (Generic Desktop Ctrls)
0x09, 0x06,        # Usage (Keyboard)
0xA1, 0x01,        # Collection (Application)
0x05, 0x07,        #   Usage Page (Kbrd/Keypad)
0x19, 0xE0,        #   Usage Minimum (0xE0)
0x29, 0xE7,        #   Usage Maximum (0xE7)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x01,        #   Logical Maximum (1)
0x75, 0x01,        #   Report Size (1)
0x95, 0x08,        #   Report Count (8)
0x81, 0x02,        #   Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x95, 0x01,        #   Report Count (1)
0x75, 0x08,        #   Report Size (8)
0x81, 0x03,        #   Input (Const,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x95, 0x06,        #   Report Count (6)
0x75, 0x08,        #   Report Size (8)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x65,        #   Logical Maximum (101)
0x05, 0x07,        #   Usage Page (Kbrd/Keypad)
0x19, 0x00,        #   Usage Minimum (0x00)
0x29, 0x65,        #   Usage Maximum (0x65)
0x81, 0x00,        #   Input (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0xC0,              # End Collection

Mouse

• 1 byte currently pressed buttons
• 2 bytes X movement
• 2 bytes Y movement
• 1 byte vertical scroll wheel
• 1 byte horizontal scroll wheel

Report length: 7

0x05, 0x01,        # Usage Page (Generic Desktop Ctrls)
0x09, 0x02,        # Usage (Mouse)
0xA1, 0x01,        # Collection (Application)
0x05, 0x09,        #   Usage Page (Button)
0x19, 0x01,        #   Usage Minimum (0x01)
0x29, 0x08,        #   Usage Maximum (0x08)
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x01,        #   Logical Maximum (1)
0x95, 0x08,        #   Report Count (8)
0x75, 0x01,        #   Report Size (1)
0x81, 0x02,        #   Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x05, 0x01,        #   Usage Page (Generic Desktop Ctrls)
0x09, 0x30,        #   Usage (X)
0x09, 0x31,        #   Usage (Y)
0x16, 0x00, 0x80,  #   Logical Minimum (-32768)
0x26, 0xFF, 0x7F,  #   Logical Maximum (32767)
0x75, 0x10,        #   Report Size (16)
0x95, 0x02,        #   Report Count (2)
0x81, 0x06,        #   Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x09, 0x38,        #   Usage (Wheel)
0x15, 0x81,        #   Logical Minimum (-127)
0x25, 0x7F,        #   Logical Maximum (127)
0x75, 0x08,        #   Report Size (8)
0x95, 0x01,        #   Report Count (1)
0x81, 0x06,        #   Input (Data,Var,Rel,No Wrap,Linear,Preferred State,No Null Position)
0x05, 0x0C,        #   Usage Page (Consumer)
0x0A, 0x38, 0x02,  #   Usage (AC Pan)
0x15, 0x81,        #   Logical Minimum (-127)
0x25, 0x7F,        #   Logical Maximum (127)
0x75, 0x08,        #   Report Size (8)
0x95, 0x01,        #   Report Count (1)
0x81, 0x06,        #   Input (Data,Var,Rel,No Wrap,Linear,Preferred State,No Null Position)
0xC0,              # End Collection

Joystick

• 4 bytes joystick positions (2x XY)
• 2 bytes trigger positions (2x Z)
• 3 bytes currently pressed buttons (24 buttons total)

Report length: 9

0x05, 0x01,        # Usage Page (Generic Desktop Ctrls)
0x09, 0x04,        # Usage (Joystick)
0xA1, 0x01,        # Collection (Application)
0x15, 0x81,        #   Logical Minimum (-127)
0x25, 0x7F,        #   Logical Maximum (127)
0x09, 0x01,        #   Usage (Pointer)
0xA1, 0x00,        #   Collection (Physical)
0x09, 0x30,        #     Usage (X)
0x09, 0x31,        #     Usage (Y)
0x09, 0x33,        #     Usage (Rx)
0x09, 0x34,        #     Usage (Ry)
0x75, 0x08,        #     Report Size (8)
0x95, 0x04,        #     Report Count (4)
0x81, 0x02,        #     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0xC0,              #   End Collection
0x15, 0x00,        #   Logical Minimum (0)
0x25, 0x7F,        #   Logical Maximum (127)
0x09, 0x01,        #   Usage (Pointer)
0xA1, 0x00,        #   Collection (Physical)
0x09, 0x32,        #     Usage (Z)
0x09, 0x35,        #     Usage (Rz)
0x75, 0x08,        #     Report Size (8)
0x95, 0x02,        #     Report Count (2)
0x81, 0x02,        #     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0xC0,              #   End Collection
0xA1, 0x00,        #   Collection (Physical)
0x05, 0x09,        #     Usage Page (Button)
0x19, 0x01,        #     Usage Minimum (0x01)
0x29, 0x18,        #     Usage Maximum (0x18)
0x15, 0x00,        #     Logical Minimum (0)
0x25, 0x01,        #     Logical Maximum (1)
0x75, 0x01,        #     Report Size (1)
0x95, 0x18,        #     Report Count (24)
0x81, 0x02,        #     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0xC0,              #   End Collection
0xC0,              # End Collection