Skip to content

Document the MMS USB transport - #14

Merged
lkasso merged 1 commit into
mainfrom
lkasso/usb-transport-docs
Aug 2, 2026
Merged

Document the MMS USB transport#14
lkasso merged 1 commit into
mainfrom
lkasso/usb-transport-docs

Conversation

@lkasso

@lkasso lkasso commented Aug 2, 2026

Copy link
Copy Markdown
Member

Adds a USB Transport page documenting how the MetaMotionS is controlled over a USB cable instead of Bluetooth.

The MMS has supported USB since 2022 and it has never been documented. Nothing on docs.mbientlab.com mentions it, so the capability has been effectively invisible to customers. This page closes that gap.

The page is written as a transport specification rather than a tutorial, and it is deliberately language-agnostic. Someone should be able to implement a USB driver in any language from this page alone, without reading our SDK source.

What's covered

  • Enumeration: VID:PID 1915:D978, recovering the board MAC from the USB serial-number descriptor, typical device paths per OS
  • Port configuration: 1000000 baud, settle delay, why the buffer flush matters
  • The ? identification handshake and how its six fields map onto the Device Information Service characteristics
  • Frame format 0x1F | length | payload | 0x0A, with three worked byte examples
  • A language-agnostic decoder state machine, plus the chunked-read detail that keeps log downloads from overflowing the input buffer
  • How the transport substitutes for the four BtleConnection callbacks, for anyone wrapping the C++ SDK
  • The full log download sequence over USB
  • Differences from BLE, limitations, and an implementation checklist

Everything above the transport layer is unchanged, so the page links into the existing API Specification for module and register detail rather than duplicating it.

Three details worth a careful read

The length prefix is authoritative, not the delimiters. There is no escaping, and 0x1F and 0x0A appear inside payloads regularly. The third worked example is a Readout command whose length byte is 0x0A, which makes the point more clearly than prose does. Anyone who writes a decoder that scans for the stop byte will fragment packets.

Flush pending writes before a log download. 0x0B 0x10 0x01 is required on the MMS. The board buffers entries in a NAND page cache, and anything still cached at download time is missing from the readout with no error reported. This is the easiest way to silently lose the newest data.

Firmware update over USB is not supported. MetaBoot is detected through the DFU service, which the USB transport does not expose, so DFU stays on BLE. Documented as a limitation rather than left for someone to discover.

Register-level content cross-references the existing API Specification rather than restating it.

Also in this PR

  • Nav entry under MetaWear API in mkdocs.yml
  • Short USB Connectivity section on the MetaMotionS page linking through to the spec

Checked

All 26 internal doc links resolve, including the new anchors into api-specification.md. Please run mkdocs serve locally to confirm rendering, I was not able to build with the Material theme.

@lkasso
lkasso merged commit 34e397f into main Aug 2, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant