Skip to content

Commit efaa8a8

Browse files
pi-anlpi-anl
committed
docs/library: Simplify machine.USBDevice documentation.
Remove documentation for features not in this branch: - NCM USB class support - VID/PID runtime properties - Deprecated BUILTIN_CDC_MSC constant Simplify documentation to focus on: - BUILTIN_CDC and BUILTIN_MSC constants - Bitwise OR operator for combining classes - Two basic usage examples Reduces documentation additions from 261 lines to 12 lines. Signed-off-by: Andrew Leech <[email protected]>
1 parent fe4ba61 commit efaa8a8

File tree

1 file changed

+6
-216
lines changed

1 file changed

+6
-216
lines changed

‎docs/library/machine.USBDevice.rst‎

Lines changed: 6 additions & 216 deletions
Original file line numberDiff line numberDiff line change
@@ -198,30 +198,15 @@ Methods
198198
:func:`USBDevice.active` function to deactivate before setting if necessary
199199
(and again to activate after setting).
200200

201-
**Combining Built-in Drivers:**
202-
203-
Multiple built-in USB classes can be enabled simultaneously by combining
204-
constants with the bitwise OR operator::
205-
206-
usb = machine.USBDevice()
207-
usb.active(False)
208-
# Enable both CDC and MSC
209-
usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_MSC
210-
usb.active(True)
211-
212-
The combined configuration will dynamically generate appropriate USB
213-
descriptors containing only the selected classes.
214-
215201
If this value is set to any value other than :data:`USBDevice.BUILTIN_NONE` then
216202
the following restrictions apply to the :func:`USBDevice.config` arguments:
217203

218204
- ``desc_cfg`` should begin with the built-in USB interface descriptor data
219205
accessible via :data:`USBDevice.builtin_driver` attribute ``desc_cfg``.
220-
The descriptor is dynamically generated based on the combination of classes
221-
enabled. Descriptors appended after the built-in configuration descriptors
222-
should use interface, string and endpoint numbers starting from the max
223-
built-in values defined in :data:`USBDevice.builtin_driver` attributes
224-
``itf_max``, ``str_max`` and ``ep_max``.
206+
Descriptors appended after the built-in configuration descriptors should use
207+
interface, string and endpoint numbers starting from the max built-in values
208+
defined in :data:`USBDevice.builtin_driver` attributes ``itf_max``, ``str_max``
209+
and ``ep_max``.
225210

226211
- The ``bNumInterfaces`` field in the built-in configuration
227212
descriptor will also need to be updated if any new interfaces
@@ -305,61 +290,10 @@ Constants
305290
Can be combined with other ``BUILTIN_`` constants using the bitwise
306291
OR operator (``|``).
307292

308-
.. data:: USBDevice.BUILTIN_NCM
309-
310-
Constant representing the built-in USB NCM (network) driver.
311-
Only available when ``MICROPY_HW_NETWORK_USBNET`` is enabled in the
312-
firmware build. Can be combined with other ``BUILTIN_`` constants
313-
using the bitwise OR operator (``|``).
314-
315-
.. note:: When NCM is disabled after being active, the network
316-
interface is automatically cleaned up.
317-
318-
.. data:: USBDevice.BUILTIN_CDC_MSC
319-
320-
.. deprecated::
321-
Use ``USBDevice.BUILTIN_CDC | USBDevice.BUILTIN_MSC`` instead.
322-
323-
Legacy constant for CDC and MSC combination. Provided for backward
324-
compatibility only.
325-
326-
**Combining Built-in Constants:**
327-
328-
Built-in driver constants can be combined using the bitwise OR operator to
329-
create custom USB device configurations::
330-
331-
# CDC serial port only
332-
usb.builtin_driver = USBDevice.BUILTIN_CDC
333-
334-
# CDC and MSC (serial + mass storage)
335-
usb.builtin_driver = USBDevice.BUILTIN_CDC | USBDevice.BUILTIN_MSC
336-
337-
# All available interfaces
338-
usb.builtin_driver = USBDevice.BUILTIN_CDC | USBDevice.BUILTIN_MSC | USBDevice.BUILTIN_NCM
339-
340-
# No built-in drivers (for fully custom USB devices)
341-
usb.builtin_driver = USBDevice.BUILTIN_NONE
342-
343-
The combined configuration dynamically generates the appropriate USB descriptors
344-
and updates the ``itf_max``, ``ep_max``, and ``str_max`` properties accordingly.
345-
346-
Each constant object contains the following read-only fields:
347-
348-
- ``itf_max`` - One more than the highest bInterfaceNumber value used
349-
in the configuration. Dynamically calculated based on enabled classes.
350-
- ``ep_max`` - One more than the highest bEndpointAddress value used
351-
in the configuration. Does not include any ``IN`` flag bit (0x80).
352-
Dynamically calculated based on enabled classes.
353-
- ``str_max`` - One more than the highest string descriptor index
354-
value used by any descriptor. Dynamically calculated.
355-
- ``desc_dev`` - ``bytes`` object containing the USB device descriptor.
356-
- ``desc_cfg`` - ``bytes`` object containing the complete USB
357-
configuration descriptor for the enabled classes.
358-
359293
Usage Examples
360294
--------------
361295

362-
**Basic CDC Serial Port:**
296+
**Enable CDC only:**
363297
::
364298

365299
import machine
@@ -369,158 +303,14 @@ Usage Examples
369303
usb.builtin_driver = usb.BUILTIN_CDC
370304
usb.active(True)
371305

