Skip to content

Commit 1ae9033

Browse files
andrewleechclaude
andcommitted
usb-device-mtp: Add documentation for MTP driver
- Create detailed README.md for usb-device-mtp package - Update main USB README.md to include MTP driver information - Document usage, configuration options, and limitations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 0a3bf40 commit 1ae9033

File tree

2 files changed

+97
-0
lines changed

2 files changed

+97
-0
lines changed

micropython/usb/README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,16 @@ USB MIDI devices in MicroPython.
135135
The example [midi_example.py](examples/device/midi_example.py) demonstrates how
136136
to create a simple MIDI device to send MIDI data to and from the USB host.
137137

138+
### Package usb-device-mtp
139+
140+
This package provides the `usb.device.mtp` module, which implements the Media Transfer
141+
Protocol (MTP) to expose MicroPython's filesystem to host computers.
142+
143+
The example [mtp_example.py](examples/device/mtp_example.py) demonstrates how to
144+
create an MTP device interface that allows browsing and transferring files to/from
145+
the MicroPython filesystem using standard file managers on Windows, macOS, and Linux
146+
without requiring special drivers.
147+
138148
### Limitations
139149

140150
#### Buffer thread safety
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# USB MTP Device Driver for MicroPython
2+
3+
This package provides a USB Media Transfer Protocol (MTP) interface for MicroPython, enabling filesystem access from host computers via a standard protocol.
4+
5+
## Features
6+
7+
- Implements the Media Transfer Protocol (MTP) based on the PTP/PIMA 15740 Still Image standard
8+
- Compatible with Windows, macOS, and Linux hosts without requiring special drivers
9+
- Exposes MicroPython's filesystem to the host computer
10+
- Supports basic file operations:
11+
- Browsing directories
12+
- Uploading files to the device
13+
- Downloading files from the device
14+
- Deleting files and directories
15+
- Optional debug logging to assist with troubleshooting
16+
17+
## Installation
18+
19+
Install the package using MicroPython's package manager:
20+
21+
```
22+
mpremote mip install usb-device-mtp
23+
```
24+
25+
## Usage
26+
27+
The basic usage pattern is:
28+
29+
```python
30+
import usb.device
31+
from usb.device.mtp import MTPInterface
32+
33+
# Create an MTP interface that exposes a specific path as storage
34+
mtp = MTPInterface(storage_path="/")
35+
36+
# Initialize the USB device with the MTP interface
37+
# Keep builtin_driver=True to maintain the serial REPL alongside MTP
38+
usb.device.get().init(mtp, builtin_driver=True)
39+
40+
# At this point, the MTP interface is available to the host computer
41+
# Your MicroPython filesystem will be accessible via the standard file manager
42+
```
43+
44+
See [mtp_example.py](/examples/device/mtp_example.py) for a complete example program.
45+
46+
## Configuration Options
47+
48+
The `MTPInterface` constructor accepts the following parameters:
49+
50+
- `storage_path`: Root directory to expose via MTP (default: "/")
51+
- `rx_size`: Size of the receive buffer in bytes (default: 4096)
52+
- `tx_size`: Size of the transmit buffer in bytes (default: 4096)
53+
- `debug`: Enable detailed debug logging (default: False)
54+
55+
## Runtime USB Considerations
56+
57+
When running the MTP interface:
58+
59+
1. The device may disconnect temporarily from the host while USB reconfiguration occurs
60+
2. The MicroPython REPL serial interface will remain accessible if you use `builtin_driver=True`
61+
3. If you add the MTP initialization code to `boot.py`, remember to include `builtin_driver=True` to maintain access to the device
62+
63+
## Limitations
64+
65+
- Performance may vary depending on the MicroPython board's USB hardware
66+
- Large file transfers might be slower than with dedicated file transfer tools
67+
- Limited support for MTP events and advanced features
68+
- Only one storage (the specified path) is exposed
69+
70+
## Implementation Details
71+
72+
This driver implements the USB MTP protocol by extending the `Interface` class from `usb.device.core`. It uses the Still Image class (0x06) with the PIMA 15740 protocol (0x01) specification to provide compatibility with standard MTP implementations on host operating systems.
73+
74+
The driver requires three endpoints:
75+
- Bulk OUT endpoint for receiving commands and data
76+
- Bulk IN endpoint for sending data and responses
77+
- Interrupt IN endpoint for sending events (currently unused)
78+
79+
## Debugging
80+
81+
To enable verbose debug logging:
82+
83+
```python
84+
mtp = MTPInterface(storage_path="/", debug=True)
85+
```
86+
87+
This will output detailed information about USB transfers, MTP commands, and filesystem operations, which can be helpful when troubleshooting connection issues.

0 commit comments

Comments
 (0)