Skip to content

Commit b2df89c

Browse files
dpgeorgedpgeorge
committed
examples/usb: Add a very simple USBDevice example with host.
Signed-off-by: Damien George <damien@micropython.org>
1 parent c3301da commit b2df89c

File tree

2 files changed

+191
-0
lines changed

2 files changed

+191
-0
lines changed

‎examples/usb/usb_simple_device.py‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Implementation of a very simple, custom USB device in Python. The device has an
2+
# IN and OUT endpoint, accepts up to 64 bytes of data on the OUT endpoint, and echos
3+
# that data back to the IN endpoint.
4+
#
5+
# To run, just execute this file on a device with machine.USBDevice support. The device
6+
# will then change to the custom USB device.
7+
#
8+
# For example, use `mpremote` (the `--no-follow` option starts the script running
9+
# without waiting for a response, because there won't be a response after the device
10+
# changes its USB mode):
11+
#
12+
# $ mpremote run --no-follow usb_simple_device.py
13+
#
14+
# Then, run the host side of the example on your PC using:
15+
#
16+
# $ sudo python usb_simple_host_pyusb.py
17+
#
18+
# You'll need to have `pyusb` installed via `pip install pyusb` to run the host PC code.
19+
# And `sudo` is most likely needed to access the custom USB device.
20+
#
21+
# Once you have finished running the code, you will need to reset or unplug the USB
22+
# device to stop it.
23+
24+
import machine
25+
26+
# VID and PID of the USB device.
27+
VID = 0xF055
28+
PID = 0x9999
29+
30+
# USB endpoints used by the device.
31+
EP_OUT = 0x01
32+
EP_IN = 0x81
33+
34+
# USB device descriptor.
35+
_desc_dev = bytes(
36+
[
37+
0x12, # bLength
38+
0x01, # bDescriptorType: Device
39+
0x00,
40+
0x02, # USB version: 2.00
41+
0xFF, # bDeviceClass: vendor
42+
0x00, # bDeviceSubClass
43+
0x01, # bDeviceProtocol
44+
0x40, # bMaxPacketSize
45+
VID & 0xFF,
46+
VID >> 8 & 0xFF, # VID
47+
PID & 0xFF,
48+
PID >> 8 & 0xFF, # PID
49+
0x00,
50+
0x01, # bcdDevice: 1.00
51+
0x11, # iManufacturer
52+
0x12, # iProduct
53+
0x13, # iSerialNumber
54+
0x01, # bNumConfigurations: 1
55+
]
56+
)
57+
58+
# USB configuration descriptor.
59+
_desc_cfg = bytes(
60+
[
61+
# Configuration Descriptor.
62+
0x09, # bLength
63+
0x02, # bDescriptorType: configuration
64+
0x20,
65+
0x00, # wTotalLength: 32
66+
0x01, # bNumInterfaces
67+
0x01, # bConfigurationValue
68+
0x14, # iConfiguration
69+
0xA0, # bmAttributes
70+
0x96, # bMaxPower
71+
# Interface Descriptor.
72+
0x09, # bLength
73+
0x04, # bDescriptorType: interface
74+
0x00, # bInterfaceNumber
75+
0x00, # bAlternateSetting
76+
0x02, # bNumEndpoints
77+
0xFF, # bInterfaceClass
78+
0x03, # bInterfaceSubClass
79+
0x00, # bInterfaceProtocol
80+
0x15, # iInterface
81+
# Endpoint IN1.
82+
0x07, # bLength
83+
0x05, # bDescriptorType: endpoint
84+
EP_IN, # bEndpointAddress
85+
0x03, # bmAttributes: interrupt
86+
0x40,
87+
0x00, # wMaxPacketSize
88+
0x0A, # bInterval
89+
# Endpoint OUT1.
90+
0x07, # bLength
91+
0x05, # bDescriptorType: endpoint
92+
EP_OUT, # bEndpointAddress
93+
0x02, # bmAttributes: bulk
94+
0x40,
95+
0x00, # wMaxPacketSize
96+
0x00, # bInterval
97+
]
98+
)
99+
100+
# USB strings.
101+
_desc_strs = {
102+
0x11: b"iManufacturer",
103+
0x12: b"iProduct",
104+
0x13: b"iSerial",
105+
0x14: b"iInterface",
106+
0x15: b"iInterface",
107+
0x16: b"Extra information",
108+
}
109+
110+
111+
# USB callback for when our custom USB interface is opened by the host.
112+
def _open_itf_cb(interface_desc_view):
113+
print("_open_itf_cb", bytes(interface_desc_view))
114+
# Prepare to receive first data packet on the OUT endpoint.
115+
usbd.submit_xfer(EP_OUT, usbd_buf)
116+
117+
118+
# USB callback for when a data transfer (IN or OUT) has completed.
119+
def _xfer_cb(ep_addr, result, xferred_bytes):
120+
print("_xfer_cb", ep_addr, result, xferred_bytes)
121+
if ep_addr == EP_OUT:
122+
# Received data packet from the host, print it out.
123+
print(usbd_buf)
124+
# And then echo the data back to the host.
125+
usbd.submit_xfer(EP_IN, memoryview(usbd_buf)[:xferred_bytes])
126+
elif ep_addr == EP_IN:
127+
# Host got our data, prepare to receive the next data packet.
128+
usbd.submit_xfer(EP_OUT, usbd_buf)
129+
130+
131+
# USB data buffer, for IN and OUT transfers.
132+
usbd_buf = bytearray(64)
133+
134+
# Switch the USB device to our custom USB driver.
135+
usbd = machine.USBDevice()
136+
usbd.builtin_driver = usbd.BUILTIN_NONE
137+
usbd.config(
138+
desc_dev=_desc_dev,
139+
desc_cfg=_desc_cfg,
140+
desc_strs=_desc_strs,
141+
open_itf_cb=_open_itf_cb,
142+
xfer_cb=_xfer_cb,
143+
)
144+
usbd.active(1)

‎examples/usb/usb_simple_host_pyusb.py‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Host side of the `usb_simple_device.py` example. This must be run using standard
4+
# Python on a PC. See further instructions in `usb_simple_device.py`.
5+
6+
import sys
7+
import usb.core
8+
import usb.util
9+
10+
# VID and PID of the custom USB device.
11+
VID = 0xF055
12+
PID = 0x9999
13+
14+
# USB endpoints used by the device.
15+
EP_OUT = 0x01
16+
EP_IN = 0x81
17+
18+
19+
def main():
20+
# Search for the custom USB device by VID/PID.
21+
dev = usb.core.find(idVendor=VID, idProduct=PID)
22+
23+
if dev is None:
24+
print("No USB device found")
25+
sys.exit(1)
26+
27+
# Claim the USB device.
28+
usb.util.claim_interface(dev, 0)
29+
30+
# Read the device's strings.
31+
for i in range(0x11, 0x17):
32+
print(f"str{i}:", usb.util.get_string(dev, i))
33+
34+
# Test writing to the device.
35+
ret = dev.write(EP_OUT, b"01234567", timeout=1000)
36+
print(ret)
37+
38+
# Test reading from the device.
39+
print(dev.read(EP_IN, 64))
40+
41+
# Release the USB device.
42+
usb.util.release_interface(dev, 0)
43+
usb.util.dispose_resources(dev)
44+
45+
46+
if __name__ == "__main__":
47+
main()

0 commit comments

Comments
 (0)