Resolve nine internal contradictions in the API spec#7
Merged
Conversation
A careful read found nine places where the spec disagreed with itself — the prose, register tables, worked examples, and wire-level reference giving an implementer conflicting models. Each is resolved in favor of the canonical source (register table / SDK / hardware-verified note), with cross-checks against MetaWear-SDK-Cpp and our fw 1.7.2 testing: - Event workflow examples used a broken entry format (source tuple only); rewritten to source triple + target module/register + param length, with params alone in the 0x03 write. Switch source index 0x00 -> 0xFF. - Logging example: Add Trigger packed byte (offset bits 0-4, length-1 bits 5-7) shown as two separate bytes with an impossible 6-byte entry; now two triggers per 6-byte sample. Readout fixed from 4 bytes to the required 8 (count + notify delta). Wire-reference packed-byte formula was also backwards -> corrected. - Data-processor source table: temperature 0xC1 and GPIO 0x07 fed processors nothing on hardware; corrected to the loud-read forms (0x81 / 0x87 / 0x86) per the read-signal-routing note. - SPI wire-level layout invented separate mode/len/msb/nrf/id bytes and dropped MOSI/MISO; rewritten to the packed config byte matching the register table and both SDKs. - Sensor fusion prose claimed the underlying acc/gyro/mag are configured automatically and must not be configured separately — the opposite of the truth; the host must configure and start them or fusion emits nothing. - Command-format table: "bit 8" -> bit 7, removed a stray vertical-tab control char, and documented bit 6 (data-id/silent) alongside bit 7 in the packet section. - Temperature: channel byte is a 0-based channel index (not a 1-based sensor selector); scale 0.25 C -> 0.125 C, matching the module section. - LED Flash example: little-endian values read as big-endian (0x32 0x00 = 50 ms not 12800; 0xF4 0x01 = 500 ms not 62465). - Module discovery: absent modules DO respond, with a bare 2-byte header (not "do not respond"); detect absence by length, not timeout. mkdocs build --strict passes; all cross-page anchors verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
A careful review found nine places where the spec contradicted itself — prose vs. register table vs. worked example vs. wire-level reference giving implementers conflicting models. Each is resolved toward the canonical source, cross-checked against MetaWear-SDK-Cpp and our firmware-1.7.2 hardware testing.
0x00→0xFF0xC1/GPIO0x07fed processors nothing on HW → loud-read forms0x81/0x87/0x86mkdocs build --strictpasses; all cross-page anchors verified.🤖 Generated with Claude Code