|
| 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