Skip to content

Commit 81962f1

Browse files
projectgusprojectgus
committed
usb: Add USB device support packages.
These packages build on top of machine.USBDevice() to provide high level and flexible support for implementing USB devices in Python code. Additional credits, as per included copyright notices: - CDC support based on initial implementation by @hoihu with fixes by @linted. - MIDI support based on initial implementation by @paulhamsh. - HID keypad example based on work by @turmoni. - Everyone who tested and provided feedback on early versions of these packages. This work was funded through GitHub Sponsors. Signed-off-by: Angus Gratton <angus@redyak.com.au>
1 parent 45ead11 commit 81962f1

20 files changed

Lines changed: 2733 additions & 0 deletions

File tree

‎micropython/usb/README.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Dynamic USB packages
2+
3+
These packages allow implementing USB functionality on a MicroPython device using pure Python code.
4+
5+
Currently only USB device is implemented, not USB host.
6+
7+
## USB Device support
8+
9+
### Support
10+
11+
USB Device support depends on the low-level [machine.USBDevice](https://docs.micropython.org/en/latest/library/machine.USBDevice.html) class. This class is new and not supported on all ports, so please check the documentation for your MicroPython version. It is possible to implement a USB device using only the low-level USBDevice class. These packages are higher level and easier to use.
12+
13+
For more information about how to install packages, or "freeze" them into a
14+
firmware image, consult the [MicroPython documentation on "Package
15+
management"](https://docs.micropython.org/en/latest/reference/packages.html).
16+
17+
### Examples
18+
19+
The [examples/device](examples/device) directory in this repo has a range of examples. After installing necessary packages, you can download an example and run it with `mpremote run EXAMPLE_FILENAME.py` ([mpremote docs](https://docs.micropython.org/en/latest/reference/mpremote.html#mpremote-command-run)).
20+
21+
#### Unexpected serial disconnects
22+
23+
If you normally connect to your MicroPython device over a USB serial port ("USB CDC"), then running a USB example will disconnect mpremote when the new USB device configuration activates and the serial port has to temporarily disconnect. It is likely that mpremote will print an error. The example should still start running, if necessary then you can reconnect with mpremote and type Ctrl-B to restore the MicroPython REPL and/or Ctrl-C to stop the running example.
24+
25+
If you use `mpremote run` again while a different runtime USB configuration is already active, then the USB serial port may disconnect immediately before the example runs. This is because mpremote has to soft-reset MicroPython, and when the existing USB device is reset then the entire USB port needs to reset. If this happens, run the same `mpremote run` command again.
26+
27+
We plan to add features to `mpremote` so that this limitation is less disruptive. Other tools that communicate with MicroPython over the serial port will encounter similar issues when runtime USB is in use.
28+
29+
### Initialising runtime USB
30+
31+
The overall pattern for enabling USB devices at runtime is:
32+
33+
1. Instantiate the Interface objects for your desired USB device.
34+
2. Call `usb.device.get()` to get the singleton object for the high-level USB device.
35+
3. Call `init(...)` to pass the desired interfaces as arguments, plus any custom
36+
keyword arguments to configure the overall device.
37+
38+
An example, similar to [mouse_example.py](examples/device/mouse_example.py):
39+
40+
```py
41+
m = usb.device.mouse.MouseInterface()
42+
usb.device.get().init(m, builtin_driver=True)
43+
```
44+
45+
Setting `builtin_driver=True` means that any built-in USB serial port will still
46+
be available. Otherwise, you may permanently lose access to MicroPython until
47+
the next time the device resets.
48+
49+
See [Unexpected serial disconnects](#Unexpected-serial-disconnects), above, for
50+
an explanation of possible errors or disconnects when the runtime USB device
51+
initialises.
52+
53+
Placing the call to `usb.device.get().init()` into the `boot.py` of the MicroPython file system allows the runtime USB device to initialise immediately on boot, before any built-in USB. However, note that calling this function on boot without `builtin_driver=True` will make the MicroPython USB serial interface permanently inaccessible until you "safe mode boot" (on supported boards) or completely erase the flash of your device.
54+
55+
### Package usb-device-keyboard
56+
57+
This package provides the `usb.device.keyboard` module. See [keyboard_example.py](examples/device/keyboard_example.py) for an example program.
58+
59+
### Package usb-device-mouse
60+
61+
This package provides the `usb.device.mouse` module. See [mouse_example.py](examples/device/mouse_example.py) for an example program.
62+
63+
### Package usb-device-hid
64+
65+
This package provides the `usb.device.hid` module. USB HID (Human Interface Device) class allows creating a wide variety of device types. The most common are mouse and keyboard, which have their own packages in micropython-lib. However, using the usb-device-hid package directly allows creation of any kind of HID device.
66+
67+
See [hid_custom_keypad_example.py](examples/device/hid_custom_keypad_example.py) for an example of a Keypad HID device with a custom HID descriptor.
68+
69+
### Package usb-device-cdc
70+
71+
This package provides the `usb.device.cdc` module. USB-CDC (Communications Device Class) is most commonly used for virtual serial port USB interfaces, and that is what is supported here.
72+
73+
The example [cdc_repl_example.py](examples/device/cdc_repl_example.py) demonstrates how to add a second USB serial interface and duplicate the MicroPython REPL between the two.
74+
75+
### Package usb-device-midi
76+
77+
This package provides the `usb.device.midi` module. This allows implementing MIDI devices in MicroPython.
78+
79+
The example [midi_example.py](examples/device/midi_example.py) demonstrates how to create a simple MIDI device to send MIDI data to the USB host.
80+
81+
### Package usb-device
82+
83+
This package contains the common implementation components for the other packages, and can be used to create new and different USB device types. All of the other packages depend on this package.
84+
85+
It provides the `usb.device.get()` function for accessing the Device singleton object, and the `usb.device.core` module which contains the low-level classes and utility functions for implementing new USB interface drivers in Python. The best examples of how to use the core classes is the source code of the other USB device packages.

‎micropython/usb/examples/device/cdc_repl_example.py‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# MicroPython USB CDC REPL example
2+
#
3+
# Example demonstrating how to use os.dupterm() to provide the
4+
# MicroPython REPL on a dynamic CDCInterface() serial port.
5+
#
6+
# Note that if you run this example on the built-in USB CDC port via 'mpremote
7+
# run' then you'll have to reconnect after it re-enumerates, and it may be
8+
# necessary afterward to type Ctrl-B to exit the Raw REPL mode and resume the
9+
# interactive REPL back.
10+
#
11+
# This example uses the usb-device-cdc package for the CDCInterface class.
12+
# This can be installed with:
13+
#
14+
# mpremote mip install usb-device-cdc
15+
#
16+
# MIT license; Copyright (c) 2023-2024 Angus Gratton
17+
import os
18+
import time
19+
import usb.device
20+
from usb.device.cdc import CDCInterface
21+
22+
cdc = CDCInterface()
23+
cdc.init(timeout=0) # zero timeout makes this non-blocking, suitable for os.dupterm()
24+
25+
# pass builtin_driver=True so that we get the built-in USB-CDC alongside,
26+
# if it's available.
27+
usb.device.get().init(cdc, builtin_driver=True)
28+
29+
print("Waiting for USB host to configure the interface...")
30+
31+
# wait for host enumerate as a CDC device...
32+
while not cdc.is_open():
33+
time.sleep_ms(100)
34+
35+
# Note: This example doesn't wait for the host to access the new CDC port,
36+
# which could be done by polling cdc.dtr, as this will block the REPL
37+
# from resuming while this code is still executing.
38+
39+
print("CDC port enumerated, duplicating REPL...")
40+
41+
old_term = os.dupterm(cdc)

‎micropython/usb/examples/device/hid_custom_keypad_example.py‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# MicroPython USB HID custom Keypad example
2+
#
3+
# This example demonstrates creating a custom HID device with its own
4+
# HID descriptor, in this case for a USB number keypad.
5+
#
6+
# For higher level examples that require less code to use, see mouse_example.py
7+
# and keyboard_example.py
8+
#
9+
# This example uses the usb-device-hid package for the HIDInterface class.
10+
# This can be installed with:
11+
#
12+
# mpremote mip install usb-device-hid
13+
#
14+
# MIT license; Copyright (c) 2023 Dave Wickham, 2023-2024 Angus Gratton
15+
from micropython import const
16+
import time
17+
import usb.device
18+
from usb.device.hid import HIDInterface
19+
20+
_INTERFACE_PROTOCOL_KEYBOARD = const(0x01)
21+
22+
23+
def keypad_example():
24+
k = KeypadInterface()
25+
26+
usb.device.get().init(k, builtin_driver=True)
27+
28+
while not k.is_open():
29+
time.sleep_ms(100)
30+
31+
while True:
32+
time.sleep(2)
33+
print("Press NumLock...")
34+
k.send_key("<NumLock>")
35+
time.sleep_ms(100)
36+
k.send_key()
37+
time.sleep(1)
38+
# continue
39+
print("Press ...")
40+
for _ in range(3):
41+
time.sleep(0.1)
42+
k.send_key(".")
43+
time.sleep(0.1)
44+
k.send_key()
45+
print("Starting again...")
46+
47+
48+
class KeypadInterface(HIDInterface):
49+
# Very basic synchronous USB keypad HID interface
50+
51+
def __init__(self):
52+
super().__init__(
53+
_KEYPAD_REPORT_DESC,
54+
set_report_buf=bytearray(1),
55+
protocol=_INTERFACE_PROTOCOL_KEYBOARD,
56+
interface_str="MicroPython Keypad",
57+
)
58+
self.numlock = False
59+
60+
def on_set_report(self, report_data, _report_id, _report_type):
61+
report = report_data[0]
62+
b = bool(report & 1)
63+
if b != self.numlock:
64+
print("Numlock: ", b)
65+
self.numlock = b
66+
67+
def send_key(self, key=None):
68+
if key is None:
69+
self.send_report(b"\x00")
70+
else:
71+
self.send_report(_key_to_id(key).to_bytes(1, "big"))
72+
73+
74+
# See HID Usages and Descriptions 1.4, section 10 Keyboard/Keypad Page (0x07)
75+
#
76+
# This keypad example has a contiguous series of keys (KEYPAD_KEY_IDS) starting
77+
# from the NumLock/Clear keypad key (0x53), but you can send any Key IDs from
78+
# the table in the HID Usages specification.
79+
_KEYPAD_KEY_OFFS = const(0x53)
80+
81+
_KEYPAD_KEY_IDS = [
82+
"<NumLock>",
83+
"/",
84+
"*",
85+
"-",
86+
"+",
87+
"<Enter>",
88+
"1",
89+
"2",
90+
"3",
91+
"4",
92+
"5",
93+
"6",
94+
"7",
95+
"8",
96+
"9",
97+
"0",
98+
".",
99+
]
100+
101+
102+
def _key_to_id(key):
103+
# This is a little slower than making a dict for lookup, but uses
104+
# less memory and O(n) can be fast enough when n is small.
105+
return _KEYPAD_KEY_IDS.index(key) + _KEYPAD_KEY_OFFS
106+
107+
108+
# HID Report descriptor for a numeric keypad
109+
#
110+
# fmt: off
111+
_KEYPAD_REPORT_DESC = (
112+
b'\x05\x01' # Usage Page (Generic Desktop)
113+
b'\x09\x07' # Usage (Keypad)
114+
b'\xA1\x01' # Collection (Application)
115+
b'\x05\x07' # Usage Page (Keypad)
116+
b'\x19\x00' # Usage Minimum (0)
117+
b'\x29\xFF' # Usage Maximum (ff)
118+
b'\x15\x00' # Logical Minimum (0)
119+
b'\x25\xFF' # Logical Maximum (ff)
120+
b'\x95\x01' # Report Count (1),
121+
b'\x75\x08' # Report Size (8),
122+
b'\x81\x00' # Input (Data, Array, Absolute)
123+
b'\x05\x08' # Usage page (LEDs)
124+
b'\x19\x01' # Usage Minimum (1)
125+
b'\x29\x01' # Usage Maximum (1),
126+
b'\x95\x01' # Report Count (1),
127+
b'\x75\x01' # Report Size (1),
128+
b'\x91\x02' # Output (Data, Variable, Absolute)
129+
b'\x95\x01' # Report Count (1),
130+
b'\x75\x07' # Report Size (7),
131+
b'\x91\x01' # Output (Constant) - padding bits
132+
b'\xC0' # End Collection
133+
)
134+
# fmt: on
135+
136+
137+
keypad_example()

‎micropython/usb/examples/device/keyboard_example.py‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# MicroPython USB Keyboard example
2+
#
3+
# This example uses the usb-device-keyboard package for the KeyboardInterface class.
4+
# This can be installed with:
5+
#
6+
# mpremote mip install usb-device-keyboard
7+
#
8+
# To implement a keyboard with different USB HID characteristics, copy the
9+
# usb-device-keyboard/usb/device/keyboard.py file into your own project and modify
10+
# KeyboardInterface.
11+
#
12+
# MIT license; Copyright (c) 2024 Angus Gratton
13+
import usb.device
14+
from usb.device.keyboard import KeyboardInterface, KeyCode, LEDCode
15+
from machine import Pin
16+
import time
17+
18+
# Tuples mapping Pin inputs to the KeyCode each input generates
19+
#
20+
# (Big keyboards usually multiplex multiple keys per input with a scan matrix,
21+
# but this is a simple example.)
22+
KEYS = (
23+
(Pin.cpu.GPIO10, KeyCode.CAPS_LOCK),
24+
(Pin.cpu.GPIO11, KeyCode.LEFT_SHIFT),
25+
(Pin.cpu.GPIO12, KeyCode.M),
26+
(Pin.cpu.GPIO13, KeyCode.P),
27+
# ... add more pin to KeyCode mappings here if needed
28+
)
29+
30+
# Tuples mapping Pin outputs to the LEDCode that turns the output on
31+
LEDS = (
32+
(Pin.board.LED, LEDCode.CAPS_LOCK),
33+
# ... add more pin to LEDCode mappings here if needed
34+
)
35+
36+
37+
class ExampleKeyboard(KeyboardInterface):
38+
def on_led_update(self, led_mask):
39+
# print(hex(led_mask))
40+
for pin, code in LEDS:
41+
# Set the pin high if 'code' bit is set in led_mask
42+
pin(code & led_mask)
43+
44+
45+
def keyboard_example():
46+
# Initialise all the pins as active-low inputs with pullup resistors
47+
for pin, _ in KEYS:
48+
pin.init(Pin.IN, Pin.PULL_UP)
49+
50+
# Initialise all the LEDs as active-high outputs
51+
for pin, _ in LEDS:
52+
pin.init(Pin.OUT, value=0)
53+
54+
# Register the keyboard interface and re-enumerate
55+
k = ExampleKeyboard()
56+
usb.device.get().init(k, builtin_driver=True)
57+
58+
print("Entering keyboard loop...")
59+
60+
keys = [] # Keys held down, reuse the same list object
61+
prev_keys = [None] # Previous keys, starts with a dummy value so first
62+
# iteration will always send
63+
while True:
64+
if k.is_open():
65+
keys.clear()
66+
for pin, code in KEYS:
67+
if not pin(): # active-low
68+
keys.append(code)
69+
if keys != prev_keys:
70+
# print(keys)
71+
k.send_keys(keys)
72+
prev_keys.clear()
73+
prev_keys.extend(keys)
74+
75+
# This simple example scans each input in an infinite loop, but a more
76+
# complex implementation would probably use a timer or similar.
77+
time.sleep_ms(1)
78+
79+
80+
keyboard_example()

0 commit comments

Comments
 (0)