372-
**CDC + Mass Storage:**
373-
::
374-
375-
import machine
376-
377-
usb = machine.USBDevice()
378-
usb.active(False)
379-
usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_MSC
380-
usb.active(True)
381-
382-
**Network Device with Serial Console:**
383-
::
384-
385-
import machine
386-
387-
usb = machine.USBDevice()
388-
usb.active(False)
389-
# Enable both CDC for console and NCM for networking
390-
usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_NCM
391-
usb.active(True)
392-
393-
**Querying Current Configuration:**
394-
::
395-
396-
import machine
397-
398-
usb = machine.USBDevice()
399-
usb.active(False)
400-
usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_MSC
401-
usb.active(True)
402-
403-
# Check if specific class is enabled using bitwise AND
404-
if usb.builtin_driver & usb.BUILTIN_CDC:
405-
print("CDC is enabled")
406-
if usb.builtin_driver & usb.BUILTIN_MSC:
407-
print("MSC is enabled")
408-
409-
# Check for exact configuration using equality
410-
if usb.builtin_driver == (usb.BUILTIN_CDC | usb.BUILTIN_MSC):
411-
print("Both CDC and MSC are enabled")
412-
413-
**Switching Configurations at Runtime:**
306+
**Enable both CDC and MSC:**
414307
::
415308

416309
import machine
417310

418311
usb = machine.USBDevice()
419-
420-
# Start with CDC only
421-
usb.active(False)
422-
usb.builtin_driver = usb.BUILTIN_CDC
423-
usb.active(True)
424-
425-
# Later, add mass storage
426312
usb.active(False)
427313
usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_MSC
428314
usb.active(True)
429315

430-
# Remove MSC, add NCM
431-
usb.active(False)
432-
usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_NCM
433-
usb.active(True)
434-
435-
**Custom VID/PID (Runtime Mode):**
436-
::
437-
438-
import machine
439-
440-
# Create custom device descriptor with your VID/PID
441-
custom_device_desc = bytearray([
442-
18, # bLength
443-
1, # bDescriptorType (Device)
444-
0x00, 0x02, # bcdUSB (USB 2.0)
445-
0x02, # bDeviceClass (CDC)
446-
0x00, # bDeviceSubClass
447-
0x00, # bDeviceProtocol
448-
64, # bMaxPacketSize0
449-
0x34, 0x12, # idVendor (0x1234)
450-
0x78, 0x56, # idProduct (0x5678)
451-
0x00, 0x01, # bcdDevice (1.0)
452-
1, # iManufacturer
453-
2, # iProduct
454-
3, # iSerialNumber
455-
1 # bNumConfigurations
456-
])
457-
458-
usb = machine.USBDevice()
459-
usb.active(False)
460-
usb.config(desc_dev=custom_device_desc)
461-
usb.builtin_driver = usb.BUILTIN_CDC
462-
usb.active(True)
463-
464-
Dynamic VID/PID Configuration
465-
-----------------------------
466-
467-
**Runtime VID/PID Properties (All Modes):**
468-
469-
Both runtime and non-runtime USB device modes support dynamic VID/PID
470-
configuration using simple Python properties:
471-
472-
::
473-
474-
import machine
475-
476-
usb = machine.USBDevice()
477-
usb.active(False)
478-
479-
# Set custom VID/PID dynamically
480-
usb.vid = 0x1234
481-
usb.pid = 0x5678
482-
483-
usb.builtin_driver = usb.BUILTIN_CDC
484-
usb.active(True)
485-
486-
# Check current values
487-
print(f"VID: 0x{usb.vid:04X}, PID: 0x{usb.pid:04X}")
488-
489-
# Reset to firmware defaults
490-
usb.active(False)
491-
usb.vid = 0 # 0 means use builtin default
492-
usb.pid = 0
493-
usb.active(True)
494-
495-
**Build-time VID/PID Override:**
496-
497-
For additional customization, VID/PID defaults can be set at build time
498-
using the ``MICROPY_HW_USB_RUNTIME_VID`` and ``MICROPY_HW_USB_RUNTIME_PID``
499-
macros:
500-
501-
**Override VID/PID at Build Time:**
502-
::
503-
504-
# Build with custom VID/PID
505-
make CFLAGS_EXTRA="-DMICROPY_HW_USB_RUNTIME_VID=0x1234 -DMICROPY_HW_USB_RUNTIME_PID=0x5678"
506-
507-
**Port-specific Configuration:**
508-
::
509-
510-
# In mpconfigport.h or boards/BOARD/mpconfigboard.h
511-
#define MICROPY_HW_USB_RUNTIME_VID (0x1234)
512-
#define MICROPY_HW_USB_RUNTIME_PID (0x5678)
513-
514-
This allows customizing the USB VID/PID defaults even when ``MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE``
515-
is disabled and only built-in drivers are available. If not specified, these
516-
macros default to ``MICROPY_HW_USB_VID`` and ``MICROPY_HW_USB_PID``.
517-
518-
**VID/PID Property Notes:**
519-
520-
- Properties can only be set when ``usb.active`` is ``False``
521-
- Setting VID/PID to ``0`` uses the firmware default value
522-
- Valid range is 1-65535 (0x0001-0xFFFF)
523-
- Custom values persist across active()/inactive() cycles
524-
- Works in both runtime and non-runtime USB device modes
525-
526316
.. _usb driver modules in micropython-lib: https://github.com/micropython/micropython-lib/tree/master/micropython/usb#readme

0 commit comments

Comments
 (0)