Document the MMS USB transport - #14
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a
USB Transportpage 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
1915:D978, recovering the board MAC from the USB serial-number descriptor, typical device paths per OS?identification handshake and how its six fields map onto the Device Information Service characteristics0x1F | length | payload | 0x0A, with three worked byte examplesBtleConnectioncallbacks, for anyone wrapping the C++ SDKEverything 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
0x1Fand0x0Aappear inside payloads regularly. The third worked example is a Readout command whose length byte is0x0A, 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 0x01is 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
MetaWear APIinmkdocs.ymlUSB Connectivitysection on the MetaMotionS page linking through to the specChecked
All 26 internal doc links resolve, including the new anchors into
api-specification.md. Please runmkdocs servelocally to confirm rendering, I was not able to build with the Material theme.