Skip to content

Commit 583bc0d

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 <[email protected]>
1 parent 45ead11 commit 583bc0d

File tree

20 files changed

+2829
-0
lines changed

20 files changed

+2829
-0
lines changed

‎micropython/usb/README.md

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

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

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
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+
# To run this example:
7+
#
8+
# 1. Make sure `usb-device-cdc` is installed via: mpremote mip install usb-device-cdc
9+
#
10+
# 2. Run the example via: mpremote run cdc_repl_example.py
11+
#
12+
# 3. mpremote will exit with an error after the previous step, because when the
13+
# example runs the existing USB device disconnects and then re-enumerates with
14+
# the second serial port. If you check (for example by running mpremote connect
15+
# list) then you should now see two USB serial devices.
16+
#
17+
# 4. Connect to one of the new ports: mpremote connect PORTNAME
18+
#
19+
# It may be necessary to type Ctrl-B to exit the raw REPL mode and resume the
20+
# interactive REPL after mpremote connects.
21+
#
22+
# MIT license; Copyright (c) 2023-2024 Angus Gratton
23+
import os
24+
import time
25+
import usb.device
26+
from usb.device.cdc import CDCInterface
27+
28+
cdc = CDCInterface()
29+
cdc.init(timeout=0) # zero timeout makes this non-blocking, suitable for os.dupterm()
30+
31+
# pass builtin_driver=True so that we get the built-in USB-CDC alongside,
32+
# if it's available.
33+
usb.device.get().init(cdc, builtin_driver=True)
34+
35+
print("Waiting for USB host to configure the interface...")
36+
37+
# wait for host enumerate as a CDC device...
38+
while not cdc.is_open():
39+
time.sleep_ms(100)
40+
41+
# Note: This example doesn't wait for the host to access the new CDC port,
42+
# which could be done by polling cdc.dtr, as this will block the REPL
43+
# from resuming while this code is still executing.
44+
45+
print("CDC port enumerated, duplicating REPL...")
46+
47+
old_term = os.dupterm(cdc)

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

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

0 commit comments

Comments
 (0)