# USB Drivers These packages allow implementing USB functionality on a MicroPython system using pure Python code. Currently only USB device is implemented, not USB host. ## USB Device support ### Support 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. However, the packages here are higher level and easier to use. For more information about how to install packages, or "freeze" them into a firmware image, consult the [MicroPython documentation on "Package management"](https://docs.micropython.org/en/latest/reference/packages.html). ### Examples 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)). #### Unexpected serial disconnects 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. If you use `mpremote run` again while a different USB device 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. 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. ### Initialising runtime USB The overall pattern for enabling USB devices at runtime is: 1. Instantiate the Interface objects for your desired USB device. 2. Call `usb.device.get()` to get the singleton object for the high-level USB device. 3. Call `init(...)` to pass the desired interfaces as arguments, plus any custom keyword arguments to configure the overall device. An example, similar to [mouse_example.py](examples/device/mouse_example.py): ```py m = usb.device.mouse.MouseInterface() usb.device.get().init(m, builtin_driver=True) ``` Setting `builtin_driver=True` means that any built-in USB serial port will still be available. Otherwise, you may permanently lose access to MicroPython until the next time the device resets. See [Unexpected serial disconnects](#Unexpected-serial-disconnects), above, for an explanation of possible errors or disconnects when the runtime USB device initialises. 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. This is a feature (not a bug) and allows you full control over the USB device, for example to only enable USB HID and prevent REPL access to the system. 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. ### Package usb-device This base package contains the common implementation components for the other packages, and can be used to implement new and different USB interface support. All of the other `usb-device-` packages depend on this package, and it will be automatically installed as needed. Specicially, this package 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. ### Package usb-device-keyboard This package provides the `usb.device.keyboard` module. See [keyboard_example.py](examples/device/keyboard_example.py) for an example program. ### Package usb-device-mouse This package provides the `usb.device.mouse` module. See [mouse_example.py](examples/device/mouse_example.py) for an example program. ### Package usb-device-hid 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. 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. ### Package usb-device-cdc 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. 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. ### Package usb-device-midi This package provides the `usb.device.midi` module. This allows implementing USB MIDI devices in MicroPython. The example [midi_example.py](examples/device/midi_example.py) demonstrates how to create a simple MIDI device to send MIDI data to and from the USB host. ### Limitations #### Buffer thread safety The internal Buffer class that's used by most of the USB device classes expects data to be written to it (i.e. sent to the host) by only one thread. Bytes may be lost from the USB transfers if more than one thread (or a thread and a callback) try to write to the buffer simultaneously. If writing USB data from multiple sources, your code may need to add synchronisation (i.e. locks).