From 75390f9f40e0c1e6662c9af867bf12bc4a8c530e Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:36:19 +0000 Subject: [PATCH 01/24] Refine structured v3 YAML authoring --- components/Protocol/Message.vue | 17 +- components/Protocol/StructuredMessagePage.vue | 2 +- public/files/protocol-v3.yaml | 322 +++++++++--------- utils/ByteStringParser.test.ts | 7 + utils/ByteStringParser.ts | 9 +- utils/MessageDocumentation.test.ts | 40 ++- utils/MessageDocumentation.ts | 23 +- 7 files changed, 241 insertions(+), 179 deletions(-) diff --git a/components/Protocol/Message.vue b/components/Protocol/Message.vue index 823e734b0..b8d6c23fc 100644 --- a/components/Protocol/Message.vue +++ b/components/Protocol/Message.vue @@ -311,6 +311,7 @@ import { readTypedData } from '../../src/protocol/base.gen'; import { formatSentinelValue } from '../../utils/ProtocolSentinels'; import crc16 from 'crc/crc16xmodem'; import { Buffer } from 'buffer'; +import { parseByteString, type ByteStringEncoding } from '../../utils/ByteStringParser'; import Bytes from './Bytes.vue'; interface ByteSection { @@ -340,6 +341,18 @@ export default defineComponent({ type: String, required: true }, + normalizedBytes: { + type: Array as PropType, + default: undefined + }, + encoding: { + type: String as PropType, + default: 'auto' + }, + displayType: { + type: String as PropType<'ints' | 'hex' | 'hex0x' | 'printf'>, + default: 'ints' + }, yamlData: { type: Object as PropType, default: () => ({}) @@ -390,7 +403,7 @@ export default defineComponent({ const isCogModalVisible = ref(false); const isBytesCollapsed = ref(props.defaultCollapsed); - const byteDisplayType = ref<'ints' | 'hex' | 'hex0x' | 'printf'>('ints'); + const byteDisplayType = ref<'ints' | 'hex' | 'hex0x' | 'printf'>(props.displayType); const byteCopySpaces = ref(true); const byteCopyCommas = ref(false); const byteUpperCase = ref(true); @@ -413,6 +426,8 @@ export default defineComponent({ const sectionParseOverrides = ref>({}); const byteArray = computed(() => { + if (props.normalizedBytes) return props.normalizedBytes.map(byte => String(byte)); + if (props.encoding !== 'auto') return parseByteString(props.byteString, props.encoding).bytes.map(byte => String(byte)); const trimmed = props.byteString.trim(); if (!trimmed) return []; diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index b54b6adbd..a8afa2273 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -477,7 +477,7 @@ onBeforeUnmount(() => {
- +
Raw bytes diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index df0ba21a3..9d44503fe 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1467,10 +1467,10 @@ messages: title: GET request description: No payload fields are required. Method must be included; this message does not default to GET. headers: - "1": + 1: presence: optional description: Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 2 response: @@ -1480,23 +1480,23 @@ messages: Returned fields vary by target and available readings. Response To and Status may be omitted when the request has no nonzero Message ID. headers: - "3": + 3: presence: optional - "4": + 4: presence: optional value: 0 fields: - "1": {presence: optional} - "2": {presence: optional} - "3": {presence: optional} - "4": {presence: optional} - "5": {presence: optional} - "6": {presence: optional} - "7": {presence: optional} - "10": {presence: optional} - "12": {presence: optional} - "13": {presence: optional} - "14": {presence: optional} + 1: {presence: optional} + 2: {presence: optional} + 3: {presence: optional} + 4: {presence: optional} + 5: {presence: optional} + 6: {presence: optional} + 7: {presence: optional} + 10: {presence: optional} + 12: {presence: optional} + 13: {presence: optional} + 14: {presence: optional} examples: - title: GET exchange provenance: captured @@ -1508,10 +1508,12 @@ messages: frames: - role: request label: GET request for device status - bytes: 3 20 0 34 0 2 0 5 1 1 2 4 32 98 132 62 0 0 194 229 + encoding: hex + bytes: 03 14 00 22 00 02 00 05 01 01 02 04 20 62 84 3E 00 00 C2 E5 - role: response label: Device status response - bytes: 3 49 0 34 0 2 0 3 4 4 32 98 132 62 1 0 8 0 1 3 7 10 2 4 5 6 1 88 1 0 4 239 8 0 0 1 48 1 64 1 0 2 0 0 2 0 0 108 94 + encoding: hex + bytes: 03 31 00 22 00 02 00 03 04 04 20 62 84 3E 01 00 08 00 01 03 07 0A 02 04 05 06 01 58 01 00 04 EF 08 00 00 01 30 01 40 01 00 02 00 00 02 00 00 6C 5E SUBSCRIBE: title: Subscribe to status updates description: >- @@ -1526,28 +1528,28 @@ messages: the default subscription documented here. Updates are subject to the selected interval and message level. headers: - "1": + 1: presence: optional description: Include a nonzero Message ID if you need a setup acknowledgment. - "5": + 5: presence: required value: 3 - "6": + 6: presence: optional description: Publication interval in milliseconds. Omitted or 0 allows updates as new status data becomes available. - "7": + 7: presence: optional description: Subscription duration in milliseconds. Omitted or 0 keeps the subscription active until unsubscribed. - "8": + 8: presence: optional description: Time in milliseconds to wait for the first matching status update. Omitted or 0 does not set a timeout. - "15": + 15: presence: optional description: Storage/retry policy for publications. Defaults to None (0). - "16": + 16: presence: optional description: Minimum publication level. The default Info-Auto (2) receives normal status updates; no explicit level is required. - "17": + 17: presence: optional value: 0 description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. @@ -1559,9 +1561,9 @@ messages: includes a nonzero Message ID. This acknowledges the request, not delivery of a status update. No acknowledgment is sent for an omitted or zero Message ID. headers: - "3": + 3: presence: required - "4": + 4: presence: required value: 0 publication: @@ -1571,24 +1573,24 @@ messages: interval and level. They are not replies to the original SUBSCRIBE request and do not carry its Response To. Available payload fields vary by target and readings. headers: - "3": + 3: presence: omitted description: A later publication is not correlated to the subscription request. - "4": + 4: presence: omitted description: Status updates carry status data, not a command-result envelope. fields: - "1": {presence: optional} - "2": {presence: optional} - "3": {presence: optional} - "4": {presence: optional} - "5": {presence: optional} - "6": {presence: optional} - "7": {presence: optional} - "10": {presence: optional} - "12": {presence: optional} - "13": {presence: optional} - "14": {presence: optional} + 1: {presence: optional} + 2: {presence: optional} + 3: {presence: optional} + 4: {presence: optional} + 5: {presence: optional} + 6: {presence: optional} + 7: {presence: optional} + 10: {presence: optional} + 12: {presence: optional} + 13: {presence: optional} + 14: {presence: optional} UNSUBSCRIBE: title: Stop the default status subscription description: >- @@ -1599,10 +1601,10 @@ messages: title: UNSUBSCRIBE request description: No payload fields are required. Omit Subscription ID; this operation removes the default subscription only. headers: - "1": + 1: presence: optional description: Include a nonzero Message ID if you need an acknowledgment. - "5": + 5: presence: required value: 5 response: @@ -1613,9 +1615,9 @@ messages: request includes a nonzero Message ID. No acknowledgment is sent for an omitted or zero Message ID. headers: - "3": + 3: presence: required - "4": + 4: presence: required value: 0 35: @@ -1663,10 +1665,10 @@ messages: title: GET request description: No payload fields are required. Include Method GET to request the device identifiers. headers: - "1": + 1: presence: optional description: Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 2 response: @@ -1676,17 +1678,17 @@ messages: available on every device type. Cached SIM2 ICCID is a previously read value and may be stale. headers: - "3": + 3: presence: optional - "4": + 4: presence: optional value: 0 fields: - "1": {presence: optional} - "2": {presence: optional} - "3": {presence: optional} - "4": {presence: optional} - "8": {presence: optional} + 1: {presence: optional} + 2: {presence: optional} + 3: {presence: optional} + 4: {presence: optional} + 8: {presence: optional} examples: - title: GET exchange provenance: captured @@ -1698,10 +1700,12 @@ messages: frames: - role: request label: GET request for device ids - bytes: 3 20 0 35 0 2 0 5 1 1 2 4 31 187 53 226 0 0 191 169 + encoding: hex + bytes: 03 14 00 23 00 02 00 05 01 01 02 04 1F BB 35 E2 00 00 BF A9 - role: response label: Device IDs response - bytes: 3 65 0 35 0 2 0 3 4 4 31 187 53 226 1 0 3 0 1 2 3 4 3 109 161 0 15 56 54 52 57 53 48 48 54 48 50 49 50 53 56 55 20 56 57 52 53 55 51 48 48 48 48 48 48 50 50 50 49 52 56 48 54 6 251 + encoding: hex + bytes: 03 41 00 23 00 02 00 03 04 04 1F BB 35 E2 01 00 03 00 01 02 03 04 03 6D A1 00 0F 38 36 34 39 35 30 30 36 30 32 31 32 35 38 37 14 38 39 34 35 37 33 30 30 30 30 30 30 32 32 32 31 34 38 30 36 06 FB 36: name: Device Time id: deviceTime @@ -1989,19 +1993,19 @@ messages: title: GET request description: No payload fields are needed. headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 2 fields: - "1": + 1: presence: omitted - "2": + 2: presence: omitted - "3": + 3: presence: omitted response: title: GPS state (MT39) @@ -2009,22 +2013,22 @@ messages: A successful GET returns GPS Control directly, with no separate success ACK. An unsuccessful request returns MT5 (ACK) with Status, not this payload. headers: - "3": + 3: presence: optional - "4": + 4: presence: optional value: 0 fields: - "1": + 1: presence: required description: Whether the GPS service is on. - "2": + 2: presence: required description: Whether correction data is enabled. values: - "0": Disabled - "1": Full RTCM stream - "3": + 0: Disabled + 1: Full RTCM stream + 3: presence: omitted description: Start mode is a SET input, not returned state. errors: @@ -2044,18 +2048,18 @@ messages: title: SET request description: Use writable control fields, not the read-only GPS status field. headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 1 fields: - "1": + 1: presence: omitted description: Read-only status. Sending this field in SET is rejected with Invalid Parameter (4). - "2": + 2: presence: optional description: >- Request and apply correction data to the GPS, such as RTK; this automatically controls @@ -2063,18 +2067,18 @@ messages: start-mode-only SET does not preserve the previous correction setting. Include 1 to keep API-enabled corrections on. values: - "0": Disabled - "1": Full RTCM stream - "3": + 0: Disabled + 1: Full RTCM stream + 3: presence: optional description: >- If GPS is enabled, reboot it in this mode. If it is disabled, enable it with the requested state. values: - "1": Normal - "2": Cold - "3": Warm - "4": Hot + 1: Normal + 2: Cold + 3: Warm + 4: Hot response: messageId: 5 title: Response (MT5 - ACK) @@ -2082,13 +2086,13 @@ messages: For a request with a nonzero Message ID, successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. headers: - "3": + 3: presence: optional - "4": + 4: presence: required value: 0 fields: - "1": + 1: presence: required value: 39 description: >- @@ -3411,14 +3415,14 @@ messages: title: GET request description: No payload fields are needed. headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 2 - "22": + 22: presence: required maxBytes: 1 value: 2 @@ -3429,26 +3433,26 @@ messages: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with Status instead. headers: - "3": + 3: presence: optional - "4": + 4: presence: optional value: 0 - "22": + 22: presence: required maxBytes: 1 value: 2 description: Identifies the format of this response payload. fields: - "1": + 1: presence: omitted description: The legacy additive checksum is absent from version 2 responses. - "2": + 2: presence: required description: >- Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- or two-byte little-endian encoding may omit a high zero byte. - "129": + 129: presence: optional maxBytes: 1024 description: >- @@ -3461,76 +3465,76 @@ messages: title: GET request description: No payload fields are needed. headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 2 - "22": + 22: presence: optional maxBytes: 1 description: >- Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: - "0": Version 1 (also the omitted/malformed-width fallback) - "1": Version 1 + 0: Version 1 (also the omitted/malformed-width fallback) + 1: Version 1 response: title: Legacy cached payload description: >- A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with Status instead. headers: - "3": + 3: presence: optional - "4": + 4: presence: optional value: 0 - "22": + 22: presence: omitted description: >- Legacy version 1 responses retain their original wire layout and omit Message Version. fields: - "1": + 1: presence: required description: "Additive checksum: sum of all cached payload bytes modulo 65536." - "2": + 2: presence: omitted description: The CRC field belongs to version 2. - "10": + 10: presence: optional maxBytes: 255 description: >- Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is omitted. - "11": + 11: presence: optional maxBytes: 255 description: >- Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is omitted. - "12": + 12: presence: optional maxBytes: 255 description: >- Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is omitted. - "13": + 13: presence: optional maxBytes: 255 description: >- Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is omitted. - "14": + 14: presence: optional maxBytes: 255 description: >- Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload data is omitted. - "129": + 129: presence: omitted description: >- Version 1 retains the legacy wire layout; it does not include the extended @@ -3550,20 +3554,20 @@ messages: outer message-frame CRC protects the SET request itself. Optional supplied checksum fields 1 and 2 are ignored. headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 1 - "22": + 22: presence: required maxBytes: 1 value: 2 description: A one-byte value of 2 selects version 2. fields: - "129": + 129: presence: required maxBytes: 1024 description: >- @@ -3577,13 +3581,13 @@ messages: the cached bytes; subscriber publications are separate asynchronous messages and are not this reply. headers: - "3": + 3: presence: optional - "4": + 4: presence: required value: 0 fields: - "1": + 1: presence: required value: 58 description: >- @@ -3616,13 +3620,13 @@ messages: reason. Updates arrive as asynchronous MT58 publications, not as direct replies to SUBSCRIBE. headers: - "3": + 3: presence: optional - "4": + 4: presence: required value: 0 fields: - "1": + 1: presence: required value: 58 description: >- @@ -3642,32 +3646,32 @@ messages: request: title: SUBSCRIBE request headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 3 - "6": + 6: presence: optional description: >- Optional publication interval in milliseconds. If omitted, updates are sent when new data is available. - "7": + 7: presence: optional description: >- Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. - "16": + 16: presence: optional description: Minimum publication level. - "17": + 17: presence: optional description: >- Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. - "22": + 22: presence: required maxBytes: 1 value: 2 @@ -3678,27 +3682,27 @@ messages: Version 2 updates include Message Version 2 and field 2. Field 129 carries the complete cached payload when nonempty; empty payload data is omitted. headers: - "3": + 3: presence: omitted description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - "17": + 17: presence: optional description: Identifies nonzero subscription IDs for this publication. - "22": + 22: presence: required maxBytes: 1 value: 2 description: A one-byte value of 2 selects version 2. fields: - "1": + 1: presence: omitted description: The legacy additive checksum is absent from version 2 responses. - "2": + 2: presence: required description: >- Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- or two-byte little-endian encoding may omit a high zero byte. - "129": + 129: presence: optional maxBytes: 1024 description: >- @@ -3712,95 +3716,95 @@ messages: request: title: SUBSCRIBE request headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 3 - "6": + 6: presence: optional description: >- Optional publication interval in milliseconds. If omitted, updates are sent when new data is available. - "7": + 7: presence: optional description: >- Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. - "16": + 16: presence: optional description: Minimum publication level. - "17": + 17: presence: optional description: >- Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. - "22": + 22: presence: optional maxBytes: 1 description: >- Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: - "0": Version 1 (also the omitted/malformed-width fallback) - "1": Version 1 + 0: Version 1 (also the omitted/malformed-width fallback) + 1: Version 1 publication: title: Legacy cached payload update description: >- Version 1 updates use the additive checksum and legacy chunks. Empty payload data is omitted. headers: - "3": + 3: presence: omitted description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - "17": + 17: presence: optional description: Identifies nonzero subscription IDs for this publication. - "22": + 22: presence: omitted description: >- Legacy version 1 responses retain their original wire layout and omit Message Version. fields: - "1": + 1: presence: required description: "Additive checksum: sum of all cached payload bytes modulo 65536." - "2": + 2: presence: omitted description: The CRC field belongs to version 2. - "10": + 10: presence: optional maxBytes: 255 description: >- Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is omitted. - "11": + 11: presence: optional maxBytes: 255 description: >- Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is omitted. - "12": + 12: presence: optional maxBytes: 255 description: >- Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is omitted. - "13": + 13: presence: optional maxBytes: 255 description: >- Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is omitted. - "14": + 14: presence: optional maxBytes: 255 description: >- Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload data is omitted. - "129": + 129: presence: omitted description: >- Version 1 retains the legacy wire layout; it does not include the extended @@ -3815,17 +3819,17 @@ messages: title: UNSUBSCRIBE request description: No payload fields are needed. headers: - "1": + 1: presence: optional description: >- Include a nonzero Message ID to correlate the reply. - "5": + 5: presence: required value: 5 - "17": + 17: presence: optional description: Use the Subscription ID to remove, or omit it for the default subscription (0). - "22": + 22: presence: ignored description: UNSUBSCRIBE does not select or reset the publication format. response: @@ -3837,13 +3841,13 @@ messages: are suppressed for an omitted or zero Message ID; error ACKs are not suppressed for this reason. headers: - "3": + 3: presence: optional - "4": + 4: presence: required value: 0 fields: - "1": + 1: presence: required value: 58 description: >- @@ -3871,18 +3875,18 @@ messages: for an empty cache. Independent upload bytes in field 129 do not form part of that cached-message CRC. headers: - "22": + 22: presence: required maxBytes: 1 value: 2 description: A one-byte value of 2 selects version 2. fields: - "2": + 2: presence: optional description: >- Present when Message Box support is enabled: CRC-16/XMODEM of the cached down-synced message, not a checksum of the upload in field 129. Zero for an empty cache. - "129": + 129: presence: optional description: >- Independent Transmit Now upload data; do not compare its CRC with field 2 to validate diff --git a/utils/ByteStringParser.test.ts b/utils/ByteStringParser.test.ts index 74f68c062..a4fccd0d7 100644 --- a/utils/ByteStringParser.test.ts +++ b/utils/ByteStringParser.test.ts @@ -2,6 +2,13 @@ import { describe, it, expect } from '@jest/globals'; import { parseByteString, formatBytes, detectNonMessagePatterns } from './ByteStringParser'; describe('ByteStringParser', () => { + it('uses an explicit encoding to parse all-digit hex without decimal guessing', () => { + const hex = parseByteString('03 20 00 22 00 02 00 05', 'hex') + const decimal = parseByteString('3 32 0 34 0 2 0 5', 'decimal') + expect(hex.bytes).toEqual([3, 32, 0, 34, 0, 2, 0, 5]) + expect(decimal.bytes).toEqual(hex.bytes) + expect(parseByteString('03 20 00 22 00 02 00 05', 'hex').hasHex).toBe(true) + }) describe('parseByteString', () => { describe('decimal mode', () => { it('should parse simple space-separated integers', () => { diff --git a/utils/ByteStringParser.ts b/utils/ByteStringParser.ts index e9527ca51..42434b34f 100644 --- a/utils/ByteStringParser.ts +++ b/utils/ByteStringParser.ts @@ -8,6 +8,8 @@ export interface ParsedBytes { hasHex: boolean; } +export type ByteStringEncoding = 'auto' | 'decimal' | 'hex'; + /** * Extract valid byte values (0-255) from any input string. * Handles messy input with random text, hex values, and decimal integers. @@ -27,11 +29,16 @@ export interface ParsedBytes { * @param input - Raw input string potentially containing bytes * @returns Object with parsed bytes array and hex detection flag */ -export function parseByteString(input: string): ParsedBytes { +export function parseByteString(input: string, encoding: ByteStringEncoding = 'auto'): ParsedBytes { if (!input || !input.trim()) { return { bytes: [], hasHex: false }; } + // Explicit encodings are used by structured documentation. Auto remains + // available for the general-purpose log parser used elsewhere in the UI. + if (encoding === 'decimal') return parseDecimalBytes(input); + if (encoding === 'hex') return parseHexBytes(input); + // Check if input looks like base64 first if (looksLikeBase64(input)) { const decoded = tryDecodeBase64(input); diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 2b9aead13..5a7c65d9e 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -89,6 +89,8 @@ describe('shared response conventions', () => { it('keeps explicit exceptions and non-OK status rules local', () => { expect(commonResponseHeaderIds({ headers: { '3': { presence: 'omitted' }, '4': { presence: 'required', value: 4 } } })).toEqual([]) expect(commonResponseHeaderIds({ headers: { '3': { presence: 'optional', description: 'A message-specific correlation rule.' }, '4': { presence: 'required', value: 0, maxBytes: 1 } } })).toEqual([]) + expect(commonResponseHeaderIds({ headers: { '3': { presence: 'ignored' }, '4': { value: 0 } } })).toEqual(['4']) + expect(commonResponseHeaderIds({ headers: { '3': {}, '4': { value: 0 } } })).toEqual(['3', '4']) }) it('keeps MT58 version/payload rules and explicit publication correlation distinct', () => { const message = getMessageDocumentation(protocol.messages[58])! @@ -142,7 +144,8 @@ describe('optional message documentation', () => { expect(protocol.header[5]).toEqual(before) const fields = resolveDocumentationFields(protocol, protocol.messages[39], { 1: {} }, 'fields') expect(fields[0].description).toBe(protocol.messages[39].data[1].description) - expect(fields[0].presence).toBeUndefined() // readonly does not imply required + expect(fields[0].presence).toBe('optional') // listed fields default to optional; readonly alone is not required + expect(resolveDocumentationFields(protocol, protocol.messages[39], {}, 'fields')).toEqual([]) // unlisted fields are not added to this exchange const ack = resolveDocumentationFields(protocol, protocol.messages[5], { 1: {} }, 'fields') expect(ack[0].name).toBe(protocol.messages[5].data[1].name) expect(ack[0].name).not.toBe(protocol.messages[58].data[1].name) @@ -413,6 +416,7 @@ describe('Device Status reference', () => { expect(unsubscribe.response?.messageId).toBe(5) expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') expect(subscribe.request?.headers?.['17']).toMatchObject({ presence: 'optional', value: 0 }) + expect(subscribe.publication?.headers?.['4'].presence).toBe('omitted') expect(unsubscribe.request?.headers?.['17']).toBeUndefined() for (const context of [get.response, subscribe.publication]) { expect(Object.keys(context!.fields!)).toEqual(Object.keys(message.data)) @@ -428,10 +432,12 @@ describe('Device Status reference', () => { expect(example.target).toBe('RH2 over I2C') expect(example.frames.map(frame => frame.role)).toEqual(['request', 'response']) expect(example.frames.map(frame => frame.bytes)).toEqual([ - '3 20 0 34 0 2 0 5 1 1 2 4 32 98 132 62 0 0 194 229', - '3 49 0 34 0 2 0 3 4 4 32 98 132 62 1 0 8 0 1 3 7 10 2 4 5 6 1 88 1 0 4 239 8 0 0 1 48 1 64 1 0 2 0 0 2 0 0 108 94', + '03 14 00 22 00 02 00 05 01 01 02 04 20 62 84 3E 00 00 C2 E5', + '03 31 00 22 00 02 00 03 04 04 20 62 84 3E 01 00 08 00 01 03 07 0A 02 04 05 06 01 58 01 00 04 EF 08 00 00 01 30 01 40 01 00 02 00 00 02 00 00 6C 5E', ]) - const frames = example.frames.map(frame => frame.bytes.split(' ').map(Number)) + expect(example.frames.every(frame => frame.encoding === 'hex')).toBe(true) + expect(example.frames[0].normalizedBytes).toEqual([3, 20, 0, 34, 0, 2, 0, 5, 1, 1, 2, 4, 32, 98, 132, 62, 0, 0, 194, 229]) + const frames = example.frames.map(frame => frame.normalizedBytes!) for (const bytes of frames) { expect(calculateCRC16XMODEM(bytes.slice(0, -2))).toBe(bytes[bytes.length - 2] | bytes[bytes.length - 1] << 8) expect(parseRawMessage(bytes)).toMatchObject({ protocolVersion: 3, length: bytes.length, messageType: 34 }) @@ -455,13 +461,13 @@ describe('Device Status reference', () => { expect(capturedDocumentationValues(example, 58, message.data)).toEqual([]) expect(capturedDocumentationValues(example, 34, message.data, 2)).toEqual([]) const invalid = clone(example) - invalid.frames[1].bytes += ' 0' + invalid.frames[1].normalizedBytes!.push(0) expect(capturedDocumentationValues(invalid, 34, message.data)).toEqual([]) - const bytes = example.frames[1].bytes.split(' ').map(Number) + const bytes = [...example.frames[1].normalizedBytes!] bytes[26] = 255 // Invalid first payload length, even with a recomputed checksum. const crc = calculateCRC16XMODEM(bytes.slice(0, -2)) bytes.splice(-2, 2, crc & 255, crc >> 8) - invalid.frames[1].bytes = bytes.join(' ') + invalid.frames[1].normalizedBytes = bytes expect(capturedDocumentationValues(invalid, 34, message.data)).toEqual([]) const badType = { ...message.data, 7: { ...message.data[7], type: 'uint8' } } expect(capturedDocumentationValues(example, 34, badType).some(field => field.id === 7)).toBe(false) @@ -493,6 +499,19 @@ describe('Device IDs reference', () => { expect(message.examples).toBeUndefined() expect(validateMessageDocumentation(protocol, 35)).toEqual([]) }) + it('normalizes the original captured ID exchange and verifies its CRC', () => { + const [example] = get.examples! + expect(example.provenance).toBe('captured') + expect(example.frames.every(frame => frame.encoding === 'hex')).toBe(true) + expect(example.frames[0].normalizedBytes).toEqual([3, 20, 0, 35, 0, 2, 0, 5, 1, 1, 2, 4, 31, 187, 53, 226, 0, 0, 191, 169]) + const [request, response] = example.frames.map(frame => frame.normalizedBytes!) + for (const bytes of [request, response]) { + expect(calculateCRC16XMODEM(bytes.slice(0, -2))).toBe(bytes[bytes.length - 2] | bytes[bytes.length - 1] << 8) + expect(parseRawMessage(bytes)).toMatchObject({ protocolVersion: 3, length: bytes.length, messageType: 35 }) + } + expect(parseRawMessage(request).data).toEqual({}) + expect(Object.keys(parseRawMessage(response).data)).toEqual(['1', '2', '3']) + }) it('preserves and decodes the captured GET pair without inventing serial or SIM2 samples', () => { const [example] = get.examples! @@ -502,11 +521,8 @@ describe('Device IDs reference', () => { expect(example.description).toContain('RH2 P1 v2287') expect(example.target).toBe('RH2 over I2C') expect(example.frames.map(frame => frame.role)).toEqual(['request', 'response']) - expect(example.frames.map(frame => frame.bytes)).toEqual([ - '3 20 0 35 0 2 0 5 1 1 2 4 31 187 53 226 0 0 191 169', - '3 65 0 35 0 2 0 3 4 4 31 187 53 226 1 0 3 0 1 2 3 4 3 109 161 0 15 56 54 52 57 53 48 48 54 48 50 49 50 53 56 55 20 56 57 52 53 55 51 48 48 48 48 48 48 50 50 50 49 52 56 48 54 6 251', - ]) - const frames = example.frames.map(frame => frame.bytes.split(' ').map(Number)) + expect(example.frames.every(frame => frame.encoding === 'hex')).toBe(true) + const frames = example.frames.map(frame => frame.normalizedBytes!) for (const bytes of frames) { expect(calculateCRC16XMODEM(bytes.slice(0, -2))).toBe(bytes[bytes.length - 2] | bytes[bytes.length - 1] << 8) expect(parseRawMessage(bytes)).toMatchObject({ protocolVersion: 3, length: bytes.length, messageType: 35 }) diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index 92e288521..ca6384863 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -1,5 +1,5 @@ import { calculateCRC16XMODEM, getElementByteSize, parseRawMessage, readTypedData } from '../src/protocol/base.gen' -import { parseByteString } from './ByteStringParser' +import { parseByteString, type ByteStringEncoding } from './ByteStringParser' import { formatSentinelValue } from './ProtocolSentinels' /** Structured message documentation. Wire definitions remain in header and message.data. */ @@ -24,7 +24,7 @@ export interface DocumentationContext { export function commonResponseHeaderIds(context: DocumentationContext): string[] { return Object.entries(context.headers || {}).filter(([id, field]) => { if (field.description || field.values || field.maxBytes !== undefined || - !['required', 'optional'].includes(field.presence || '')) return false + !['required', 'optional', undefined].includes(field.presence)) return false return id === '3' && field.value === undefined || id === '4' && field.value === 0 }).map(([id]) => id) } @@ -34,7 +34,17 @@ export interface DocumentationExample { provenance: 'generated' | 'captured' description?: string target?: string - frames: { role: 'request' | 'response' | 'publication' | 'upload'; label: string; bytes: string }[] + frames: { role: 'request' | 'response' | 'publication' | 'upload'; label: string; bytes: string; encoding?: ByteStringEncoding; normalizedBytes?: number[] }[] +} + +function normalizeDocumentationExamples(examples: DocumentationExample[] = []): DocumentationExample[] { + return examples.map(example => ({ + ...example, + frames: example.frames.map(frame => ({ + ...frame, + normalizedBytes: parseByteString(frame.bytes, frame.encoding || 'auto').bytes, + })), + })) } /** Align each exchange stage without changing frame order or published anchors. */ @@ -53,7 +63,7 @@ export function capturedDocumentationValues(example: DocumentationExample, messa if (example.provenance !== 'captured') return [] return example.frames.flatMap(frame => { try { - const { bytes } = parseByteString(frame.bytes) + const bytes = frame.normalizedBytes ?? parseByteString(frame.bytes, frame.encoding || 'auto').bytes const start = bytes[0] === 0x4c && bytes[1] === 0x42 ? 2 : 0 const parsed = parseRawMessage(bytes) if (parsed.protocolVersion !== 3 || parsed.messageType !== messageId || parsed.encrypted || parsed.length !== bytes.length - start) return [] @@ -182,6 +192,7 @@ export function getMessageDocumentation(message: any): MessageDocumentation | un const addOperation = (id: string, source: any, method?: string) => { if (!source || (!source.exchange && !source.versions)) return const contextualDescriptions = (exchange: any) => Object.fromEntries(Object.entries(exchange || {}).map(([key, value]: [string, any]) => { + if (key === 'examples') return [key, normalizeDocumentationExamples(value)] if (!['request', 'response'].includes(key) || !value?.fields || value.messageId !== undefined) return [key, value] return [key, { ...value, fields: Object.fromEntries(Object.entries(value.fields).map(([id, usage]: [string, any]) => [ id, { description: source[key]?.[id]?.description, ...usage }, @@ -251,7 +262,9 @@ export function resolveDocumentationFields( sentinels: definition.sentinels, baseDescription: definition.description || '', description: context.description ?? definition.description ?? '', - presence: context.presence, + // Only entries explicitly listed in an exchange context are shown; + // absent presence on such an entry means optional, not forbidden. + presence: context.presence ?? 'optional', value: context.value, valueName: context.value === undefined ? undefined : definition.values?.[context.value]?.name, values: Object.entries(context.values ?? (context.value === undefined ? definition.values || {} : {})).map(([value, details]: [string, any]) => ({ From c3dfa4060511f77904f2ef0d5d137753acaa5189 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:36:35 +0000 Subject: [PATCH 02/24] Remove redundant v3 exchange metadata --- public/files/protocol-v3.yaml | 144 ++++++++--------------------- utils/MessageDocumentation.test.ts | 84 ++++++++++++++++- 2 files changed, 116 insertions(+), 112 deletions(-) diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 9d44503fe..2d6e75bd0 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1468,7 +1468,6 @@ messages: description: No payload fields are required. Method must be included; this message does not default to GET. headers: 1: - presence: optional description: Include a nonzero Message ID to correlate the reply. 5: presence: required @@ -1480,23 +1479,21 @@ messages: Returned fields vary by target and available readings. Response To and Status may be omitted when the request has no nonzero Message ID. headers: - 3: - presence: optional + 3: {} 4: - presence: optional value: 0 fields: - 1: {presence: optional} - 2: {presence: optional} - 3: {presence: optional} - 4: {presence: optional} - 5: {presence: optional} - 6: {presence: optional} - 7: {presence: optional} - 10: {presence: optional} - 12: {presence: optional} - 13: {presence: optional} - 14: {presence: optional} + 1: {} + 2: {} + 3: {} + 4: {} + 5: {} + 6: {} + 7: {} + 10: {} + 12: {} + 13: {} + 14: {} examples: - title: GET exchange provenance: captured @@ -1529,28 +1526,21 @@ messages: interval and message level. headers: 1: - presence: optional description: Include a nonzero Message ID if you need a setup acknowledgment. 5: presence: required value: 3 6: - presence: optional description: Publication interval in milliseconds. Omitted or 0 allows updates as new status data becomes available. 7: - presence: optional description: Subscription duration in milliseconds. Omitted or 0 keeps the subscription active until unsubscribed. 8: - presence: optional description: Time in milliseconds to wait for the first matching status update. Omitted or 0 does not set a timeout. 15: - presence: optional description: Storage/retry policy for publications. Defaults to None (0). 16: - presence: optional description: Minimum publication level. The default Info-Auto (2) receives normal status updates; no explicit level is required. 17: - presence: optional value: 0 description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. response: @@ -1580,17 +1570,17 @@ messages: presence: omitted description: Status updates carry status data, not a command-result envelope. fields: - 1: {presence: optional} - 2: {presence: optional} - 3: {presence: optional} - 4: {presence: optional} - 5: {presence: optional} - 6: {presence: optional} - 7: {presence: optional} - 10: {presence: optional} - 12: {presence: optional} - 13: {presence: optional} - 14: {presence: optional} + 1: {} + 2: {} + 3: {} + 4: {} + 5: {} + 6: {} + 7: {} + 10: {} + 12: {} + 13: {} + 14: {} UNSUBSCRIBE: title: Stop the default status subscription description: >- @@ -1602,7 +1592,6 @@ messages: description: No payload fields are required. Omit Subscription ID; this operation removes the default subscription only. headers: 1: - presence: optional description: Include a nonzero Message ID if you need an acknowledgment. 5: presence: required @@ -1666,7 +1655,6 @@ messages: description: No payload fields are required. Include Method GET to request the device identifiers. headers: 1: - presence: optional description: Include a nonzero Message ID to correlate the reply. 5: presence: required @@ -1678,17 +1666,15 @@ messages: available on every device type. Cached SIM2 ICCID is a previously read value and may be stale. headers: - 3: - presence: optional + 3: {} 4: - presence: optional value: 0 fields: - 1: {presence: optional} - 2: {presence: optional} - 3: {presence: optional} - 4: {presence: optional} - 8: {presence: optional} + 1: {} + 2: {} + 3: {} + 4: {} + 8: {} examples: - title: GET exchange provenance: captured @@ -1994,7 +1980,6 @@ messages: description: No payload fields are needed. headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: @@ -2013,10 +1998,8 @@ messages: A successful GET returns GPS Control directly, with no separate success ACK. An unsuccessful request returns MT5 (ACK) with Status, not this payload. headers: - 3: - presence: optional + 3: {} 4: - presence: optional value: 0 fields: 1: @@ -2025,9 +2008,6 @@ messages: 2: presence: required description: Whether correction data is enabled. - values: - 0: Disabled - 1: Full RTCM stream 3: presence: omitted description: Start mode is a SET input, not returned state. @@ -2049,7 +2029,6 @@ messages: description: Use writable control fields, not the read-only GPS status field. headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: @@ -2060,25 +2039,15 @@ messages: presence: omitted description: Read-only status. Sending this field in SET is rejected with Invalid Parameter (4). 2: - presence: optional description: >- Request and apply correction data to the GPS, such as RTK; this automatically controls the GPS module. Omitting this field sets API-enabled corrections to disabled, so a start-mode-only SET does not preserve the previous correction setting. Include 1 to keep API-enabled corrections on. - values: - 0: Disabled - 1: Full RTCM stream 3: - presence: optional description: >- If GPS is enabled, reboot it in this mode. If it is disabled, enable it with the requested state. - values: - 1: Normal - 2: Cold - 3: Warm - 4: Hot response: messageId: 5 title: Response (MT5 - ACK) @@ -2086,8 +2055,7 @@ messages: For a request with a nonzero Message ID, successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. headers: - 3: - presence: optional + 3: {} 4: presence: required value: 0 @@ -3416,7 +3384,6 @@ messages: description: No payload fields are needed. headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: @@ -3433,10 +3400,8 @@ messages: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with Status instead. headers: - 3: - presence: optional + 3: {} 4: - presence: optional value: 0 22: presence: required @@ -3453,7 +3418,6 @@ messages: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- or two-byte little-endian encoding may omit a high zero byte. 129: - presence: optional maxBytes: 1024 description: >- Complete cached payload in an extended-length field with a uint16 little-endian @@ -3466,14 +3430,12 @@ messages: description: No payload fields are needed. headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: presence: required value: 2 22: - presence: optional maxBytes: 1 description: >- Omitted, explicitly 0, or malformed-width values resolve to 0 and select version @@ -3487,10 +3449,8 @@ messages: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with Status instead. headers: - 3: - presence: optional + 3: {} 4: - presence: optional value: 0 22: presence: omitted @@ -3505,31 +3465,26 @@ messages: presence: omitted description: The CRC field belongs to version 2. 10: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is omitted. 11: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is omitted. 12: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is omitted. 13: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is omitted. 14: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty @@ -3555,7 +3510,6 @@ messages: Optional supplied checksum fields 1 and 2 are ignored. headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: @@ -3581,8 +3535,7 @@ messages: the cached bytes; subscriber publications are separate asynchronous messages and are not this reply. headers: - 3: - presence: optional + 3: {} 4: presence: required value: 0 @@ -3620,8 +3573,7 @@ messages: reason. Updates arrive as asynchronous MT58 publications, not as direct replies to SUBSCRIBE. headers: - 3: - presence: optional + 3: {} 4: presence: required value: 0 @@ -3647,27 +3599,22 @@ messages: title: SUBSCRIBE request headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: presence: required value: 3 6: - presence: optional description: >- Optional publication interval in milliseconds. If omitted, updates are sent when new data is available. 7: - presence: optional description: >- Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. 16: - presence: optional description: Minimum publication level. 17: - presence: optional description: >- Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. @@ -3686,7 +3633,6 @@ messages: presence: omitted description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. 17: - presence: optional description: Identifies nonzero subscription IDs for this publication. 22: presence: required @@ -3703,7 +3649,6 @@ messages: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- or two-byte little-endian encoding may omit a high zero byte. 129: - presence: optional maxBytes: 1024 description: >- Complete cached payload in an extended-length field with a uint16 little-endian @@ -3717,32 +3662,26 @@ messages: title: SUBSCRIBE request headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: presence: required value: 3 6: - presence: optional description: >- Optional publication interval in milliseconds. If omitted, updates are sent when new data is available. 7: - presence: optional description: >- Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. 16: - presence: optional description: Minimum publication level. 17: - presence: optional description: >- Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. 22: - presence: optional maxBytes: 1 description: >- Omitted, explicitly 0, or malformed-width values resolve to 0 and select version @@ -3760,7 +3699,6 @@ messages: presence: omitted description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. 17: - presence: optional description: Identifies nonzero subscription IDs for this publication. 22: presence: omitted @@ -3775,31 +3713,26 @@ messages: presence: omitted description: The CRC field belongs to version 2. 10: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is omitted. 11: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is omitted. 12: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is omitted. 13: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is omitted. 14: - presence: optional maxBytes: 255 description: >- Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty @@ -3820,14 +3753,12 @@ messages: description: No payload fields are needed. headers: 1: - presence: optional description: >- Include a nonzero Message ID to correlate the reply. 5: presence: required value: 5 17: - presence: optional description: Use the Subscription ID to remove, or omit it for the default subscription (0). 22: presence: ignored @@ -3841,8 +3772,7 @@ messages: are suppressed for an omitted or zero Message ID; error ACKs are not suppressed for this reason. headers: - 3: - presence: optional + 3: {} 4: presence: required value: 0 @@ -3882,12 +3812,10 @@ messages: description: A one-byte value of 2 selects version 2. fields: 2: - presence: optional description: >- Present when Message Box support is enabled: CRC-16/XMODEM of the cached down-synced message, not a checksum of the upload in field 129. Zero for an empty cache. 129: - presence: optional description: >- Independent Transmit Now upload data; do not compare its CRC with field 2 to validate the upload. diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 5a7c65d9e..33cc4be13 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -98,7 +98,9 @@ describe('shared response conventions', () => { const subscribe = getOperationVariant(message.operations.find(operation => operation.method === 'SUBSCRIBE')!, '2') expect(commonResponseHeaderIds(get.response!)).toEqual(['3', '4']) expect(get.response?.headers?.['22']).toMatchObject({ presence: 'required', value: 2 }) - expect(get.response?.fields?.['129']).toMatchObject({ presence: 'optional', maxBytes: 1024 }) + expect(get.response?.fields?.['129']).toMatchObject({ maxBytes: 1024 }) + expect(get.response?.fields?.['129'].presence).toBeUndefined() + expect(resolveDocumentationFields(protocol, protocol.messages[58], get.response?.fields, 'fields').find(field => field.id === 129)?.presence).toBe('optional') expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') }) it('corrects only the Processing display label, preserving the existing SDK identifier', () => { @@ -371,6 +373,76 @@ describe('inline numeric-version authoring', () => { }) }) +describe('migrated exchange authoring audit', () => { + const migratedIds = [34, 35, 39, 58] + const normalized = (value: unknown) => typeof value === 'string' ? value.trim().replace(/\s+/g, ' ') : value + + it('does not restate optional presence or inherited metadata in exchange maps', () => { + const inspectExchange = (message: any, exchange: any) => { + if (!exchange || typeof exchange !== 'object') return + for (const role of ['request', 'response', 'publication']) { + const context = exchange[role] + if (!context || typeof context !== 'object') continue + const contextMessage = context.messageId === undefined ? message : protocol.messages[context.messageId] + for (const kind of ['headers', 'fields'] as const) { + const definitions = kind === 'headers' ? protocol.header : contextMessage?.data + for (const [id, usage] of Object.entries(context[kind] || {}) as [string, any][]) { + const definition = definitions?.[id] + expect(usage.presence).not.toBe('optional') + if (!definition) continue + for (const key of ['description', 'name', 'id', 'type', 'unit', 'maxBytes']) { + if (usage[key] !== undefined && definition[key] !== undefined) { + expect(normalized(usage[key])).not.toBe(normalized(definition[key])) + } + } + for (const [value, override] of Object.entries(usage.values || {}) as [string, any][]) { + const inherited = definition.values?.[value] + if (!inherited) continue + const inheritedName = typeof inherited === 'string' ? inherited : inherited.name + const inheritedDescription = typeof inherited === 'string' ? undefined : inherited.description + const localDescription = typeof override === 'string' ? override : override?.description + if (typeof override === 'string') expect(normalized(override)).not.toBe(normalized(inheritedName)) + if (override?.name !== undefined) expect(normalized(override.name)).not.toBe(normalized(inheritedName)) + if (localDescription !== undefined && inheritedDescription !== undefined) { + expect(normalized(localDescription)).not.toBe(normalized(inheritedDescription)) + } + if (localDescription !== undefined) expect(normalized(localDescription)).not.toBe(normalized(inheritedName)) + } + } + } + } + } + const inspectSource = (message: any, source: any) => { + if (!source || typeof source !== 'object') return + if (source.exchange) inspectExchange(message, source.exchange) + for (const exchange of Object.values(source.versions || {})) inspectExchange(message, exchange) + } + + for (const id of migratedIds) { + const message = protocol.messages[id] + for (const source of Object.values(message.methods || {})) inspectSource(message, source) + for (const source of Object.values(message.contexts || {})) inspectSource(message, source) + } + }) + + it('inherits global field names, descriptions and enum labels without changing their rendered values', () => { + const gps = protocol.messages[39] + const [gpsField] = resolveDocumentationFields(protocol, gps, { 2: {} }, 'fields') + const gpsDefinition = gps.data[2] + expect(gpsField.name).toBe(gpsDefinition.name) + expect(gpsField.description).toBe(gpsDefinition.description) + expect(gpsField.values.map(({ value, name, description }: any) => ({ value, name, description }))).toEqual([ + { value: 0, name: gpsDefinition.values[0].name, description: gpsDefinition.values[0].description || '' }, + { value: 1, name: gpsDefinition.values[1].name, description: gpsDefinition.values[1].description || '' }, + ]) + + const [methodHeader] = resolveDocumentationFields(protocol, gps, { 5: { presence: 'required', value: 1 } }, 'headers') + expect(methodHeader.name).toBe(protocol.header[5].name) + expect(methodHeader.description).toBe(protocol.header[5].description) + expect(methodHeader.valueName).toBe(protocol.header[5].values[1].name) + }) +}) + describe('Device Status reference', () => { const message = protocol.messages[34] @@ -415,12 +487,15 @@ describe('Device Status reference', () => { expect(subscribe.response?.messageId).toBe(5) expect(unsubscribe.response?.messageId).toBe(5) expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') - expect(subscribe.request?.headers?.['17']).toMatchObject({ presence: 'optional', value: 0 }) + expect(subscribe.request?.headers?.['17']).toMatchObject({ value: 0 }) + expect(subscribe.request?.headers?.['17'].presence).toBeUndefined() + expect(resolveDocumentationFields(protocol, message, subscribe.request?.headers, 'headers').find(field => field.id === 17)?.presence).toBe('optional') expect(subscribe.publication?.headers?.['4'].presence).toBe('omitted') expect(unsubscribe.request?.headers?.['17']).toBeUndefined() for (const context of [get.response, subscribe.publication]) { expect(Object.keys(context!.fields!)).toEqual(Object.keys(message.data)) - expect(Object.values(context!.fields!).every(field => field.presence === 'optional')).toBe(true) + expect(Object.values(context!.fields!).every(field => field.presence === undefined)).toBe(true) + expect(resolveDocumentationFields(protocol, message, context!.fields, 'fields').every(field => field.presence === 'optional')).toBe(true) } expect(subscribe.examples).toBeUndefined() expect(unsubscribe.examples).toBeUndefined() @@ -494,7 +569,8 @@ describe('Device IDs reference', () => { ['4', 'serial', 'uint32'], ['8', 'cachedIccid2', 'ascii'], ]) expect(Object.keys(get.response!.fields!)).toEqual(Object.keys(message.data)) - expect(Object.values(get.response!.fields!).every(field => field.presence === 'optional')).toBe(true) + expect(Object.values(get.response!.fields!).every(field => field.presence === undefined)).toBe(true) + expect(resolveDocumentationFields(protocol, message, get.response?.fields, 'fields').every(field => field.presence === 'optional')).toBe(true) expect(get.response?.description).toContain('may be stale') expect(message.examples).toBeUndefined() expect(validateMessageDocumentation(protocol, 35)).toEqual([]) From d6ecafee1e3930bcbe85499311f66cfa13a3d32b Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:36:57 +0000 Subject: [PATCH 03/24] Remove omitted presence from v3 docs --- devices/api/protocol/responses.md | 4 + public/files/protocol-v3.yaml | 343 ++++++++--------------------- utils/MessageDocumentation.test.ts | 39 +++- utils/MessageDocumentation.ts | 7 +- 4 files changed, 124 insertions(+), 269 deletions(-) diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 681cd2d6c..ee7da5cd2 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -6,6 +6,10 @@ outline: [2,3] A request and its reply are separate frames, with separate headers and data fields. The operation's message page defines the reply type, payload and errors. This page explains the shared conventions; it does not mean every request receives the same kind of reply. +### Authoring exchange fields + +Exchange maps list the fields shown for that stage; listed fields are optional unless marked `required` or `ignored`. Do not add a field row to represent a field that is not sent or returned. Explain no-payload requests, unavailable fields, version-specific layouts, and rejected inputs in the exchange prose. Use `ignored` only when the field is accepted but has no effect in that operation. + Use the operation's required request headers. An omitted [Method (header 5)](./headers#5-method) is not a universal GET default; GPS Control and Message Box require an explicit method. ## Correlating a reply diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 2d6e75bd0..8421a3950 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -33,8 +33,9 @@ header: id: id description: | ID identifying the message. - Can be used by a receiver to ACK, respond to, deduplicate, resend or otherwise track messages. + A receiver may use it to ACK, respond to, deduplicate, resend or otherwise track messages. Some clients and services may require or desire an incrementing message ID for each message sent, acting as a sequence number. + Responses that support correlation can carry this value in Response To. type: uint32 2: name: Client ID @@ -1467,8 +1468,7 @@ messages: title: GET request description: No payload fields are required. Method must be included; this message does not default to GET. headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 2 @@ -1525,24 +1525,17 @@ messages: the default subscription documented here. Updates are subject to the selected interval and message level. headers: - 1: - description: Include a nonzero Message ID if you need a setup acknowledgment. + 1: {} 5: presence: required value: 3 - 6: - description: Publication interval in milliseconds. Omitted or 0 allows updates as new status data becomes available. - 7: - description: Subscription duration in milliseconds. Omitted or 0 keeps the subscription active until unsubscribed. - 8: - description: Time in milliseconds to wait for the first matching status update. Omitted or 0 does not set a timeout. - 15: - description: Storage/retry policy for publications. Defaults to None (0). - 16: - description: Minimum publication level. The default Info-Auto (2) receives normal status updates; no explicit level is required. + 6: {} + 7: {} + 8: {} + 15: {} + 16: {} 17: value: 0 - description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. response: messageId: 5 title: Response (MT5 - ACK) @@ -1561,14 +1554,11 @@ messages: description: >- Later status updates produce Device Status messages, filtered by the subscription interval and level. They are not replies to the original SUBSCRIBE request and - do not carry its Response To. Available payload fields vary by target and readings. - headers: - 3: - presence: omitted - description: A later publication is not correlated to the subscription request. - 4: - presence: omitted - description: Status updates carry status data, not a command-result envelope. + do not carry its Response To or Status header. Available payload fields vary by target + and readings. For this subscription, interval 0 or no interval publishes when new + status data is available; duration 0 or no duration is indefinite; timeout 0 or no + timeout sets no first-update deadline. Storage defaults to None (0), and the default + message level is Info-Auto (2). fields: 1: {} 2: {} @@ -1591,8 +1581,7 @@ messages: title: UNSUBSCRIBE request description: No payload fields are required. Omit Subscription ID; this operation removes the default subscription only. headers: - 1: - description: Include a nonzero Message ID if you need an acknowledgment. + 1: {} 5: presence: required value: 5 @@ -1654,8 +1643,7 @@ messages: title: GET request description: No payload fields are required. Include Method GET to request the device identifiers. headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 2 @@ -1663,8 +1651,7 @@ messages: title: Device IDs (MT35) description: >- The GET response contains the available device identifiers. Not all fields are - available on every device type. Cached SIM2 ICCID is a previously read value - and may be stale. + available on every device type. headers: 3: {} 4: @@ -1933,13 +1920,13 @@ messages: 1: name: GPS is on id: gpsOn - description: Status of the GPS, is it on? + description: Whether the GPS service is on. type: bool readonly: true 2: name: Corrections Enabled id: correctionsOn - description: Request and apply correction data to the GPS, such as RTK. + description: Whether correction data is enabled. type: uint8 values: 0: @@ -1951,7 +1938,7 @@ messages: 3: name: Start Mode id: startMode - description: Start mode of the GPS module. + description: Start mode requested for the GPS module. type: uint8 values: 1: @@ -1979,24 +1966,17 @@ messages: title: GET request description: No payload fields are needed. headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 2 - fields: - 1: - presence: omitted - 2: - presence: omitted - 3: - presence: omitted response: title: GPS state (MT39) description: >- A successful GET returns GPS Control directly, with no separate success ACK. - An unsuccessful request returns MT5 (ACK) with Status, not this payload. + It reports whether GPS and correction data are currently enabled; Start Mode is + a SET input and is not returned. An unsuccessful request returns MT5 (ACK) with + Status, not this payload. headers: 3: {} 4: @@ -2004,13 +1984,8 @@ messages: fields: 1: presence: required - description: Whether the GPS service is on. 2: presence: required - description: Whether correction data is enabled. - 3: - presence: omitted - description: Start mode is a SET input, not returned state. errors: - code: 7 description: "Not Supported: the product or firmware does not support this operation." @@ -2018,36 +1993,27 @@ messages: title: Configure corrections and start mode description: Enable correction data and/or restart the GPS in the requested boot mode. request: - 2: - description: Automatically controls the GPS module. - 3: - description: If the GPS is currently enabled, this will cause the GPS to be rebooted into the requested state. If the GPS is currently disabled, this will cause the GPS to be enabled and the requested state to be set. + 2: {} + 3: {} response: null exchange: request: title: SET request - description: Use writable control fields, not the read-only GPS status field. + description: >- + Field 1 (GPS is on) is read-only and is rejected with Invalid Parameter (4) if sent. + Field 2 requests whether API-enabled correction data should be on and automatically + controls the GPS module as needed. If it is absent, API-enabled corrections are disabled, + so a start-mode-only SET does not preserve the previous correction setting. Include field + 2 with value 1 to keep them on. Field 3 requests a start mode: if GPS is enabled, the + device reboots it in that mode; if disabled, the device enables it in that mode. headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 1 fields: - 1: - presence: omitted - description: Read-only status. Sending this field in SET is rejected with Invalid Parameter (4). - 2: - description: >- - Request and apply correction data to the GPS, such as RTK; this automatically controls - the GPS module. Omitting this field sets API-enabled corrections to disabled, so a - start-mode-only SET does not preserve the previous correction setting. Include 1 to - keep API-enabled corrections on. - 3: - description: >- - If GPS is enabled, reboot it in this mode. If it is disabled, enable it with the - requested state. + 2: {} + 3: {} response: messageId: 5 title: Response (MT5 - ACK) @@ -2063,9 +2029,6 @@ messages: 1: presence: required value: 39 - description: >- - ACK Type identifies the original message type (39). No message-specific state is - returned in this ACK. errors: - code: 4 description: >- @@ -3306,7 +3269,10 @@ messages: label: "2025-10" description: >- Earlier chunked payload and additive-checksum format, retained for existing integrations. - GET and SUBSCRIBE use this format when header 22 is omitted or set to 1. No legacy SET is supported. + GET and SUBSCRIBE use it when header 22 is omitted, zero, malformed-width, or set to 1. + Legacy replies and publications omit header 22 and use checksum field 1 plus nonempty + chunks 10-14 concatenated in field-ID order. They do not include CRC field 2 or full-payload + field 129. No legacy SET is supported. legacy: true group: info header: @@ -3316,51 +3282,51 @@ messages: 1: name: Legacy Checksum id: legacyChecksum - description: Legacy additive checksum (sum of payload bytes modulo 65536), used in version 1 responses with the legacy chunk fields. Absent from version 2 responses. Optional and ignored in SET. + description: Legacy additive checksum (sum of payload bytes modulo 65536), used in version 1 responses and publications with the legacy chunk fields. Absent from version 2 responses and publications. Optional and ignored in SET. type: uint16 readonly: true versions: [1] 2: name: CRC id: crc - description: CRC-16/XMODEM of the cached payload (polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000), separate from the outer message-frame CRC. Returned in version 2 responses and tracking-session messages, including an empty cache as zero (0x0000). Optional and ignored in SET; the device calculates it from field 129. One- or two-byte little-endian encoding may omit a high zero byte. Implemented only on Viper devices. + description: CRC-16/XMODEM of the cached payload (polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000), separate from the outer message-frame CRC. Returned in version 2 responses and publications and tracking-session messages, including an empty cache as zero (0x0000). Optional and ignored in SET; the device calculates it from field 129. One- or two-byte little-endian encoding may omit a high zero byte. Implemented only on Viper devices. type: uint16 readonly: true versions: [2] 10: name: Legacy Payload Chunk 1 id: legacyChunk1 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. + description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. type: bytes versions: [1] 11: name: Legacy Payload Chunk 2 id: legacyChunk2 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. + description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. type: bytes versions: [1] 12: name: Legacy Payload Chunk 3 id: legacyChunk3 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. + description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. type: bytes versions: [1] 13: name: Legacy Payload Chunk 4 id: legacyChunk4 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. + description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. type: bytes versions: [1] 14: name: Legacy Payload Chunk 5 id: legacyChunk5 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. + description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. type: bytes versions: [1] 129: name: Full Payload id: fullPayload - description: Complete message-box bytes in SET requests, GET responses, and subscription updates (up to 1024 bytes). SET must include this field; an explicit zero-length value clears the cache. Uses an extended-length field with a uint16 little-endian length prefix. Tracking-session uploads may use this field for independent Transmit Now data instead. + description: Complete message-box bytes in SET requests, GET responses, and subscription updates (up to 1024 bytes). SET must include this field; an explicit zero-length value clears the cache. GET responses and subscription updates include it only when the cache is nonempty. Uses an extended-length field with a uint16 little-endian length prefix. Tracking-session uploads may use this field for independent Transmit Now data instead. type: bytes versions: [2] methods: @@ -3383,9 +3349,7 @@ messages: title: GET request description: No payload fields are needed. headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 2 @@ -3393,12 +3357,12 @@ messages: presence: required maxBytes: 1 value: 2 - description: A one-byte value of 2 selects version 2. response: title: Cached payload description: >- A successful GET returns this MT58 payload. An unsuccessful request returns - MT5 (ACK) with Status instead. + MT5 (ACK) with Status instead. Version 2 returns CRC field 2; legacy checksum + field 1 and version 1 chunks are not returned. headers: 3: {} 4: @@ -3407,93 +3371,49 @@ messages: presence: required maxBytes: 1 value: 2 - description: Identifies the format of this response payload. fields: - 1: - presence: omitted - description: The legacy additive checksum is absent from version 2 responses. 2: presence: required - description: >- - Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty - cache. One- or two-byte little-endian encoding may omit a high zero byte. 129: maxBytes: 1024 - description: >- - Complete cached payload in an extended-length field with a uint16 little-endian - length prefix. Empty payload data is omitted. 1: title: 2025-10 · legacy chunks description: Use the unchanged legacy wire layout and additive checksum. request: title: GET request - description: No payload fields are needed. + description: >- + No payload fields are needed. A missing, zero, or malformed-width Message Version + selects version 1; explicit value 1 also selects version 1. headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 2 22: maxBytes: 1 - description: >- - Omitted, explicitly 0, or malformed-width values resolve to 0 and select version - 1; an explicit 1 also selects version 1. - values: - 0: Version 1 (also the omitted/malformed-width fallback) - 1: Version 1 response: title: Legacy cached payload description: >- A successful GET returns this MT58 payload. An unsuccessful request returns - MT5 (ACK) with Status instead. + MT5 (ACK) with Status instead. Legacy replies use checksum field 1 and nonempty + payload chunks 10-14; they do not include header 22, CRC field 2, or field 129. headers: 3: {} 4: value: 0 - 22: - presence: omitted - description: >- - Legacy version 1 responses retain their original wire layout and omit Message - Version. fields: 1: presence: required - description: "Additive checksum: sum of all cached payload bytes modulo 65536." - 2: - presence: omitted - description: The CRC field belongs to version 2. 10: maxBytes: 255 - description: >- - Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty - payload data is omitted. 11: maxBytes: 255 - description: >- - Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty - payload data is omitted. 12: maxBytes: 255 - description: >- - Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty - payload data is omitted. 13: maxBytes: 255 - description: >- - Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty - payload data is omitted. 14: maxBytes: 255 - description: >- - Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty - payload data is omitted. - 129: - presence: omitted - description: >- - Version 1 retains the legacy wire layout; it does not include the extended - full-payload field. SET: title: Replace or clear the cached message description: >- @@ -3505,13 +3425,10 @@ messages: request: title: SET request description: >- - Message Version 2 and field 129 are required. The device calculates the payload CRC; the - outer message-frame CRC protects the SET request itself. - Optional supplied checksum fields 1 and 2 are ignored. + The device calculates the payload CRC; the outer message-frame CRC protects the SET + request itself. headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 1 @@ -3519,14 +3436,10 @@ messages: presence: required maxBytes: 1 value: 2 - description: A one-byte value of 2 selects version 2. fields: 129: presence: required maxBytes: 1024 - description: >- - Complete new cache bytes. An explicit zero-length field clears the cache; omitting the - field is an error. Extended-length encoding uses a uint16 little-endian length prefix. response: messageId: 5 title: Response (MT5 - ACK) @@ -3543,9 +3456,6 @@ messages: 1: presence: required value: 58 - description: >- - ACK Type identifies the original message type (58). No message-specific state is - returned in this ACK. errors: - code: 2 description: "Missing Parameter: field 129 is absent." @@ -3581,9 +3491,6 @@ messages: 1: presence: required value: 58 - description: >- - ACK Type identifies the original message type (58). No message-specific state is - returned in this ACK. errors: - code: 4 description: >- @@ -3597,62 +3504,38 @@ messages: description: Explicit version 2 selects the shared extended-payload and CRC publication format. request: title: SUBSCRIBE request + description: >- + No payload fields are needed. A nonzero Message ID requests a setup acknowledgment; + omitting Subscription ID selects the default subscription (0). headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 3 - 6: - description: >- - Optional publication interval in milliseconds. If omitted, updates are sent when - new data is available. - 7: - description: >- - Subscription duration in milliseconds; 0 is indefinite until explicitly - unsubscribed. - 16: - description: Minimum publication level. - 17: - description: >- - Subscription ID; omit for the default subscription (0). Use the same ID when - unsubscribing. + 6: {} + 7: {} + 16: {} + 17: {} 22: presence: required maxBytes: 1 value: 2 - description: A one-byte value of 2 selects version 2. publication: title: Cached payload update description: >- - Version 2 updates include Message Version 2 and field 2. Field 129 carries the - complete cached payload when nonempty; empty payload data is omitted. + This is an asynchronous cache update, not a direct reply to SUBSCRIBE; it has no + Response To header. Version 2 identifies the format and includes the cached CRC. headers: - 3: - presence: omitted - description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - 17: - description: Identifies nonzero subscription IDs for this publication. + 17: {} 22: presence: required maxBytes: 1 value: 2 - description: A one-byte value of 2 selects version 2. fields: - 1: - presence: omitted - description: The legacy additive checksum is absent from version 2 responses. 2: presence: required - description: >- - Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty - cache. One- or two-byte little-endian encoding may omit a high zero byte. 129: maxBytes: 1024 - description: >- - Complete cached payload in an extended-length field with a uint16 little-endian - length prefix. Empty payload data is omitted. 1: title: Version 1 · legacy publications description: >- @@ -3660,106 +3543,56 @@ messages: publication format. request: title: SUBSCRIBE request + description: >- + No payload fields are needed. A nonzero Message ID requests a setup acknowledgment; + omitting Subscription ID selects the default subscription (0). headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 3 - 6: - description: >- - Optional publication interval in milliseconds. If omitted, updates are sent when - new data is available. - 7: - description: >- - Subscription duration in milliseconds; 0 is indefinite until explicitly - unsubscribed. - 16: - description: Minimum publication level. - 17: - description: >- - Subscription ID; omit for the default subscription (0). Use the same ID when - unsubscribing. + 6: {} + 7: {} + 16: {} + 17: {} 22: maxBytes: 1 - description: >- - Omitted, explicitly 0, or malformed-width values resolve to 0 and select version - 1; an explicit 1 also selects version 1. - values: - 0: Version 1 (also the omitted/malformed-width fallback) - 1: Version 1 publication: title: Legacy cached payload update description: >- - Version 1 updates use the additive checksum and legacy chunks. Empty payload data is - omitted. + This is an asynchronous cache update, not a direct reply to SUBSCRIBE; it has no + Response To header. headers: - 3: - presence: omitted - description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - 17: - description: Identifies nonzero subscription IDs for this publication. - 22: - presence: omitted - description: >- - Legacy version 1 responses retain their original wire layout and omit Message - Version. + 17: {} fields: 1: presence: required - description: "Additive checksum: sum of all cached payload bytes modulo 65536." - 2: - presence: omitted - description: The CRC field belongs to version 2. 10: maxBytes: 255 - description: >- - Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty - payload data is omitted. 11: maxBytes: 255 - description: >- - Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty - payload data is omitted. 12: maxBytes: 255 - description: >- - Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty - payload data is omitted. 13: maxBytes: 255 - description: >- - Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty - payload data is omitted. 14: maxBytes: 255 - description: >- - Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty - payload data is omitted. - 129: - presence: omitted - description: >- - Version 1 retains the legacy wire layout; it does not include the extended - full-payload field. UNSUBSCRIBE: title: Stop a subscription description: >- Remove the addressed subscription. Neither UNSUBSCRIBE nor subscription expiry resets the - shared publication-format selection. + shared publication-format selection. If Subscription ID is absent, this removes the default + subscription (ID 0). exchange: request: title: UNSUBSCRIBE request description: No payload fields are needed. headers: - 1: - description: >- - Include a nonzero Message ID to correlate the reply. + 1: {} 5: presence: required value: 5 - 17: - description: Use the Subscription ID to remove, or omit it for the default subscription (0). + 17: {} 22: presence: ignored description: UNSUBSCRIBE does not select or reset the publication format. @@ -3780,9 +3613,6 @@ messages: 1: presence: required value: 58 - description: >- - ACK Type identifies the original message type (58). No message-specific state is - returned in this ACK. errors: - code: 7 description: "Not Supported: the product or firmware does not support this operation." @@ -3809,7 +3639,6 @@ messages: presence: required maxBytes: 1 value: 2 - description: A one-byte value of 2 selects version 2. fields: 2: description: >- diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 33cc4be13..bebeba521 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -87,7 +87,6 @@ describe('shared response conventions', () => { expect(context).toEqual(before) }) it('keeps explicit exceptions and non-OK status rules local', () => { - expect(commonResponseHeaderIds({ headers: { '3': { presence: 'omitted' }, '4': { presence: 'required', value: 4 } } })).toEqual([]) expect(commonResponseHeaderIds({ headers: { '3': { presence: 'optional', description: 'A message-specific correlation rule.' }, '4': { presence: 'required', value: 0, maxBytes: 1 } } })).toEqual([]) expect(commonResponseHeaderIds({ headers: { '3': { presence: 'ignored' }, '4': { value: 0 } } })).toEqual(['4']) expect(commonResponseHeaderIds({ headers: { '3': {}, '4': { value: 0 } } })).toEqual(['3', '4']) @@ -98,10 +97,16 @@ describe('shared response conventions', () => { const subscribe = getOperationVariant(message.operations.find(operation => operation.method === 'SUBSCRIBE')!, '2') expect(commonResponseHeaderIds(get.response!)).toEqual(['3', '4']) expect(get.response?.headers?.['22']).toMatchObject({ presence: 'required', value: 2 }) + expect(get.response?.fields?.['1']).toBeUndefined() expect(get.response?.fields?.['129']).toMatchObject({ maxBytes: 1024 }) expect(get.response?.fields?.['129'].presence).toBeUndefined() expect(resolveDocumentationFields(protocol, protocol.messages[58], get.response?.fields, 'fields').find(field => field.id === 129)?.presence).toBe('optional') - expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') + expect(subscribe.publication?.headers?.['3']).toBeUndefined() + expect(subscribe.publication?.fields?.['1']).toBeUndefined() + const legacyGet = getOperationVariant(message.operations.find(operation => operation.method === 'GET')!, '1') + expect(legacyGet.response?.headers?.['22']).toBeUndefined() + expect(legacyGet.response?.fields?.['2']).toBeUndefined() + expect(legacyGet.response?.fields?.['129']).toBeUndefined() }) it('corrects only the Processing display label, preserving the existing SDK identifier', () => { expect(protocol.header[4].values[-1]).toMatchObject({ name: 'Processing', id: 'error' }) @@ -166,6 +171,7 @@ describe('optional message documentation', () => { response: { messageId: 9999 }, } } message.contexts = { get: { exchange: {} } } + message.methods.GET.exchange.response.fields = { 1: { presence: 'omitted' } } const errors = validateMessageDocumentation(sample, 39).join('\n') expect(errors).toContain('duplicate operation id get') expect(errors).toContain('unsupported method UNSUPPORTED') @@ -174,6 +180,7 @@ describe('optional message documentation', () => { expect(errors).toContain('unknown fields id 99') expect(errors).toContain('unknown message 9999') expect(errors).toContain('invalid note placement') + expect(errors).toContain('response fields 1 has invalid presence') }) it('puts required fields first while preserving order within each group', () => { @@ -181,7 +188,7 @@ describe('optional message documentation', () => { 1: { presence: 'optional' as const }, 4: { presence: 'required' as const }, 5: { presence: 'required' as const }, - 17: { presence: 'omitted' as const }, + 17: {}, 22: { presence: 'optional' as const }, } const before = clone(usage) @@ -296,12 +303,13 @@ describe('inline numeric-version authoring', () => { expect(protocol).toEqual(before) }) - it('preserves direct SDK request/response map presence and field IDs', () => { + it('preserves direct request/response map presence and field IDs without duplicate field descriptions', () => { const gps = protocol.messages[39].methods expect(gps.GET.request).toBeNull() expect(gps.GET.response).toEqual({ 1: null, 2: null }) expect(Object.keys(gps.SET.request)).toEqual(['2', '3']) - expect(gps.SET.request[2].description).toBe('Automatically controls the GPS module.') + expect(gps.SET.request[2]).toEqual({}) + expect(gps.SET.request[3]).toEqual({}) expect(gps.SET.response).toBeNull() for (const method of Object.values(protocol.messages[58].methods) as any[]) { expect(Object.prototype.hasOwnProperty.call(method, 'request')).toBe(false) @@ -366,8 +374,9 @@ describe('inline numeric-version authoring', () => { it('keeps ignored checksums out of SET inputs without deleting the compatibility rule', () => { const set = protocol.messages[58].methods.SET.versions[2] expect(Object.keys(set!.request!.fields)).toEqual(['129']) - expect(set.request.description).toContain('checksum fields 1 and 2 are ignored') expect(set!.request!.fields[129]).toMatchObject({ presence: 'required', maxBytes: 1024 }) + expect(protocol.messages[58].data[1].description).toContain('ignored in SET') + expect(protocol.messages[58].data[2].description).toContain('ignored in SET') const get = protocol.messages[58].methods.GET.versions[2] expect(get.response.fields[2].presence).toBe('required') }) @@ -389,6 +398,7 @@ describe('migrated exchange authoring audit', () => { for (const [id, usage] of Object.entries(context[kind] || {}) as [string, any][]) { const definition = definitions?.[id] expect(usage.presence).not.toBe('optional') + expect(usage.presence).not.toBe('omitted') if (!definition) continue for (const key of ['description', 'name', 'id', 'type', 'unit', 'maxBytes']) { if (usage[key] !== undefined && definition[key] !== undefined) { @@ -431,6 +441,17 @@ describe('migrated exchange authoring audit', () => { const gpsDefinition = gps.data[2] expect(gpsField.name).toBe(gpsDefinition.name) expect(gpsField.description).toBe(gpsDefinition.description) + expect(gpsDefinition.description).toBe('Whether correction data is enabled.') + expect(gps.data[1].description).toBe('Whether the GPS service is on.') + expect(gps.methods.GET.exchange.response.description).toContain('Start Mode is a SET input and is not returned') + expect(gps.methods.SET.exchange.request.description).toContain('rejected with Invalid Parameter (4) if sent') + expect(gps.methods.SET.exchange.request.description).toContain('API-enabled corrections are disabled') + expect(gps.methods.SET.exchange.request.description).toContain('automatically controls the GPS module') + expect(gps.methods.SET.exchange.request.description).toContain('the device reboots it in that mode') + const set = getMessageDocumentation(gps)!.operations.find(operation => operation.method === 'SET')! + const setFields = resolveDocumentationFields(protocol, gps, set.request!.fields, 'fields') + expect(setFields.find(field => field.id === 2)!.description).toBe(gps.data[2].description) + expect(setFields.find(field => field.id === 3)!.description).toBe(gps.data[3].description) expect(gpsField.values.map(({ value, name, description }: any) => ({ value, name, description }))).toEqual([ { value: 0, name: gpsDefinition.values[0].name, description: gpsDefinition.values[0].description || '' }, { value: 1, name: gpsDefinition.values[1].name, description: gpsDefinition.values[1].description || '' }, @@ -486,11 +507,11 @@ describe('Device Status reference', () => { expect(get.response?.messageId).toBeUndefined() expect(subscribe.response?.messageId).toBe(5) expect(unsubscribe.response?.messageId).toBe(5) - expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') + expect(subscribe.publication?.headers?.['3']).toBeUndefined() expect(subscribe.request?.headers?.['17']).toMatchObject({ value: 0 }) expect(subscribe.request?.headers?.['17'].presence).toBeUndefined() expect(resolveDocumentationFields(protocol, message, subscribe.request?.headers, 'headers').find(field => field.id === 17)?.presence).toBe('optional') - expect(subscribe.publication?.headers?.['4'].presence).toBe('omitted') + expect(subscribe.publication?.headers?.['4']).toBeUndefined() expect(unsubscribe.request?.headers?.['17']).toBeUndefined() for (const context of [get.response, subscribe.publication]) { expect(Object.keys(context!.fields!)).toEqual(Object.keys(message.data)) @@ -571,7 +592,7 @@ describe('Device IDs reference', () => { expect(Object.keys(get.response!.fields!)).toEqual(Object.keys(message.data)) expect(Object.values(get.response!.fields!).every(field => field.presence === undefined)).toBe(true) expect(resolveDocumentationFields(protocol, message, get.response?.fields, 'fields').every(field => field.presence === 'optional')).toBe(true) - expect(get.response?.description).toContain('may be stale') + expect(get.response?.description).not.toContain('may be stale') expect(message.examples).toBeUndefined() expect(validateMessageDocumentation(protocol, 35)).toEqual([]) }) diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index ca6384863..cc559e7bd 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -5,7 +5,8 @@ import { formatSentinelValue } from './ProtocolSentinels' /** Structured message documentation. Wire definitions remain in header and message.data. */ export interface DocumentationField { description?: string - presence?: 'required' | 'optional' | 'ignored' | 'omitted' + /** Omit for the normal optional case; use ignored only for accepted-but-ignored inputs. */ + presence?: 'required' | 'optional' | 'ignored' value?: number values?: Record maxBytes?: number @@ -344,7 +345,7 @@ function validateInlineDocumentation(message: any): string[] { if (context?.messageId !== undefined) continue for (const [id, usage] of Object.entries(context?.fields || {}) as [string, any][]) { const applicable = message.data?.[id]?.versions - if (Array.isArray(applicable) && !applicable.includes(Number(version)) && !['omitted', 'ignored'].includes(usage?.presence)) { + if (Array.isArray(applicable) && !applicable.includes(Number(version)) && usage?.presence !== 'ignored') { errors.push(`${name}/${version} ${role} uses field ${id} outside its versions`) } } @@ -406,7 +407,7 @@ export function validateMessageDocumentation(protocol: any, messageId: number): fail(`${label} ${kind} ${key} must be an object`) continue } - if (field.presence && !['required', 'optional', 'ignored', 'omitted'].includes(field.presence)) { + if (field.presence && !['required', 'optional', 'ignored'].includes(field.presence)) { fail(`${label} ${kind} ${key} has invalid presence`) } if (field.maxBytes !== undefined && (!Number.isInteger(field.maxBytes) || field.maxBytes < 0)) { From 3d1496f2ee9ecad1db0c700607b1117981891ac0 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:37:02 +0000 Subject: [PATCH 04/24] Remove Authoring exchange field section --- devices/api/protocol/responses.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index ee7da5cd2..aaaccf456 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -6,12 +6,6 @@ outline: [2,3] A request and its reply are separate frames, with separate headers and data fields. The operation's message page defines the reply type, payload and errors. This page explains the shared conventions; it does not mean every request receives the same kind of reply. -### Authoring exchange fields - -Exchange maps list the fields shown for that stage; listed fields are optional unless marked `required` or `ignored`. Do not add a field row to represent a field that is not sent or returned. Explain no-payload requests, unavailable fields, version-specific layouts, and rejected inputs in the exchange prose. Use `ignored` only when the field is accepted but has no effect in that operation. - -Use the operation's required request headers. An omitted [Method (header 5)](./headers#5-method) is not a universal GET default; GPS Control and Message Box require an explicit method. - ## Correlating a reply Include a nonzero [Message ID (header 1)](./headers#1-message-id) when you need to match replies to requests. A correlated reply carries that ID in [Response to (header 3)](./headers#3-response-to), not as its own Message ID. From 7aae7fcdf0469e14639aea9def0967473ba6fedf Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:37:07 +0000 Subject: [PATCH 05/24] Re add something I didnt want to remove Added clarification on request headers and message ID correlation. --- devices/api/protocol/responses.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index aaaccf456..681cd2d6c 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -6,6 +6,8 @@ outline: [2,3] A request and its reply are separate frames, with separate headers and data fields. The operation's message page defines the reply type, payload and errors. This page explains the shared conventions; it does not mean every request receives the same kind of reply. +Use the operation's required request headers. An omitted [Method (header 5)](./headers#5-method) is not a universal GET default; GPS Control and Message Box require an explicit method. + ## Correlating a reply Include a nonzero [Message ID (header 1)](./headers#1-message-id) when you need to match replies to requests. A correlated reply carries that ID in [Response to (header 3)](./headers#3-response-to), not as its own Message ID. From 4746937e903a391d6e2577fa873ae4993c33e4de Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:37:33 +0000 Subject: [PATCH 06/24] Correct GPS and MT34 response documentation --- public/files/protocol-v3.yaml | 37 +++++++++++++++++------------- utils/MessageDocumentation.test.ts | 23 +++++++++++++++---- 2 files changed, 39 insertions(+), 21 deletions(-) diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 8421a3950..80ee0f453 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1476,12 +1476,12 @@ messages: title: Device status (MT34) description: >- A successful GET returns Device Status directly, without a separate success ACK. - Returned fields vary by target and available readings. Response To and Status may - be omitted when the request has no nonzero Message ID. + Returned fields vary by target and available readings. The reviewed Toit + implementation returns firmware information and includes Response To whenever + a Message ID is present, including zero; it does not include an explicit Status + header. Other targets may differ. headers: 3: {} - 4: - value: 0 fields: 1: {} 2: {} @@ -1920,13 +1920,17 @@ messages: 1: name: GPS is on id: gpsOn - description: Whether the GPS service is on. + description: >- + Whether GPS Control has an active Position-data subscription at the Info-Auto level. + This does not directly report hardware power or fix state. type: bool readonly: true 2: name: Corrections Enabled id: correctionsOn - description: Whether correction data is enabled. + description: >- + Correction-service control and status. GET reports whether corrections are enabled + by the API or device mode; SET requests the API-controlled correction setting. type: uint8 values: 0: @@ -1956,7 +1960,7 @@ messages: methods: GET: title: Read GPS state - description: Return the current GPS and correction-service state, not a position fix. + description: Read the GPS-control subscription state and effective correction-service state, not a position fix. request: null response: 1: null @@ -1974,9 +1978,9 @@ messages: title: GPS state (MT39) description: >- A successful GET returns GPS Control directly, with no separate success ACK. - It reports whether GPS and correction data are currently enabled; Start Mode is - a SET input and is not returned. An unsuccessful request returns MT5 (ACK) with - Status, not this payload. + It reports the Position-data subscription state and whether corrections are enabled + by the API or device mode. Start Mode is a SET input and is not returned. An + unsuccessful request returns MT5 (ACK) with Status, not this payload. headers: 3: {} 4: @@ -1991,7 +1995,7 @@ messages: description: "Not Supported: the product or firmware does not support this operation." SET: title: Configure corrections and start mode - description: Enable correction data and/or restart the GPS in the requested boot mode. + description: Request correction-service control and/or a GPS start mode. request: 2: {} 3: {} @@ -2001,11 +2005,12 @@ messages: title: SET request description: >- Field 1 (GPS is on) is read-only and is rejected with Invalid Parameter (4) if sent. - Field 2 requests whether API-enabled correction data should be on and automatically - controls the GPS module as needed. If it is absent, API-enabled corrections are disabled, - so a start-mode-only SET does not preserve the previous correction setting. Include field - 2 with value 1 to keep them on. Field 3 requests a start mode: if GPS is enabled, the - device reboots it in that mode; if disabled, the device enables it in that mode. + Field 2 requests the API-controlled correction setting. If absent from a successful + SET, that API flag is cleared; device mode may still require corrections. The API + correction request alone does not keep GPS/RTK running: an external Position + subscription or device-mode ownership is also required. Field 3 records a requested + start mode as pending in current firmware; this SET path does not establish an immediate + hardware restart or enable. headers: 1: {} 5: diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index bebeba521..29ea30904 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -441,13 +441,16 @@ describe('migrated exchange authoring audit', () => { const gpsDefinition = gps.data[2] expect(gpsField.name).toBe(gpsDefinition.name) expect(gpsField.description).toBe(gpsDefinition.description) - expect(gpsDefinition.description).toBe('Whether correction data is enabled.') - expect(gps.data[1].description).toBe('Whether the GPS service is on.') + expect(gpsDefinition.description).toContain('GET reports whether corrections are enabled by the API or device mode') + expect(gps.data[1].description).toContain('active Position-data subscription at the Info-Auto level') + expect(gps.data[1].description).toContain('does not directly report hardware power or fix state') expect(gps.methods.GET.exchange.response.description).toContain('Start Mode is a SET input and is not returned') expect(gps.methods.SET.exchange.request.description).toContain('rejected with Invalid Parameter (4) if sent') - expect(gps.methods.SET.exchange.request.description).toContain('API-enabled corrections are disabled') - expect(gps.methods.SET.exchange.request.description).toContain('automatically controls the GPS module') - expect(gps.methods.SET.exchange.request.description).toContain('the device reboots it in that mode') + expect(gps.methods.SET.exchange.request.description).toContain('that API flag is cleared') + expect(gps.methods.SET.exchange.request.description).toContain('device mode may still require corrections') + expect(gps.methods.SET.exchange.request.description).toContain('external Position subscription or device-mode ownership is also required') + expect(gps.methods.SET.exchange.request.description).toContain('records a requested start mode as pending in current firmware') + expect(gps.methods.SET.exchange.request.description).not.toMatch(/automatically controls|reboots it|enables it in that mode/) const set = getMessageDocumentation(gps)!.operations.find(operation => operation.method === 'SET')! const setFields = resolveDocumentationFields(protocol, gps, set.request!.fields, 'fields') expect(setFields.find(field => field.id === 2)!.description).toBe(gps.data[2].description) @@ -481,6 +484,16 @@ describe('Device Status reference', () => { } expect(validateMessageDocumentation(protocol, 34)).toEqual([]); }); + it('qualifies Toit MT34 GET response headers by target', () => { + const get = docs.operations.find((operation: DocumentationOperation) => operation.method === 'GET')! + const response = get.response! + expect(response.description).toContain('reviewed Toit implementation') + expect(response.description).toContain('whenever a Message ID is present, including zero') + expect(response.description).toContain('does not include an explicit Status header') + expect(response.description).toContain('Other targets may differ') + expect(response.headers?.['3']).toBeDefined() + expect(response.headers?.['4']).toBeUndefined() + }) it('keeps the existing methods and wire fields without inventing a message version', () => { expect(Object.keys(message.methods)).toEqual(['GET', 'SUBSCRIBE', 'UNSUBSCRIBE']) expect(message.versions).toBeUndefined() From f516d1078d6d88698ac676ca382c23290face81e Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:37:40 +0000 Subject: [PATCH 07/24] Correct v3 message sidebar grouping --- public/files/protocol-v3.yaml | 16 ++++++++-------- utils/MessageDocumentation.test.ts | 26 ++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 80ee0f453..193bb6480 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -680,7 +680,7 @@ messages: GET behaviour: - If Key (data field 7 / `key`) is omitted, the response returns a config summary payload (data field 5 / `summary16`). - If Key is provided, the response returns the value for that specific key in Payload (data field 9). - group: ungrouped + group: general data: 3: name: Command @@ -1760,7 +1760,7 @@ messages: The cache is replaced when network identity changes or a signal metric changes by more than 3 raw units. Smaller signal changes alone do not replace it. GET and subscription support is firmware-dependent. - group: info + group: gsm header: - 5 data: @@ -2470,7 +2470,7 @@ messages: id: batteryStatus description: | Get the battery status of a device - group: info + group: power header: - 5 data: @@ -3033,7 +3033,7 @@ messages: name: Charger Settings id: chargerSettings description: For products with configurable charge settings (notably NOT Vehicle RTK), get and define charging parameters - group: location + group: power header: - 5 data: @@ -3186,7 +3186,7 @@ messages: Everything is in 0.1g or degrees for clarity: whilst higher precision data is available, the accuracy can only really be trusted up to 0.1g or 1deg increments, and this keeps the payload size down. **Partial messages:** When only one or more of the per-axis maximum G component fields (keys 9/10/11) change and all other fields are unchanged, the device emits two messages back-to-back. First, a sparse MT_ACCEL_DATA message containing only the changed component field(s) at Q_ChangesOnly level, allowing subscribers to react immediately to axis-level changes. Second, a full MT_ACCEL_DATA message (all fields) at Q_Valid level. In all other cases only one full message is emitted, at Q_ChangesOnly if any field changed or Q_Valid if the store is unchanged. - group: ungrouped + group: info data: 1: name: Version @@ -4208,7 +4208,7 @@ messages: name: RTCM Data id: rtcmData description: Data relating to RTCM (Radio Technical Commission for Maritime Services) correction data for high-precision GNSS positioning. - group: "" + group: location data: 1: name: Data @@ -4232,7 +4232,7 @@ messages: name: EPO Data id: epoData description: Data relating to EPO (Extended Prediction Orbit) transfer requests and payload chunks. - group: "" + group: location header: - 5 data: @@ -4285,7 +4285,7 @@ messages: name: File Data id: fileData description: Generic file transfer requests and payload chunks for module firmware and other downloads. - group: "" + group: general header: - 5 data: diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 29ea30904..cfe1404ca 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -31,6 +31,32 @@ describe('Cell Info signal strength terminology', () => { }) }) +describe('protocol message groups', () => { + it('uses existing groups and places every message in its generated sidebar bucket', () => { + const sidebarGroups = Object.fromEntries(Object.keys(protocol.groups).map((group: string) => [group, [] as string[]])) + for (const [id, message] of Object.entries(protocol.messages) as [string, any][]) { + expect(protocol.groups[message.group]).toBeDefined() + sidebarGroups[message.group].push(id) + } + + expect(Object.fromEntries(['14', '37', '43', '54', '57', '2000', '2100', '2101'].map(id => [id, protocol.messages[id].group]))).toEqual({ + '14': 'general', + '37': 'gsm', + '43': 'power', + '54': 'power', + '57': 'info', + '2000': 'location', + '2100': 'location', + '2101': 'general', + }) + for (const id of ['14', '37', '43', '54', '57', '2000', '2100', '2101']) { + expect(sidebarGroups[protocol.messages[id].group]).toContain(id) + } + expect(protocol.messages[1004].group).toBe('ungrouped') + expect(protocol.messages[1005].group).toBe('ungrouped') + }) +}) + describe('paired exchange stages', () => { it('groups frame metadata by stage without mutating order or anchor indices', () => { // Metadata-only fixture; this test does not assert protocol packet bytes. From f1bed7334ba35b63caba0b7592e68cae72cbb45b Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:37:48 +0000 Subject: [PATCH 08/24] Remove redundant fixed-width limits --- public/files/protocol-v3.yaml | 12 ++---------- utils/MessageDocumentation.test.ts | 23 ++++++++++++++++++++++- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 193bb6480..f94c0adfb 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -3360,7 +3360,6 @@ messages: value: 2 22: presence: required - maxBytes: 1 value: 2 response: title: Cached payload @@ -3374,7 +3373,6 @@ messages: value: 0 22: presence: required - maxBytes: 1 value: 2 fields: 2: @@ -3394,8 +3392,7 @@ messages: 5: presence: required value: 2 - 22: - maxBytes: 1 + 22: {} response: title: Legacy cached payload description: >- @@ -3439,7 +3436,6 @@ messages: value: 1 22: presence: required - maxBytes: 1 value: 2 fields: 129: @@ -3523,7 +3519,6 @@ messages: 17: {} 22: presence: required - maxBytes: 1 value: 2 publication: title: Cached payload update @@ -3534,7 +3529,6 @@ messages: 17: {} 22: presence: required - maxBytes: 1 value: 2 fields: 2: @@ -3560,8 +3554,7 @@ messages: 7: {} 16: {} 17: {} - 22: - maxBytes: 1 + 22: {} publication: title: Legacy cached payload update description: >- @@ -3642,7 +3635,6 @@ messages: headers: 22: presence: required - maxBytes: 1 value: 2 fields: 2: diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index cfe1404ca..b1b84df84 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from '@jest/globals' import { readFileSync } from 'node:fs' import { resolve } from 'node:path' -import { calculateCRC16XMODEM, parseRawMessage, readTypedData } from '../src/protocol/base.gen' +import { calculateCRC16XMODEM, getElementByteSize, parseRawMessage, readTypedData } from '../src/protocol/base.gen' // The repository's YAML dependency is intentionally untyped. const yaml = require('js-yaml') import { @@ -123,6 +123,10 @@ describe('shared response conventions', () => { const subscribe = getOperationVariant(message.operations.find(operation => operation.method === 'SUBSCRIBE')!, '2') expect(commonResponseHeaderIds(get.response!)).toEqual(['3', '4']) expect(get.response?.headers?.['22']).toMatchObject({ presence: 'required', value: 2 }) + const [messageVersionHeader] = resolveDocumentationFields(protocol, protocol.messages[58], get.request?.headers, 'headers').filter(field => field.id === 22) + expect(messageVersionHeader).toMatchObject({ type: 'uint8', presence: 'required', value: 2 }) + expect(messageVersionHeader.maxBytes).toBeUndefined() + expect(getElementByteSize(messageVersionHeader.type!)).toBe(1) expect(get.response?.fields?.['1']).toBeUndefined() expect(get.response?.fields?.['129']).toMatchObject({ maxBytes: 1024 }) expect(get.response?.fields?.['129'].presence).toBeUndefined() @@ -134,6 +138,23 @@ describe('shared response conventions', () => { expect(legacyGet.response?.fields?.['2']).toBeUndefined() expect(legacyGet.response?.fields?.['129']).toBeUndefined() }) + it('omits type-implied Message Version limits while retaining variable-byte caps', () => { + const message = protocol.messages[58] + const maxBytes: number[] = [] + const visit = (value: any) => { + if (!value || typeof value !== 'object') return + if (value.maxBytes !== undefined) maxBytes.push(value.maxBytes) + for (const child of Object.values(value)) visit(child) + } + visit(message) + expect(maxBytes).not.toContain(1) + expect(maxBytes.filter(limit => limit === 255)).toHaveLength(10) + expect(maxBytes.filter(limit => limit === 1024)).toHaveLength(3) + for (const id of [10, 11, 12, 13, 14, 129]) { + expect(message.data[id].type).toBe('bytes') + } + expect(validateMessageDocumentation(protocol, 58)).toEqual([]) + }) it('corrects only the Processing display label, preserving the existing SDK identifier', () => { expect(protocol.header[4].values[-1]).toMatchObject({ name: 'Processing', id: 'error' }) expect(protocol.header[4].type).toBe('int8') From 7736b190929811700db689913e1a2e8bfd497df0 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:38:11 +0000 Subject: [PATCH 09/24] Consolidate GPS Control field guidance --- public/files/protocol-v3.yaml | 34 ++++++++++++++---------------- utils/MessageDocumentation.test.ts | 26 ++++++++++++++++------- 2 files changed, 34 insertions(+), 26 deletions(-) diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index f94c0adfb..d9fa1f7ff 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1921,16 +1921,18 @@ messages: name: GPS is on id: gpsOn description: >- - Whether GPS Control has an active Position-data subscription at the Info-Auto level. - This does not directly report hardware power or fix state. + Whether a Position-data subscription at the Info-Auto level is active; + this does not directly report hardware power or fix state. This field is read-only, and + a SET containing it is rejected with Invalid Parameter (4). type: bool readonly: true 2: name: Corrections Enabled id: correctionsOn description: >- - Correction-service control and status. GET reports whether corrections are enabled - by the API or device mode; SET requests the API-controlled correction setting. + Correction-service control and status. GET reports whether corrections are enabled by the + API or device mode; SET requests the API-controlled setting. Omission from a successful + SET clears only the API flag; device mode may still require corrections. type: uint8 values: 0: @@ -1942,7 +1944,9 @@ messages: 3: name: Start Mode id: startMode - description: Start mode requested for the GPS module. + description: >- + GPS start mode requested through SET. Current firmware records it as pending; this SET + path does not establish an immediate hardware restart or enable. type: uint8 values: 1: @@ -1960,7 +1964,7 @@ messages: methods: GET: title: Read GPS state - description: Read the GPS-control subscription state and effective correction-service state, not a position fix. + description: Return GPS Control state, not a position fix. request: null response: 1: null @@ -1977,10 +1981,9 @@ messages: response: title: GPS state (MT39) description: >- - A successful GET returns GPS Control directly, with no separate success ACK. - It reports the Position-data subscription state and whether corrections are enabled - by the API or device mode. Start Mode is a SET input and is not returned. An - unsuccessful request returns MT5 (ACK) with Status, not this payload. + A successful GET returns this payload directly, without a separate success ACK. + Start Mode is SET-only and is not returned. An unsuccessful request returns MT5 + (ACK) with Status, not this payload. headers: 3: {} 4: @@ -1995,7 +1998,7 @@ messages: description: "Not Supported: the product or firmware does not support this operation." SET: title: Configure corrections and start mode - description: Request correction-service control and/or a GPS start mode. + description: Apply GPS Control inputs. request: 2: {} 3: {} @@ -2004,13 +2007,8 @@ messages: request: title: SET request description: >- - Field 1 (GPS is on) is read-only and is rejected with Invalid Parameter (4) if sent. - Field 2 requests the API-controlled correction setting. If absent from a successful - SET, that API flag is cleared; device mode may still require corrections. The API - correction request alone does not keep GPS/RTK running: an external Position - subscription or device-mode ownership is also required. Field 3 records a requested - start mode as pending in current firmware; this SET path does not establish an immediate - hardware restart or enable. + A correction-service request alone does not keep GPS/RTK running; an external + Position subscription or device-mode ownership is also required. headers: 1: {} 5: diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index b1b84df84..d930a7316 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -489,16 +489,26 @@ describe('migrated exchange authoring audit', () => { expect(gpsField.name).toBe(gpsDefinition.name) expect(gpsField.description).toBe(gpsDefinition.description) expect(gpsDefinition.description).toContain('GET reports whether corrections are enabled by the API or device mode') - expect(gps.data[1].description).toContain('active Position-data subscription at the Info-Auto level') + expect(gpsDefinition.description).toContain('Omission from a successful SET clears only the API flag') + expect(gpsDefinition.description).toContain('device mode may still require corrections') + expect(gps.data[1].description).toContain('Position-data subscription at the Info-Auto level is active') expect(gps.data[1].description).toContain('does not directly report hardware power or fix state') - expect(gps.methods.GET.exchange.response.description).toContain('Start Mode is a SET input and is not returned') - expect(gps.methods.SET.exchange.request.description).toContain('rejected with Invalid Parameter (4) if sent') - expect(gps.methods.SET.exchange.request.description).toContain('that API flag is cleared') - expect(gps.methods.SET.exchange.request.description).toContain('device mode may still require corrections') + expect(gps.data[1].description).toContain('read-only') + expect(gps.data[1].description).toContain('rejected with Invalid Parameter (4)') + expect(gps.data[3].description).toContain('records it as pending') + expect(gps.data[3].description).toContain('does not establish an immediate hardware restart or enable') + expect(gps.methods.GET.description).toBe('Return GPS Control state, not a position fix.') + expect(gps.methods.GET.exchange.response.description).toContain('Start Mode is SET-only and is not returned') + expect(gps.methods.GET.exchange.response.description).not.toContain('whether corrections are enabled by the API or device mode') + expect(gps.methods.SET.description).toBe('Apply GPS Control inputs.') + expect(gps.methods.SET.exchange.request.description).not.toMatch(/Field [123]|API flag is cleared|records a requested start mode/) expect(gps.methods.SET.exchange.request.description).toContain('external Position subscription or device-mode ownership is also required') - expect(gps.methods.SET.exchange.request.description).toContain('records a requested start mode as pending in current firmware') - expect(gps.methods.SET.exchange.request.description).not.toMatch(/automatically controls|reboots it|enables it in that mode/) - const set = getMessageDocumentation(gps)!.operations.find(operation => operation.method === 'SET')! + const docs = getMessageDocumentation(gps)! + const get = docs.operations.find(operation => operation.method === 'GET')! + const getFields = resolveDocumentationFields(protocol, gps, get.response!.fields, 'fields') + expect(getFields.find(field => field.id === 1)!.description).toBe(gps.data[1].description) + expect(getFields.find(field => field.id === 2)!.description).toBe(gps.data[2].description) + const set = docs.operations.find(operation => operation.method === 'SET')! const setFields = resolveDocumentationFields(protocol, gps, set.request!.fields, 'fields') expect(setFields.find(field => field.id === 2)!.description).toBe(gps.data[2].description) expect(setFields.find(field => field.id === 3)!.description).toBe(gps.data[3].description) From 8140ec88b73c750d6dd44abf579b7eb463137855 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:38:36 +0000 Subject: [PATCH 10/24] Model V3 exchanges as additive versioned interactions Start the new iteration from current main while retaining this PR's existing history. Keep wire definitions, method maps and captured examples unchanged, and add named references with independent interaction revisions. Reuse existing exchange metadata through a validated resolver and retain existing documentation panels and anchors. Validate with 309 tests, the Next build and desktop/mobile interaction-link checks. --- components/Protocol/Message.vue | 17 +- components/Protocol/StructuredMessagePage.vue | 25 +- cspell.yaml | 3 + devices/api/messages/[messageId].md | 4 +- devices/api/protocol/responses.md | 17 + public/files/protocol-v3.yaml | 704 +++++++++++++----- utils/ByteStringParser.test.ts | 7 - utils/ByteStringParser.ts | 9 +- utils/MessageDocumentation.test.ts | 354 ++++----- utils/MessageDocumentation.ts | 30 +- utils/ProtocolInteractions.ts | 121 +++ yaml-data.data.ts | 7 +- 12 files changed, 822 insertions(+), 476 deletions(-) create mode 100644 utils/ProtocolInteractions.ts diff --git a/components/Protocol/Message.vue b/components/Protocol/Message.vue index b8d6c23fc..823e734b0 100644 --- a/components/Protocol/Message.vue +++ b/components/Protocol/Message.vue @@ -311,7 +311,6 @@ import { readTypedData } from '../../src/protocol/base.gen'; import { formatSentinelValue } from '../../utils/ProtocolSentinels'; import crc16 from 'crc/crc16xmodem'; import { Buffer } from 'buffer'; -import { parseByteString, type ByteStringEncoding } from '../../utils/ByteStringParser'; import Bytes from './Bytes.vue'; interface ByteSection { @@ -341,18 +340,6 @@ export default defineComponent({ type: String, required: true }, - normalizedBytes: { - type: Array as PropType, - default: undefined - }, - encoding: { - type: String as PropType, - default: 'auto' - }, - displayType: { - type: String as PropType<'ints' | 'hex' | 'hex0x' | 'printf'>, - default: 'ints' - }, yamlData: { type: Object as PropType, default: () => ({}) @@ -403,7 +390,7 @@ export default defineComponent({ const isCogModalVisible = ref(false); const isBytesCollapsed = ref(props.defaultCollapsed); - const byteDisplayType = ref<'ints' | 'hex' | 'hex0x' | 'printf'>(props.displayType); + const byteDisplayType = ref<'ints' | 'hex' | 'hex0x' | 'printf'>('ints'); const byteCopySpaces = ref(true); const byteCopyCommas = ref(false); const byteUpperCase = ref(true); @@ -426,8 +413,6 @@ export default defineComponent({ const sectionParseOverrides = ref>({}); const byteArray = computed(() => { - if (props.normalizedBytes) return props.normalizedBytes.map(byte => String(byte)); - if (props.encoding !== 'auto') return parseByteString(props.byteString, props.encoding).bytes.map(byte => String(byte)); const trimmed = props.byteString.trim(); if (!trimmed) return []; diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index a8afa2273..bcd57bc01 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -20,11 +20,11 @@ import { documentationExamplesForContext, documentationTargetOverride, getDocumentationFormat, - getMessageDocumentation, getOperationVariant, resolveDocumentationFields, type DocumentationOperation, } from '../../utils/MessageDocumentation' +import { getInteractionDocumentation } from '../../utils/ProtocolInteractions' const props = defineProps<{ messageId: number @@ -32,7 +32,7 @@ const props = defineProps<{ }>() const message = computed(() => props.yamlData.messages?.[props.messageId]) -const documentation = computed(() => getMessageDocumentation(message.value)) +const documentation = computed(() => getInteractionDocumentation(props.yamlData, props.messageId)) const copyStatus = ref('') const router = useRouter() let removeRouteCorrection: (() => void) | undefined @@ -70,7 +70,7 @@ const panels = computed(() => (documentation.value?.operations || []).flatMap(it examplesTitle: `${label} examples`, title: role === 'request' ? 'Request' : role === 'response' ? `Expected response${view[role] ? ` (MT${contextId}${contextId === 5 ? ' - ACK' : ''})` : ''}` - : `${item.method ? 'Later publication' : 'Device upload'}${view[role] ? ` (MT${contextId})` : ''}`, + : `${item.method ? 'Later publication' : 'Device upload'}${view[role] ? ` (MT${contextId})` : ''}`, subtitle: role !== 'request' && contextId !== 5 && !!item.method ? usage.title?.replace(/\s*\(MT\d+\)$/, '') : undefined, description: usage.description, acknowledgment: usage.messageId === 5, @@ -106,6 +106,11 @@ const panels = computed(() => (documentation.value?.operations || []).flatMap(it }) })) +const interactionLinks = computed(() => (documentation.value?.interactions || []).flatMap(interaction => { + const panel = panels.value.find(item => item.operation.id === interaction.operationId && item.variant.messageVersion === interaction.messageVersion) + return panel ? [{ ...interaction, anchor: panel.anchor }] : [] +})) + function fieldsWithExamples(fields: ReturnType, selectedPanels: typeof panels.value) { const samples = selectedPanels.flatMap(panel => panel.contexts.flatMap(context => context.examples.flatMap(example => capturedDocumentationValues(example, props.messageId, message.value.data, panel.variant.messageVersion).map(sample => ({ @@ -323,6 +328,15 @@ onBeforeUnmount(() => {

{{ documentation.summary }}

Applies to {{ documentation.target }}

+
+ Named interactions + +
@@ -477,7 +491,7 @@ onBeforeUnmount(() => {
- +
Raw bytes @@ -534,6 +548,9 @@ onBeforeUnmount(() => { .structured-message p { color: var(--reference-muted); } .structured-message [id] { scroll-margin-top: calc(var(--message-sticky-top) + var(--message-jump-height, 64px) + 24px); } .structured-message .message-summary { margin: 16px 0 10px; font-size: 16px; line-height: 1.8; white-space: pre-line; } +.interaction-index { margin: 12px 0; } +.interaction-index summary { cursor: pointer; font-weight: 600; } +.structured-message .interaction-index ul { margin: 8px 0; padding-left: 20px; } .support-context { font-size: 12px; } .support-context strong, .target-context strong { margin-right: 8px; font-weight: 600; } .message-navigation { position: sticky; top: var(--message-sticky-top); z-index: 10; min-width: 0; margin: 22px 0; align-self: start; } diff --git a/cspell.yaml b/cspell.yaml index 87abd0e40..bfd692b18 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -43,6 +43,9 @@ words: # Lightbug terms # Acronyms, initialisms, technical terms + - retryable + - nonpositive + - messagedata - RTCM - UART - OBDII diff --git a/devices/api/messages/[messageId].md b/devices/api/messages/[messageId].md index 709261acc..0903df254 100644 --- a/devices/api/messages/[messageId].md +++ b/devices/api/messages/[messageId].md @@ -8,14 +8,14 @@ import { data as protocolData } from '../../../yaml-data.data.ts' import { computed } from 'vue' import { useRoute } from 'vitepress' import { useMessageSections } from '../../../composables/useMessageSections.js' -import { getMessageDocumentation } from '../../../utils/MessageDocumentation' +import { getInteractionDocumentation } from '../../../utils/ProtocolInteractions' import StructuredMessagePage from '../../../components/Protocol/StructuredMessagePage.vue' const route = useRoute() // Extract numeric ID from "12-close" format const messageId = computed(() => parseInt((route.data.params?.messageId || '').split('-')[0])) const messageData = computed(() => protocolData?.messages?.[messageId.value]) -const structuredDocumentation = computed(() => getMessageDocumentation(messageData.value)) +const structuredDocumentation = computed(() => getInteractionDocumentation(protocolData, messageId.value)) // The legacy composable takes a numeric ID; re-create its view when the route changes. const sections = computed(() => useMessageSections(messageId.value, protocolData)) diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 681cd2d6c..f4a8ac8c7 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -52,6 +52,23 @@ A request may select a format, and a response or publication may identify the fo For example, current-format Message Box GET responses and publications carry header 22 with value `2`, but its MT5 control ACKs and terminal subscription status messages do not. Legacy Message Box responses omit it. [Message Box's format sections](../messages/58-message-box#message-58-format-current) describe those differences; the dates used as documentation format names do not replace numeric values on the wire. +## Interaction revisions + +The protocol YAML's `interactions` catalog names documented exchanges that reuse an existing message's method or named context. Resolving an interaction supplies its `request`, direct successful `response` (including ACK where applicable), and/or later or unsolicited `publication` messages from that exchange. It does not guarantee that every stage is sent; the existing correlation, suppression and target rules still apply. This initial catalog describes exchanges, not arbitrary ordered sequences of requests. + +Interaction revisions and wire message formats are independent. For example, the first revision of this interaction uses Message Box's existing format 2: + +```yaml +replace-message-box: + messageId: 58 + method: SET + versions: {1: {messageVersion: 2}} +``` + +`messageVersion` selects an existing method/context variant. It does not itself insert header 22; the referenced exchange defines the actual headers. Unversioned methods or contexts omit `messageVersion`, even when their containing message has versioned payloads. A publication-only interaction references `context` instead of `method`, without inventing a request or wire method. + +Keep field definitions, descriptions, examples and applicability at their existing source. Interactions inherit them; an optional `target` can supply a more specific applicability description without making fields required. References share source semantics, so changes to an exchange require reviewing its interactions; a revision is not a frozen copy of that exchange. Existing `header`, `messages`, `data`, `methods` and message-version definitions remain usable without the catalog. + ## Subscription replies and later updates A subscription's control reply and its later publications are different events. A control ACK reports the command status; it is not the subscribed data. Later publications can have their own headers, payload and status behavior. diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index d9fa1f7ff..38730049c 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -27,15 +27,60 @@ groups: ungrouped: name: Ungrouped description: A collection of ungrouped messages +# Named workflows reuse existing exchanges; their revisions are not wire header 22. +interactions: + read-device-status: + messageId: 34 + method: GET + versions: {1: {}} + subscribe-device-status: + messageId: 34 + method: SUBSCRIBE + versions: {1: {}} + stop-device-status-subscription: + messageId: 34 + method: UNSUBSCRIBE + versions: {1: {}} + read-device-ids: + messageId: 35 + method: GET + versions: {1: {}} + read-gps-state: + messageId: 39 + method: GET + versions: {1: {}} + configure-gps: + messageId: 39 + method: SET + versions: {1: {}} + read-message-box: + messageId: 58 + method: GET + versions: {1: {messageVersion: 1}, 2: {messageVersion: 2}} + replace-message-box: + messageId: 58 + method: SET + versions: {1: {messageVersion: 2}} + subscribe-message-box: + messageId: 58 + method: SUBSCRIBE + versions: {1: {messageVersion: 1}, 2: {messageVersion: 2}} + stop-message-box-subscription: + messageId: 58 + method: UNSUBSCRIBE + versions: {1: {}} + tracking-message-box-upload: + messageId: 58 + context: tracking-session + versions: {1: {messageVersion: 2}} header: 1: name: Message ID id: id description: | ID identifying the message. - A receiver may use it to ACK, respond to, deduplicate, resend or otherwise track messages. + Can be used by a receiver to ACK, respond to, deduplicate, resend or otherwise track messages. Some clients and services may require or desire an incrementing message ID for each message sent, acting as a sequence number. - Responses that support correlation can carry this value in Response To. type: uint32 2: name: Client ID @@ -680,7 +725,7 @@ messages: GET behaviour: - If Key (data field 7 / `key`) is omitted, the response returns a config summary payload (data field 5 / `summary16`). - If Key is provided, the response returns the value for that specific key in Payload (data field 9). - group: general + group: ungrouped data: 3: name: Command @@ -1468,32 +1513,36 @@ messages: title: GET request description: No payload fields are required. Method must be included; this message does not default to GET. headers: - 1: {} - 5: + "1": + presence: optional + description: Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 2 response: title: Device status (MT34) description: >- A successful GET returns Device Status directly, without a separate success ACK. - Returned fields vary by target and available readings. The reviewed Toit - implementation returns firmware information and includes Response To whenever - a Message ID is present, including zero; it does not include an explicit Status - header. Other targets may differ. + Returned fields vary by target and available readings. Response To and Status may + be omitted when the request has no nonzero Message ID. headers: - 3: {} + "3": + presence: optional + "4": + presence: optional + value: 0 fields: - 1: {} - 2: {} - 3: {} - 4: {} - 5: {} - 6: {} - 7: {} - 10: {} - 12: {} - 13: {} - 14: {} + "1": {presence: optional} + "2": {presence: optional} + "3": {presence: optional} + "4": {presence: optional} + "5": {presence: optional} + "6": {presence: optional} + "7": {presence: optional} + "10": {presence: optional} + "12": {presence: optional} + "13": {presence: optional} + "14": {presence: optional} examples: - title: GET exchange provenance: captured @@ -1505,12 +1554,10 @@ messages: frames: - role: request label: GET request for device status - encoding: hex - bytes: 03 14 00 22 00 02 00 05 01 01 02 04 20 62 84 3E 00 00 C2 E5 + bytes: 3 20 0 34 0 2 0 5 1 1 2 4 32 98 132 62 0 0 194 229 - role: response label: Device status response - encoding: hex - bytes: 03 31 00 22 00 02 00 03 04 04 20 62 84 3E 01 00 08 00 01 03 07 0A 02 04 05 06 01 58 01 00 04 EF 08 00 00 01 30 01 40 01 00 02 00 00 02 00 00 6C 5E + bytes: 3 49 0 34 0 2 0 3 4 4 32 98 132 62 1 0 8 0 1 3 7 10 2 4 5 6 1 88 1 0 4 239 8 0 0 1 48 1 64 1 0 2 0 0 2 0 0 108 94 SUBSCRIBE: title: Subscribe to status updates description: >- @@ -1525,17 +1572,31 @@ messages: the default subscription documented here. Updates are subject to the selected interval and message level. headers: - 1: {} - 5: + "1": + presence: optional + description: Include a nonzero Message ID if you need a setup acknowledgment. + "5": presence: required value: 3 - 6: {} - 7: {} - 8: {} - 15: {} - 16: {} - 17: + "6": + presence: optional + description: Publication interval in milliseconds. Omitted or 0 allows updates as new status data becomes available. + "7": + presence: optional + description: Subscription duration in milliseconds. Omitted or 0 keeps the subscription active until unsubscribed. + "8": + presence: optional + description: Time in milliseconds to wait for the first matching status update. Omitted or 0 does not set a timeout. + "15": + presence: optional + description: Storage/retry policy for publications. Defaults to None (0). + "16": + presence: optional + description: Minimum publication level. The default Info-Auto (2) receives normal status updates; no explicit level is required. + "17": + presence: optional value: 0 + description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. response: messageId: 5 title: Response (MT5 - ACK) @@ -1544,9 +1605,9 @@ messages: includes a nonzero Message ID. This acknowledges the request, not delivery of a status update. No acknowledgment is sent for an omitted or zero Message ID. headers: - 3: + "3": presence: required - 4: + "4": presence: required value: 0 publication: @@ -1554,23 +1615,26 @@ messages: description: >- Later status updates produce Device Status messages, filtered by the subscription interval and level. They are not replies to the original SUBSCRIBE request and - do not carry its Response To or Status header. Available payload fields vary by target - and readings. For this subscription, interval 0 or no interval publishes when new - status data is available; duration 0 or no duration is indefinite; timeout 0 or no - timeout sets no first-update deadline. Storage defaults to None (0), and the default - message level is Info-Auto (2). + do not carry its Response To. Available payload fields vary by target and readings. + headers: + "3": + presence: omitted + description: A later publication is not correlated to the subscription request. + "4": + presence: omitted + description: Status updates carry status data, not a command-result envelope. fields: - 1: {} - 2: {} - 3: {} - 4: {} - 5: {} - 6: {} - 7: {} - 10: {} - 12: {} - 13: {} - 14: {} + "1": {presence: optional} + "2": {presence: optional} + "3": {presence: optional} + "4": {presence: optional} + "5": {presence: optional} + "6": {presence: optional} + "7": {presence: optional} + "10": {presence: optional} + "12": {presence: optional} + "13": {presence: optional} + "14": {presence: optional} UNSUBSCRIBE: title: Stop the default status subscription description: >- @@ -1581,8 +1645,10 @@ messages: title: UNSUBSCRIBE request description: No payload fields are required. Omit Subscription ID; this operation removes the default subscription only. headers: - 1: {} - 5: + "1": + presence: optional + description: Include a nonzero Message ID if you need an acknowledgment. + "5": presence: required value: 5 response: @@ -1593,9 +1659,9 @@ messages: request includes a nonzero Message ID. No acknowledgment is sent for an omitted or zero Message ID. headers: - 3: + "3": presence: required - 4: + "4": presence: required value: 0 35: @@ -1643,25 +1709,30 @@ messages: title: GET request description: No payload fields are required. Include Method GET to request the device identifiers. headers: - 1: {} - 5: + "1": + presence: optional + description: Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 2 response: title: Device IDs (MT35) description: >- The GET response contains the available device identifiers. Not all fields are - available on every device type. + available on every device type. Cached SIM2 ICCID is a previously read value + and may be stale. headers: - 3: {} - 4: + "3": + presence: optional + "4": + presence: optional value: 0 fields: - 1: {} - 2: {} - 3: {} - 4: {} - 8: {} + "1": {presence: optional} + "2": {presence: optional} + "3": {presence: optional} + "4": {presence: optional} + "8": {presence: optional} examples: - title: GET exchange provenance: captured @@ -1673,12 +1744,10 @@ messages: frames: - role: request label: GET request for device ids - encoding: hex - bytes: 03 14 00 23 00 02 00 05 01 01 02 04 1F BB 35 E2 00 00 BF A9 + bytes: 3 20 0 35 0 2 0 5 1 1 2 4 31 187 53 226 0 0 191 169 - role: response label: Device IDs response - encoding: hex - bytes: 03 41 00 23 00 02 00 03 04 04 1F BB 35 E2 01 00 03 00 01 02 03 04 03 6D A1 00 0F 38 36 34 39 35 30 30 36 30 32 31 32 35 38 37 14 38 39 34 35 37 33 30 30 30 30 30 30 32 32 32 31 34 38 30 36 06 FB + bytes: 3 65 0 35 0 2 0 3 4 4 31 187 53 226 1 0 3 0 1 2 3 4 3 109 161 0 15 56 54 52 57 53 48 48 54 48 50 49 50 53 56 55 20 56 57 52 53 55 51 48 48 48 48 48 48 50 50 50 49 52 56 48 54 6 251 36: name: Device Time id: deviceTime @@ -1760,7 +1829,7 @@ messages: The cache is replaced when network identity changes or a signal metric changes by more than 3 raw units. Smaller signal changes alone do not replace it. GET and subscription support is firmware-dependent. - group: gsm + group: info header: - 5 data: @@ -1920,19 +1989,13 @@ messages: 1: name: GPS is on id: gpsOn - description: >- - Whether a Position-data subscription at the Info-Auto level is active; - this does not directly report hardware power or fix state. This field is read-only, and - a SET containing it is rejected with Invalid Parameter (4). + description: Status of the GPS, is it on? type: bool readonly: true 2: name: Corrections Enabled id: correctionsOn - description: >- - Correction-service control and status. GET reports whether corrections are enabled by the - API or device mode; SET requests the API-controlled setting. Omission from a successful - SET clears only the API flag; device mode may still require corrections. + description: Request and apply correction data to the GPS, such as RTK. type: uint8 values: 0: @@ -1944,9 +2007,7 @@ messages: 3: name: Start Mode id: startMode - description: >- - GPS start mode requested through SET. Current firmware records it as pending; this SET - path does not establish an immediate hardware restart or enable. + description: Start mode of the GPS module. type: uint8 values: 1: @@ -1964,7 +2025,7 @@ messages: methods: GET: title: Read GPS state - description: Return GPS Control state, not a position fix. + description: Return the current GPS and correction-service state, not a position fix. request: null response: 1: null @@ -1974,49 +2035,92 @@ messages: title: GET request description: No payload fields are needed. headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 2 + fields: + "1": + presence: omitted + "2": + presence: omitted + "3": + presence: omitted response: title: GPS state (MT39) description: >- - A successful GET returns this payload directly, without a separate success ACK. - Start Mode is SET-only and is not returned. An unsuccessful request returns MT5 - (ACK) with Status, not this payload. + A successful GET returns GPS Control directly, with no separate success ACK. + An unsuccessful request returns MT5 (ACK) with Status, not this payload. headers: - 3: {} - 4: + "3": + presence: optional + "4": + presence: optional value: 0 fields: - 1: + "1": presence: required - 2: + description: Whether the GPS service is on. + "2": presence: required + description: Whether correction data is enabled. + values: + "0": Disabled + "1": Full RTCM stream + "3": + presence: omitted + description: Start mode is a SET input, not returned state. errors: - code: 7 description: "Not Supported: the product or firmware does not support this operation." SET: title: Configure corrections and start mode - description: Apply GPS Control inputs. + description: Enable correction data and/or restart the GPS in the requested boot mode. request: - 2: {} - 3: {} + 2: + description: Automatically controls the GPS module. + 3: + description: If the GPS is currently enabled, this will cause the GPS to be rebooted into the requested state. If the GPS is currently disabled, this will cause the GPS to be enabled and the requested state to be set. response: null exchange: request: title: SET request - description: >- - A correction-service request alone does not keep GPS/RTK running; an external - Position subscription or device-mode ownership is also required. + description: Use writable control fields, not the read-only GPS status field. headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 1 fields: - 2: {} - 3: {} + "1": + presence: omitted + description: Read-only status. Sending this field in SET is rejected with Invalid Parameter (4). + "2": + presence: optional + description: >- + Request and apply correction data to the GPS, such as RTK; this automatically controls + the GPS module. Omitting this field sets API-enabled corrections to disabled, so a + start-mode-only SET does not preserve the previous correction setting. Include 1 to + keep API-enabled corrections on. + values: + "0": Disabled + "1": Full RTCM stream + "3": + presence: optional + description: >- + If GPS is enabled, reboot it in this mode. If it is disabled, enable it with the + requested state. + values: + "1": Normal + "2": Cold + "3": Warm + "4": Hot response: messageId: 5 title: Response (MT5 - ACK) @@ -2024,14 +2128,18 @@ messages: For a request with a nonzero Message ID, successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. headers: - 3: {} - 4: + "3": + presence: optional + "4": presence: required value: 0 fields: - 1: + "1": presence: required value: 39 + description: >- + ACK Type identifies the original message type (39). No message-specific state is + returned in this ACK. errors: - code: 4 description: >- @@ -2468,7 +2576,7 @@ messages: id: batteryStatus description: | Get the battery status of a device - group: power + group: info header: - 5 data: @@ -3031,7 +3139,7 @@ messages: name: Charger Settings id: chargerSettings description: For products with configurable charge settings (notably NOT Vehicle RTK), get and define charging parameters - group: power + group: location header: - 5 data: @@ -3184,7 +3292,7 @@ messages: Everything is in 0.1g or degrees for clarity: whilst higher precision data is available, the accuracy can only really be trusted up to 0.1g or 1deg increments, and this keeps the payload size down. **Partial messages:** When only one or more of the per-axis maximum G component fields (keys 9/10/11) change and all other fields are unchanged, the device emits two messages back-to-back. First, a sparse MT_ACCEL_DATA message containing only the changed component field(s) at Q_ChangesOnly level, allowing subscribers to react immediately to axis-level changes. Second, a full MT_ACCEL_DATA message (all fields) at Q_Valid level. In all other cases only one full message is emitted, at Q_ChangesOnly if any field changed or Q_Valid if the store is unchanged. - group: info + group: ungrouped data: 1: name: Version @@ -3272,10 +3380,7 @@ messages: label: "2025-10" description: >- Earlier chunked payload and additive-checksum format, retained for existing integrations. - GET and SUBSCRIBE use it when header 22 is omitted, zero, malformed-width, or set to 1. - Legacy replies and publications omit header 22 and use checksum field 1 plus nonempty - chunks 10-14 concatenated in field-ID order. They do not include CRC field 2 or full-payload - field 129. No legacy SET is supported. + GET and SUBSCRIBE use this format when header 22 is omitted or set to 1. No legacy SET is supported. legacy: true group: info header: @@ -3285,51 +3390,51 @@ messages: 1: name: Legacy Checksum id: legacyChecksum - description: Legacy additive checksum (sum of payload bytes modulo 65536), used in version 1 responses and publications with the legacy chunk fields. Absent from version 2 responses and publications. Optional and ignored in SET. + description: Legacy additive checksum (sum of payload bytes modulo 65536), used in version 1 responses with the legacy chunk fields. Absent from version 2 responses. Optional and ignored in SET. type: uint16 readonly: true versions: [1] 2: name: CRC id: crc - description: CRC-16/XMODEM of the cached payload (polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000), separate from the outer message-frame CRC. Returned in version 2 responses and publications and tracking-session messages, including an empty cache as zero (0x0000). Optional and ignored in SET; the device calculates it from field 129. One- or two-byte little-endian encoding may omit a high zero byte. Implemented only on Viper devices. + description: CRC-16/XMODEM of the cached payload (polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000), separate from the outer message-frame CRC. Returned in version 2 responses and tracking-session messages, including an empty cache as zero (0x0000). Optional and ignored in SET; the device calculates it from field 129. One- or two-byte little-endian encoding may omit a high zero byte. Implemented only on Viper devices. type: uint16 readonly: true versions: [2] 10: name: Legacy Payload Chunk 1 id: legacyChunk1 - description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. + description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 11: name: Legacy Payload Chunk 2 id: legacyChunk2 - description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. + description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 12: name: Legacy Payload Chunk 3 id: legacyChunk3 - description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. + description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 13: name: Legacy Payload Chunk 4 id: legacyChunk4 - description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. + description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 14: name: Legacy Payload Chunk 5 id: legacyChunk5 - description: Message Version 1 cached-payload chunk, up to 255 bytes. Concatenate present chunks in field-ID order; empty chunks are not sent. + description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 129: name: Full Payload id: fullPayload - description: Complete message-box bytes in SET requests, GET responses, and subscription updates (up to 1024 bytes). SET must include this field; an explicit zero-length value clears the cache. GET responses and subscription updates include it only when the cache is nonempty. Uses an extended-length field with a uint16 little-endian length prefix. Tracking-session uploads may use this field for independent Transmit Now data instead. + description: Complete message-box bytes in SET requests, GET responses, and subscription updates (up to 1024 bytes). SET must include this field; an explicit zero-length value clears the cache. Uses an extended-length field with a uint16 little-endian length prefix. Tracking-session uploads may use this field for independent Transmit Now data instead. type: bytes versions: [2] methods: @@ -3352,68 +3457,130 @@ messages: title: GET request description: No payload fields are needed. headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 2 - 22: + "22": presence: required + maxBytes: 1 value: 2 + description: A one-byte value of 2 selects version 2. response: title: Cached payload description: >- A successful GET returns this MT58 payload. An unsuccessful request returns - MT5 (ACK) with Status instead. Version 2 returns CRC field 2; legacy checksum - field 1 and version 1 chunks are not returned. + MT5 (ACK) with Status instead. headers: - 3: {} - 4: + "3": + presence: optional + "4": + presence: optional value: 0 - 22: + "22": presence: required + maxBytes: 1 value: 2 + description: Identifies the format of this response payload. fields: - 2: + "1": + presence: omitted + description: The legacy additive checksum is absent from version 2 responses. + "2": presence: required - 129: + description: >- + Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty + cache. One- or two-byte little-endian encoding may omit a high zero byte. + "129": + presence: optional maxBytes: 1024 + description: >- + Complete cached payload in an extended-length field with a uint16 little-endian + length prefix. Empty payload data is omitted. 1: title: 2025-10 · legacy chunks description: Use the unchanged legacy wire layout and additive checksum. request: title: GET request - description: >- - No payload fields are needed. A missing, zero, or malformed-width Message Version - selects version 1; explicit value 1 also selects version 1. + description: No payload fields are needed. headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 2 - 22: {} + "22": + presence: optional + maxBytes: 1 + description: >- + Omitted, explicitly 0, or malformed-width values resolve to 0 and select version + 1; an explicit 1 also selects version 1. + values: + "0": Version 1 (also the omitted/malformed-width fallback) + "1": Version 1 response: title: Legacy cached payload description: >- A successful GET returns this MT58 payload. An unsuccessful request returns - MT5 (ACK) with Status instead. Legacy replies use checksum field 1 and nonempty - payload chunks 10-14; they do not include header 22, CRC field 2, or field 129. + MT5 (ACK) with Status instead. headers: - 3: {} - 4: + "3": + presence: optional + "4": + presence: optional value: 0 + "22": + presence: omitted + description: >- + Legacy version 1 responses retain their original wire layout and omit Message + Version. fields: - 1: + "1": presence: required - 10: + description: "Additive checksum: sum of all cached payload bytes modulo 65536." + "2": + presence: omitted + description: The CRC field belongs to version 2. + "10": + presence: optional maxBytes: 255 - 11: + description: >- + Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "11": + presence: optional maxBytes: 255 - 12: + description: >- + Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "12": + presence: optional maxBytes: 255 - 13: + description: >- + Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "13": + presence: optional maxBytes: 255 - 14: + description: >- + Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "14": + presence: optional maxBytes: 255 + description: >- + Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "129": + presence: omitted + description: >- + Version 1 retains the legacy wire layout; it does not include the extended + full-payload field. SET: title: Replace or clear the cached message description: >- @@ -3425,20 +3592,29 @@ messages: request: title: SET request description: >- - The device calculates the payload CRC; the outer message-frame CRC protects the SET - request itself. + Message Version 2 and field 129 are required. The device calculates the payload CRC; the + outer message-frame CRC protects the SET request itself. + Optional supplied checksum fields 1 and 2 are ignored. headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 1 - 22: + "22": presence: required + maxBytes: 1 value: 2 + description: A one-byte value of 2 selects version 2. fields: - 129: + "129": presence: required maxBytes: 1024 + description: >- + Complete new cache bytes. An explicit zero-length field clears the cache; omitting the + field is an error. Extended-length encoding uses a uint16 little-endian length prefix. response: messageId: 5 title: Response (MT5 - ACK) @@ -3447,14 +3623,18 @@ messages: the cached bytes; subscriber publications are separate asynchronous messages and are not this reply. headers: - 3: {} - 4: + "3": + presence: optional + "4": presence: required value: 0 fields: - 1: + "1": presence: required value: 58 + description: >- + ACK Type identifies the original message type (58). No message-specific state is + returned in this ACK. errors: - code: 2 description: "Missing Parameter: field 129 is absent." @@ -3482,14 +3662,18 @@ messages: reason. Updates arrive as asynchronous MT58 publications, not as direct replies to SUBSCRIBE. headers: - 3: {} - 4: + "3": + presence: optional + "4": presence: required value: 0 fields: - 1: + "1": presence: required value: 58 + description: >- + ACK Type identifies the original message type (58). No message-specific state is + returned in this ACK. errors: - code: 4 description: >- @@ -3503,36 +3687,69 @@ messages: description: Explicit version 2 selects the shared extended-payload and CRC publication format. request: title: SUBSCRIBE request - description: >- - No payload fields are needed. A nonzero Message ID requests a setup acknowledgment; - omitting Subscription ID selects the default subscription (0). headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 3 - 6: {} - 7: {} - 16: {} - 17: {} - 22: + "6": + presence: optional + description: >- + Optional publication interval in milliseconds. If omitted, updates are sent when + new data is available. + "7": + presence: optional + description: >- + Subscription duration in milliseconds; 0 is indefinite until explicitly + unsubscribed. + "16": + presence: optional + description: Minimum publication level. + "17": + presence: optional + description: >- + Subscription ID; omit for the default subscription (0). Use the same ID when + unsubscribing. + "22": presence: required + maxBytes: 1 value: 2 + description: A one-byte value of 2 selects version 2. publication: title: Cached payload update description: >- - This is an asynchronous cache update, not a direct reply to SUBSCRIBE; it has no - Response To header. Version 2 identifies the format and includes the cached CRC. + Version 2 updates include Message Version 2 and field 2. Field 129 carries the + complete cached payload when nonempty; empty payload data is omitted. headers: - 17: {} - 22: + "3": + presence: omitted + description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. + "17": + presence: optional + description: Identifies nonzero subscription IDs for this publication. + "22": presence: required + maxBytes: 1 value: 2 + description: A one-byte value of 2 selects version 2. fields: - 2: + "1": + presence: omitted + description: The legacy additive checksum is absent from version 2 responses. + "2": presence: required - 129: + description: >- + Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty + cache. One- or two-byte little-endian encoding may omit a high zero byte. + "129": + presence: optional maxBytes: 1024 + description: >- + Complete cached payload in an extended-length field with a uint16 little-endian + length prefix. Empty payload data is omitted. 1: title: Version 1 · legacy publications description: >- @@ -3540,56 +3757,121 @@ messages: publication format. request: title: SUBSCRIBE request - description: >- - No payload fields are needed. A nonzero Message ID requests a setup acknowledgment; - omitting Subscription ID selects the default subscription (0). headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 3 - 6: {} - 7: {} - 16: {} - 17: {} - 22: {} + "6": + presence: optional + description: >- + Optional publication interval in milliseconds. If omitted, updates are sent when + new data is available. + "7": + presence: optional + description: >- + Subscription duration in milliseconds; 0 is indefinite until explicitly + unsubscribed. + "16": + presence: optional + description: Minimum publication level. + "17": + presence: optional + description: >- + Subscription ID; omit for the default subscription (0). Use the same ID when + unsubscribing. + "22": + presence: optional + maxBytes: 1 + description: >- + Omitted, explicitly 0, or malformed-width values resolve to 0 and select version + 1; an explicit 1 also selects version 1. + values: + "0": Version 1 (also the omitted/malformed-width fallback) + "1": Version 1 publication: title: Legacy cached payload update description: >- - This is an asynchronous cache update, not a direct reply to SUBSCRIBE; it has no - Response To header. + Version 1 updates use the additive checksum and legacy chunks. Empty payload data is + omitted. headers: - 17: {} + "3": + presence: omitted + description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. + "17": + presence: optional + description: Identifies nonzero subscription IDs for this publication. + "22": + presence: omitted + description: >- + Legacy version 1 responses retain their original wire layout and omit Message + Version. fields: - 1: + "1": presence: required - 10: + description: "Additive checksum: sum of all cached payload bytes modulo 65536." + "2": + presence: omitted + description: The CRC field belongs to version 2. + "10": + presence: optional maxBytes: 255 - 11: + description: >- + Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "11": + presence: optional maxBytes: 255 - 12: + description: >- + Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "12": + presence: optional maxBytes: 255 - 13: + description: >- + Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "13": + presence: optional maxBytes: 255 - 14: + description: >- + Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "14": + presence: optional maxBytes: 255 + description: >- + Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty + payload data is omitted. + "129": + presence: omitted + description: >- + Version 1 retains the legacy wire layout; it does not include the extended + full-payload field. UNSUBSCRIBE: title: Stop a subscription description: >- Remove the addressed subscription. Neither UNSUBSCRIBE nor subscription expiry resets the - shared publication-format selection. If Subscription ID is absent, this removes the default - subscription (ID 0). + shared publication-format selection. exchange: request: title: UNSUBSCRIBE request description: No payload fields are needed. headers: - 1: {} - 5: + "1": + presence: optional + description: >- + Include a nonzero Message ID to correlate the reply. + "5": presence: required value: 5 - 17: {} - 22: + "17": + presence: optional + description: Use the Subscription ID to remove, or omit it for the default subscription (0). + "22": presence: ignored description: UNSUBSCRIBE does not select or reset the publication format. response: @@ -3601,14 +3883,18 @@ messages: are suppressed for an omitted or zero Message ID; error ACKs are not suppressed for this reason. headers: - 3: {} - 4: + "3": + presence: optional + "4": presence: required value: 0 fields: - 1: + "1": presence: required value: 58 + description: >- + ACK Type identifies the original message type (58). No message-specific state is + returned in this ACK. errors: - code: 7 description: "Not Supported: the product or firmware does not support this operation." @@ -3631,15 +3917,19 @@ messages: for an empty cache. Independent upload bytes in field 129 do not form part of that cached-message CRC. headers: - 22: + "22": presence: required + maxBytes: 1 value: 2 + description: A one-byte value of 2 selects version 2. fields: - 2: + "2": + presence: optional description: >- Present when Message Box support is enabled: CRC-16/XMODEM of the cached down-synced message, not a checksum of the upload in field 129. Zero for an empty cache. - 129: + "129": + presence: optional description: >- Independent Transmit Now upload data; do not compare its CRC with field 2 to validate the upload. @@ -4198,7 +4488,7 @@ messages: name: RTCM Data id: rtcmData description: Data relating to RTCM (Radio Technical Commission for Maritime Services) correction data for high-precision GNSS positioning. - group: location + group: "" data: 1: name: Data @@ -4222,7 +4512,7 @@ messages: name: EPO Data id: epoData description: Data relating to EPO (Extended Prediction Orbit) transfer requests and payload chunks. - group: location + group: "" header: - 5 data: @@ -4275,7 +4565,7 @@ messages: name: File Data id: fileData description: Generic file transfer requests and payload chunks for module firmware and other downloads. - group: general + group: "" header: - 5 data: diff --git a/utils/ByteStringParser.test.ts b/utils/ByteStringParser.test.ts index a4fccd0d7..74f68c062 100644 --- a/utils/ByteStringParser.test.ts +++ b/utils/ByteStringParser.test.ts @@ -2,13 +2,6 @@ import { describe, it, expect } from '@jest/globals'; import { parseByteString, formatBytes, detectNonMessagePatterns } from './ByteStringParser'; describe('ByteStringParser', () => { - it('uses an explicit encoding to parse all-digit hex without decimal guessing', () => { - const hex = parseByteString('03 20 00 22 00 02 00 05', 'hex') - const decimal = parseByteString('3 32 0 34 0 2 0 5', 'decimal') - expect(hex.bytes).toEqual([3, 32, 0, 34, 0, 2, 0, 5]) - expect(decimal.bytes).toEqual(hex.bytes) - expect(parseByteString('03 20 00 22 00 02 00 05', 'hex').hasHex).toBe(true) - }) describe('parseByteString', () => { describe('decimal mode', () => { it('should parse simple space-separated integers', () => { diff --git a/utils/ByteStringParser.ts b/utils/ByteStringParser.ts index 42434b34f..e9527ca51 100644 --- a/utils/ByteStringParser.ts +++ b/utils/ByteStringParser.ts @@ -8,8 +8,6 @@ export interface ParsedBytes { hasHex: boolean; } -export type ByteStringEncoding = 'auto' | 'decimal' | 'hex'; - /** * Extract valid byte values (0-255) from any input string. * Handles messy input with random text, hex values, and decimal integers. @@ -29,16 +27,11 @@ export type ByteStringEncoding = 'auto' | 'decimal' | 'hex'; * @param input - Raw input string potentially containing bytes * @returns Object with parsed bytes array and hex detection flag */ -export function parseByteString(input: string, encoding: ByteStringEncoding = 'auto'): ParsedBytes { +export function parseByteString(input: string): ParsedBytes { if (!input || !input.trim()) { return { bytes: [], hasHex: false }; } - // Explicit encodings are used by structured documentation. Auto remains - // available for the general-purpose log parser used elsewhere in the UI. - if (encoding === 'decimal') return parseDecimalBytes(input); - if (encoding === 'hex') return parseHexBytes(input); - // Check if input looks like base64 first if (looksLikeBase64(input)) { const decoded = tryDecodeBase64(input); diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index d930a7316..83be428ea 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -1,7 +1,8 @@ import { describe, expect, it } from '@jest/globals' import { readFileSync } from 'node:fs' import { resolve } from 'node:path' -import { calculateCRC16XMODEM, getElementByteSize, parseRawMessage, readTypedData } from '../src/protocol/base.gen' +import { getInteractionDocumentation, resolveProtocolInteraction, validateProtocolInteractions } from './ProtocolInteractions' +import { calculateCRC16XMODEM, parseRawMessage, readTypedData } from '../src/protocol/base.gen' // The repository's YAML dependency is intentionally untyped. const yaml = require('js-yaml') import { @@ -31,32 +32,6 @@ describe('Cell Info signal strength terminology', () => { }) }) -describe('protocol message groups', () => { - it('uses existing groups and places every message in its generated sidebar bucket', () => { - const sidebarGroups = Object.fromEntries(Object.keys(protocol.groups).map((group: string) => [group, [] as string[]])) - for (const [id, message] of Object.entries(protocol.messages) as [string, any][]) { - expect(protocol.groups[message.group]).toBeDefined() - sidebarGroups[message.group].push(id) - } - - expect(Object.fromEntries(['14', '37', '43', '54', '57', '2000', '2100', '2101'].map(id => [id, protocol.messages[id].group]))).toEqual({ - '14': 'general', - '37': 'gsm', - '43': 'power', - '54': 'power', - '57': 'info', - '2000': 'location', - '2100': 'location', - '2101': 'general', - }) - for (const id of ['14', '37', '43', '54', '57', '2000', '2100', '2101']) { - expect(sidebarGroups[protocol.messages[id].group]).toContain(id) - } - expect(protocol.messages[1004].group).toBe('ungrouped') - expect(protocol.messages[1005].group).toBe('ungrouped') - }) -}) - describe('paired exchange stages', () => { it('groups frame metadata by stage without mutating order or anchor indices', () => { // Metadata-only fixture; this test does not assert protocol packet bytes. @@ -113,9 +88,8 @@ describe('shared response conventions', () => { expect(context).toEqual(before) }) it('keeps explicit exceptions and non-OK status rules local', () => { + expect(commonResponseHeaderIds({ headers: { '3': { presence: 'omitted' }, '4': { presence: 'required', value: 4 } } })).toEqual([]) expect(commonResponseHeaderIds({ headers: { '3': { presence: 'optional', description: 'A message-specific correlation rule.' }, '4': { presence: 'required', value: 0, maxBytes: 1 } } })).toEqual([]) - expect(commonResponseHeaderIds({ headers: { '3': { presence: 'ignored' }, '4': { value: 0 } } })).toEqual(['4']) - expect(commonResponseHeaderIds({ headers: { '3': {}, '4': { value: 0 } } })).toEqual(['3', '4']) }) it('keeps MT58 version/payload rules and explicit publication correlation distinct', () => { const message = getMessageDocumentation(protocol.messages[58])! @@ -123,37 +97,8 @@ describe('shared response conventions', () => { const subscribe = getOperationVariant(message.operations.find(operation => operation.method === 'SUBSCRIBE')!, '2') expect(commonResponseHeaderIds(get.response!)).toEqual(['3', '4']) expect(get.response?.headers?.['22']).toMatchObject({ presence: 'required', value: 2 }) - const [messageVersionHeader] = resolveDocumentationFields(protocol, protocol.messages[58], get.request?.headers, 'headers').filter(field => field.id === 22) - expect(messageVersionHeader).toMatchObject({ type: 'uint8', presence: 'required', value: 2 }) - expect(messageVersionHeader.maxBytes).toBeUndefined() - expect(getElementByteSize(messageVersionHeader.type!)).toBe(1) - expect(get.response?.fields?.['1']).toBeUndefined() - expect(get.response?.fields?.['129']).toMatchObject({ maxBytes: 1024 }) - expect(get.response?.fields?.['129'].presence).toBeUndefined() - expect(resolveDocumentationFields(protocol, protocol.messages[58], get.response?.fields, 'fields').find(field => field.id === 129)?.presence).toBe('optional') - expect(subscribe.publication?.headers?.['3']).toBeUndefined() - expect(subscribe.publication?.fields?.['1']).toBeUndefined() - const legacyGet = getOperationVariant(message.operations.find(operation => operation.method === 'GET')!, '1') - expect(legacyGet.response?.headers?.['22']).toBeUndefined() - expect(legacyGet.response?.fields?.['2']).toBeUndefined() - expect(legacyGet.response?.fields?.['129']).toBeUndefined() - }) - it('omits type-implied Message Version limits while retaining variable-byte caps', () => { - const message = protocol.messages[58] - const maxBytes: number[] = [] - const visit = (value: any) => { - if (!value || typeof value !== 'object') return - if (value.maxBytes !== undefined) maxBytes.push(value.maxBytes) - for (const child of Object.values(value)) visit(child) - } - visit(message) - expect(maxBytes).not.toContain(1) - expect(maxBytes.filter(limit => limit === 255)).toHaveLength(10) - expect(maxBytes.filter(limit => limit === 1024)).toHaveLength(3) - for (const id of [10, 11, 12, 13, 14, 129]) { - expect(message.data[id].type).toBe('bytes') - } - expect(validateMessageDocumentation(protocol, 58)).toEqual([]) + expect(get.response?.fields?.['129']).toMatchObject({ presence: 'optional', maxBytes: 1024 }) + expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') }) it('corrects only the Processing display label, preserving the existing SDK identifier', () => { expect(protocol.header[4].values[-1]).toMatchObject({ name: 'Processing', id: 'error' }) @@ -198,8 +143,7 @@ describe('optional message documentation', () => { expect(protocol.header[5]).toEqual(before) const fields = resolveDocumentationFields(protocol, protocol.messages[39], { 1: {} }, 'fields') expect(fields[0].description).toBe(protocol.messages[39].data[1].description) - expect(fields[0].presence).toBe('optional') // listed fields default to optional; readonly alone is not required - expect(resolveDocumentationFields(protocol, protocol.messages[39], {}, 'fields')).toEqual([]) // unlisted fields are not added to this exchange + expect(fields[0].presence).toBeUndefined() // readonly does not imply required const ack = resolveDocumentationFields(protocol, protocol.messages[5], { 1: {} }, 'fields') expect(ack[0].name).toBe(protocol.messages[5].data[1].name) expect(ack[0].name).not.toBe(protocol.messages[58].data[1].name) @@ -218,7 +162,6 @@ describe('optional message documentation', () => { response: { messageId: 9999 }, } } message.contexts = { get: { exchange: {} } } - message.methods.GET.exchange.response.fields = { 1: { presence: 'omitted' } } const errors = validateMessageDocumentation(sample, 39).join('\n') expect(errors).toContain('duplicate operation id get') expect(errors).toContain('unsupported method UNSUPPORTED') @@ -227,7 +170,6 @@ describe('optional message documentation', () => { expect(errors).toContain('unknown fields id 99') expect(errors).toContain('unknown message 9999') expect(errors).toContain('invalid note placement') - expect(errors).toContain('response fields 1 has invalid presence') }) it('puts required fields first while preserving order within each group', () => { @@ -235,7 +177,7 @@ describe('optional message documentation', () => { 1: { presence: 'optional' as const }, 4: { presence: 'required' as const }, 5: { presence: 'required' as const }, - 17: {}, + 17: { presence: 'omitted' as const }, 22: { presence: 'optional' as const }, } const before = clone(usage) @@ -350,13 +292,12 @@ describe('inline numeric-version authoring', () => { expect(protocol).toEqual(before) }) - it('preserves direct request/response map presence and field IDs without duplicate field descriptions', () => { + it('preserves direct SDK request/response map presence and field IDs', () => { const gps = protocol.messages[39].methods expect(gps.GET.request).toBeNull() expect(gps.GET.response).toEqual({ 1: null, 2: null }) expect(Object.keys(gps.SET.request)).toEqual(['2', '3']) - expect(gps.SET.request[2]).toEqual({}) - expect(gps.SET.request[3]).toEqual({}) + expect(gps.SET.request[2].description).toBe('Automatically controls the GPS module.') expect(gps.SET.response).toBeNull() for (const method of Object.values(protocol.messages[58].methods) as any[]) { expect(Object.prototype.hasOwnProperty.call(method, 'request')).toBe(false) @@ -421,109 +362,13 @@ describe('inline numeric-version authoring', () => { it('keeps ignored checksums out of SET inputs without deleting the compatibility rule', () => { const set = protocol.messages[58].methods.SET.versions[2] expect(Object.keys(set!.request!.fields)).toEqual(['129']) + expect(set.request.description).toContain('checksum fields 1 and 2 are ignored') expect(set!.request!.fields[129]).toMatchObject({ presence: 'required', maxBytes: 1024 }) - expect(protocol.messages[58].data[1].description).toContain('ignored in SET') - expect(protocol.messages[58].data[2].description).toContain('ignored in SET') const get = protocol.messages[58].methods.GET.versions[2] expect(get.response.fields[2].presence).toBe('required') }) }) -describe('migrated exchange authoring audit', () => { - const migratedIds = [34, 35, 39, 58] - const normalized = (value: unknown) => typeof value === 'string' ? value.trim().replace(/\s+/g, ' ') : value - - it('does not restate optional presence or inherited metadata in exchange maps', () => { - const inspectExchange = (message: any, exchange: any) => { - if (!exchange || typeof exchange !== 'object') return - for (const role of ['request', 'response', 'publication']) { - const context = exchange[role] - if (!context || typeof context !== 'object') continue - const contextMessage = context.messageId === undefined ? message : protocol.messages[context.messageId] - for (const kind of ['headers', 'fields'] as const) { - const definitions = kind === 'headers' ? protocol.header : contextMessage?.data - for (const [id, usage] of Object.entries(context[kind] || {}) as [string, any][]) { - const definition = definitions?.[id] - expect(usage.presence).not.toBe('optional') - expect(usage.presence).not.toBe('omitted') - if (!definition) continue - for (const key of ['description', 'name', 'id', 'type', 'unit', 'maxBytes']) { - if (usage[key] !== undefined && definition[key] !== undefined) { - expect(normalized(usage[key])).not.toBe(normalized(definition[key])) - } - } - for (const [value, override] of Object.entries(usage.values || {}) as [string, any][]) { - const inherited = definition.values?.[value] - if (!inherited) continue - const inheritedName = typeof inherited === 'string' ? inherited : inherited.name - const inheritedDescription = typeof inherited === 'string' ? undefined : inherited.description - const localDescription = typeof override === 'string' ? override : override?.description - if (typeof override === 'string') expect(normalized(override)).not.toBe(normalized(inheritedName)) - if (override?.name !== undefined) expect(normalized(override.name)).not.toBe(normalized(inheritedName)) - if (localDescription !== undefined && inheritedDescription !== undefined) { - expect(normalized(localDescription)).not.toBe(normalized(inheritedDescription)) - } - if (localDescription !== undefined) expect(normalized(localDescription)).not.toBe(normalized(inheritedName)) - } - } - } - } - } - const inspectSource = (message: any, source: any) => { - if (!source || typeof source !== 'object') return - if (source.exchange) inspectExchange(message, source.exchange) - for (const exchange of Object.values(source.versions || {})) inspectExchange(message, exchange) - } - - for (const id of migratedIds) { - const message = protocol.messages[id] - for (const source of Object.values(message.methods || {})) inspectSource(message, source) - for (const source of Object.values(message.contexts || {})) inspectSource(message, source) - } - }) - - it('inherits global field names, descriptions and enum labels without changing their rendered values', () => { - const gps = protocol.messages[39] - const [gpsField] = resolveDocumentationFields(protocol, gps, { 2: {} }, 'fields') - const gpsDefinition = gps.data[2] - expect(gpsField.name).toBe(gpsDefinition.name) - expect(gpsField.description).toBe(gpsDefinition.description) - expect(gpsDefinition.description).toContain('GET reports whether corrections are enabled by the API or device mode') - expect(gpsDefinition.description).toContain('Omission from a successful SET clears only the API flag') - expect(gpsDefinition.description).toContain('device mode may still require corrections') - expect(gps.data[1].description).toContain('Position-data subscription at the Info-Auto level is active') - expect(gps.data[1].description).toContain('does not directly report hardware power or fix state') - expect(gps.data[1].description).toContain('read-only') - expect(gps.data[1].description).toContain('rejected with Invalid Parameter (4)') - expect(gps.data[3].description).toContain('records it as pending') - expect(gps.data[3].description).toContain('does not establish an immediate hardware restart or enable') - expect(gps.methods.GET.description).toBe('Return GPS Control state, not a position fix.') - expect(gps.methods.GET.exchange.response.description).toContain('Start Mode is SET-only and is not returned') - expect(gps.methods.GET.exchange.response.description).not.toContain('whether corrections are enabled by the API or device mode') - expect(gps.methods.SET.description).toBe('Apply GPS Control inputs.') - expect(gps.methods.SET.exchange.request.description).not.toMatch(/Field [123]|API flag is cleared|records a requested start mode/) - expect(gps.methods.SET.exchange.request.description).toContain('external Position subscription or device-mode ownership is also required') - const docs = getMessageDocumentation(gps)! - const get = docs.operations.find(operation => operation.method === 'GET')! - const getFields = resolveDocumentationFields(protocol, gps, get.response!.fields, 'fields') - expect(getFields.find(field => field.id === 1)!.description).toBe(gps.data[1].description) - expect(getFields.find(field => field.id === 2)!.description).toBe(gps.data[2].description) - const set = docs.operations.find(operation => operation.method === 'SET')! - const setFields = resolveDocumentationFields(protocol, gps, set.request!.fields, 'fields') - expect(setFields.find(field => field.id === 2)!.description).toBe(gps.data[2].description) - expect(setFields.find(field => field.id === 3)!.description).toBe(gps.data[3].description) - expect(gpsField.values.map(({ value, name, description }: any) => ({ value, name, description }))).toEqual([ - { value: 0, name: gpsDefinition.values[0].name, description: gpsDefinition.values[0].description || '' }, - { value: 1, name: gpsDefinition.values[1].name, description: gpsDefinition.values[1].description || '' }, - ]) - - const [methodHeader] = resolveDocumentationFields(protocol, gps, { 5: { presence: 'required', value: 1 } }, 'headers') - expect(methodHeader.name).toBe(protocol.header[5].name) - expect(methodHeader.description).toBe(protocol.header[5].description) - expect(methodHeader.valueName).toBe(protocol.header[5].values[1].name) - }) -}) - describe('Device Status reference', () => { const message = protocol.messages[34] @@ -541,16 +386,6 @@ describe('Device Status reference', () => { } expect(validateMessageDocumentation(protocol, 34)).toEqual([]); }); - it('qualifies Toit MT34 GET response headers by target', () => { - const get = docs.operations.find((operation: DocumentationOperation) => operation.method === 'GET')! - const response = get.response! - expect(response.description).toContain('reviewed Toit implementation') - expect(response.description).toContain('whenever a Message ID is present, including zero') - expect(response.description).toContain('does not include an explicit Status header') - expect(response.description).toContain('Other targets may differ') - expect(response.headers?.['3']).toBeDefined() - expect(response.headers?.['4']).toBeUndefined() - }) it('keeps the existing methods and wire fields without inventing a message version', () => { expect(Object.keys(message.methods)).toEqual(['GET', 'SUBSCRIBE', 'UNSUBSCRIBE']) expect(message.versions).toBeUndefined() @@ -577,16 +412,12 @@ describe('Device Status reference', () => { expect(get.response?.messageId).toBeUndefined() expect(subscribe.response?.messageId).toBe(5) expect(unsubscribe.response?.messageId).toBe(5) - expect(subscribe.publication?.headers?.['3']).toBeUndefined() - expect(subscribe.request?.headers?.['17']).toMatchObject({ value: 0 }) - expect(subscribe.request?.headers?.['17'].presence).toBeUndefined() - expect(resolveDocumentationFields(protocol, message, subscribe.request?.headers, 'headers').find(field => field.id === 17)?.presence).toBe('optional') - expect(subscribe.publication?.headers?.['4']).toBeUndefined() + expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') + expect(subscribe.request?.headers?.['17']).toMatchObject({ presence: 'optional', value: 0 }) expect(unsubscribe.request?.headers?.['17']).toBeUndefined() for (const context of [get.response, subscribe.publication]) { expect(Object.keys(context!.fields!)).toEqual(Object.keys(message.data)) - expect(Object.values(context!.fields!).every(field => field.presence === undefined)).toBe(true) - expect(resolveDocumentationFields(protocol, message, context!.fields, 'fields').every(field => field.presence === 'optional')).toBe(true) + expect(Object.values(context!.fields!).every(field => field.presence === 'optional')).toBe(true) } expect(subscribe.examples).toBeUndefined() expect(unsubscribe.examples).toBeUndefined() @@ -598,12 +429,10 @@ describe('Device Status reference', () => { expect(example.target).toBe('RH2 over I2C') expect(example.frames.map(frame => frame.role)).toEqual(['request', 'response']) expect(example.frames.map(frame => frame.bytes)).toEqual([ - '03 14 00 22 00 02 00 05 01 01 02 04 20 62 84 3E 00 00 C2 E5', - '03 31 00 22 00 02 00 03 04 04 20 62 84 3E 01 00 08 00 01 03 07 0A 02 04 05 06 01 58 01 00 04 EF 08 00 00 01 30 01 40 01 00 02 00 00 02 00 00 6C 5E', + '3 20 0 34 0 2 0 5 1 1 2 4 32 98 132 62 0 0 194 229', + '3 49 0 34 0 2 0 3 4 4 32 98 132 62 1 0 8 0 1 3 7 10 2 4 5 6 1 88 1 0 4 239 8 0 0 1 48 1 64 1 0 2 0 0 2 0 0 108 94', ]) - expect(example.frames.every(frame => frame.encoding === 'hex')).toBe(true) - expect(example.frames[0].normalizedBytes).toEqual([3, 20, 0, 34, 0, 2, 0, 5, 1, 1, 2, 4, 32, 98, 132, 62, 0, 0, 194, 229]) - const frames = example.frames.map(frame => frame.normalizedBytes!) + const frames = example.frames.map(frame => frame.bytes.split(' ').map(Number)) for (const bytes of frames) { expect(calculateCRC16XMODEM(bytes.slice(0, -2))).toBe(bytes[bytes.length - 2] | bytes[bytes.length - 1] << 8) expect(parseRawMessage(bytes)).toMatchObject({ protocolVersion: 3, length: bytes.length, messageType: 34 }) @@ -627,13 +456,13 @@ describe('Device Status reference', () => { expect(capturedDocumentationValues(example, 58, message.data)).toEqual([]) expect(capturedDocumentationValues(example, 34, message.data, 2)).toEqual([]) const invalid = clone(example) - invalid.frames[1].normalizedBytes!.push(0) + invalid.frames[1].bytes += ' 0' expect(capturedDocumentationValues(invalid, 34, message.data)).toEqual([]) - const bytes = [...example.frames[1].normalizedBytes!] + const bytes = example.frames[1].bytes.split(' ').map(Number) bytes[26] = 255 // Invalid first payload length, even with a recomputed checksum. const crc = calculateCRC16XMODEM(bytes.slice(0, -2)) bytes.splice(-2, 2, crc & 255, crc >> 8) - invalid.frames[1].normalizedBytes = bytes + invalid.frames[1].bytes = bytes.join(' ') expect(capturedDocumentationValues(invalid, 34, message.data)).toEqual([]) const badType = { ...message.data, 7: { ...message.data[7], type: 'uint8' } } expect(capturedDocumentationValues(example, 34, badType).some(field => field.id === 7)).toBe(false) @@ -660,25 +489,11 @@ describe('Device IDs reference', () => { ['4', 'serial', 'uint32'], ['8', 'cachedIccid2', 'ascii'], ]) expect(Object.keys(get.response!.fields!)).toEqual(Object.keys(message.data)) - expect(Object.values(get.response!.fields!).every(field => field.presence === undefined)).toBe(true) - expect(resolveDocumentationFields(protocol, message, get.response?.fields, 'fields').every(field => field.presence === 'optional')).toBe(true) - expect(get.response?.description).not.toContain('may be stale') + expect(Object.values(get.response!.fields!).every(field => field.presence === 'optional')).toBe(true) + expect(get.response?.description).toContain('may be stale') expect(message.examples).toBeUndefined() expect(validateMessageDocumentation(protocol, 35)).toEqual([]) }) - it('normalizes the original captured ID exchange and verifies its CRC', () => { - const [example] = get.examples! - expect(example.provenance).toBe('captured') - expect(example.frames.every(frame => frame.encoding === 'hex')).toBe(true) - expect(example.frames[0].normalizedBytes).toEqual([3, 20, 0, 35, 0, 2, 0, 5, 1, 1, 2, 4, 31, 187, 53, 226, 0, 0, 191, 169]) - const [request, response] = example.frames.map(frame => frame.normalizedBytes!) - for (const bytes of [request, response]) { - expect(calculateCRC16XMODEM(bytes.slice(0, -2))).toBe(bytes[bytes.length - 2] | bytes[bytes.length - 1] << 8) - expect(parseRawMessage(bytes)).toMatchObject({ protocolVersion: 3, length: bytes.length, messageType: 35 }) - } - expect(parseRawMessage(request).data).toEqual({}) - expect(Object.keys(parseRawMessage(response).data)).toEqual(['1', '2', '3']) - }) it('preserves and decodes the captured GET pair without inventing serial or SIM2 samples', () => { const [example] = get.examples! @@ -688,8 +503,11 @@ describe('Device IDs reference', () => { expect(example.description).toContain('RH2 P1 v2287') expect(example.target).toBe('RH2 over I2C') expect(example.frames.map(frame => frame.role)).toEqual(['request', 'response']) - expect(example.frames.every(frame => frame.encoding === 'hex')).toBe(true) - const frames = example.frames.map(frame => frame.normalizedBytes!) + expect(example.frames.map(frame => frame.bytes)).toEqual([ + '3 20 0 35 0 2 0 5 1 1 2 4 31 187 53 226 0 0 191 169', + '3 65 0 35 0 2 0 3 4 4 31 187 53 226 1 0 3 0 1 2 3 4 3 109 161 0 15 56 54 52 57 53 48 48 54 48 50 49 50 53 56 55 20 56 57 52 53 55 51 48 48 48 48 48 48 50 50 50 49 52 56 48 54 6 251', + ]) + const frames = example.frames.map(frame => frame.bytes.split(' ').map(Number)) for (const bytes of frames) { expect(calculateCRC16XMODEM(bytes.slice(0, -2))).toBe(bytes[bytes.length - 2] | bytes[bytes.length - 1] << 8) expect(parseRawMessage(bytes)).toMatchObject({ protocolVersion: 3, length: bytes.length, messageType: 35 }) @@ -709,3 +527,123 @@ describe('Device IDs reference', () => { expect(documentationExamplesForContext(get.examples!, 'response')[0].stageTitle).toBe('GET exchange response') }) }) + +describe('additive interaction references', () => { + it('validates the catalogue and preserves every referenced exchange without mutating the spec', () => { + const before = clone(protocol) + expect(Object.keys(protocol.interactions).length).toBeGreaterThan(0) + expect(validateProtocolInteractions(protocol)).toEqual([]) + for (const [id, reference] of Object.entries(protocol.interactions) as [string, any][]) { + const source = getMessageDocumentation(protocol.messages[reference.messageId])! + .operations.find(operation => operation.id === (reference.method?.toLowerCase() ?? reference.context))! + for (const [revision, selection] of Object.entries(reference.versions) as [string, any][]) { + const resolved = resolveProtocolInteraction(protocol, id, Number(revision)) + const original = source.variants ? getOperationVariant(source, String(selection.messageVersion)) : source + for (const key of ['request', 'response', 'publication', 'errors', 'examples', 'format', 'anchorId'] as const) { + expect(resolved[key]).toEqual(original[key]) + } + expect(resolved.interactionId).toBe(id) + expect(resolved.interactionVersion).toBe(Number(revision)) + expect(resolved.messageId).toBe(reference.messageId) + expect(resolved.operationId).toBe(source.id) + } + const rendered = getInteractionDocumentation(protocol, reference.messageId)! + .operations.find(operation => operation.id === source.id)! + expect(rendered.id).toBe(source.id) + expect(rendered.title).toBe(source.title) + expect(getInteractionDocumentation(protocol, reference.messageId)!.operations) + .toEqual(getMessageDocumentation(protocol.messages[reference.messageId])!.operations) + } + expect(protocol).toEqual(before) + }) + + it('keeps interaction revisions independent from wire versions and resolves ACKs against MT5', () => { + const sample = clone(protocol) + sample.interactions = { replace: { messageId: 58, method: 'SET', versions: { 700: { messageVersion: 2 } } } } + expect(validateProtocolInteractions(sample)).toEqual([]) + const resolved = resolveProtocolInteraction(sample, 'replace', 700) + expect(resolved).toMatchObject({ interactionVersion: 700, messageVersion: 2, format: '2', anchorId: 'v2' }) + expect(resolved.request?.headers?.[22].value).toBe(2) + expect(resolved.response?.messageId).toBe(5) + expect(resolved.response?.fields?.[1].value).toBe(58) + expect(resolveDocumentationFields(sample, sample.messages[5], resolved.response?.fields, 'fields')[0].name) + .toBe(sample.messages[5].data[1].name) + }) + + it('allows independent applicability revisions and aliases without changing existing operation panels or anchors', () => { + const sample = clone(protocol) + sample.interactions = { replace: { messageId: 58, method: 'SET', target: 'Inherited interaction target', versions: { + 1: { messageVersion: 2, target: 'First target' }, + 2: { messageVersion: 2, target: 'Second target' }, + } } } + expect(validateProtocolInteractions(sample)).toEqual([]) + expect(resolveProtocolInteraction(sample, 'replace', 1).target).toBe('First target') + expect(resolveProtocolInteraction(sample, 'replace', 2).target).toBe('Second target') + sample.interactions['replace-alias'] = { messageId: 58, method: 'SET', target: 'Alias target', versions: { 1: { messageVersion: 2 } } } + expect(validateProtocolInteractions(sample)).toEqual([]) + expect(resolveProtocolInteraction(sample, 'replace-alias', 1)).toMatchObject({ target: 'Alias target', operationId: 'set', messageId: 58 }) + const rendered = getInteractionDocumentation(sample, 58)! + expect(rendered.operations).toEqual(getMessageDocumentation(sample.messages[58])!.operations) + expect(rendered.interactions).toHaveLength(3) + expect(rendered.interactions!.map(interaction => interaction.target)).toEqual(['Second target', 'First target', 'Alias target']) + delete sample.interactions.replace.versions[2].target + expect(resolveProtocolInteraction(sample, 'replace', 2).target).toBe('Inherited interaction target') + delete sample.interactions.replace.target + expect(resolveProtocolInteraction(sample, 'replace', 2).target).toBe(protocol.messages[58].target) + }) + + it('supports publication-only interactions and keeps unlisted operations on their legacy path', () => { + const sample = clone(protocol) + sample.interactions = { upload: { messageId: 58, context: 'tracking-session', versions: { 1: { messageVersion: 2 } } } } + const upload = resolveProtocolInteraction(sample, 'upload', 1) + expect(upload.publication).toBeDefined() + expect(upload.request).toBeUndefined() + expect(upload.response).toBeUndefined() + expect(upload.method).toBeUndefined() + const old = getMessageDocumentation(sample.messages[58])! + const next = getInteractionDocumentation(sample, 58)! + expect(next.operations.filter(operation => operation.method)).toEqual(old.operations.filter(operation => operation.method)) + expect(getInteractionDocumentation(sample, 39)).toEqual(getMessageDocumentation(sample.messages[39])) + delete sample.interactions + expect(getInteractionDocumentation(sample, 58)).toEqual(old) + expect(getInteractionDocumentation(sample, 5)).toBeUndefined() + }) + + it.each([ + ['unknown message', (reference: any) => { reference.messageId = 65534 }], + ['unknown method', (reference: any) => { reference.method = 'MISSING' }], + ['malformed method', (reference: any) => { reference.method = 5 }], + ['ambiguous selector', (reference: any) => { reference.context = 'tracking-session' }], + ['missing selector', (reference: any) => { delete reference.method }], + ['missing wire version', (reference: any) => { reference.versions = { 1: {} } }], + ['unknown wire version', (reference: any) => { reference.versions[1].messageVersion = 99 }], + ['empty revisions', (reference: any) => { reference.versions = {} }], + ['zero revision', (reference: any) => { reference.versions = { 0: { messageVersion: 2 } } }], + ['unsafe revision', (reference: any) => { reference.versions = { '9007199254740992': { messageVersion: 2 } } }], + ['non-object selection', (reference: any) => { reference.versions = { 1: null } }], + ['duplicated metadata', (reference: any) => { reference.description = 'Duplicate source description' }], + ['invalid target', (reference: any) => { reference.target = [] }], + ])('rejects %s before documentation can silently fall back', (_label, change) => { + const sample = clone(protocol) + sample.interactions = { read: { messageId: 58, method: 'GET', versions: { 1: { messageVersion: 2 } } } } + change(sample.interactions.read) + expect(validateProtocolInteractions(sample).length).toBeGreaterThan(0) + expect(() => getInteractionDocumentation(sample, 58)).toThrow() + }) + + it('rejects missing contexts, empty exchanges and versions on unversioned messages', () => { + const sample = clone(protocol) + sample.interactions = { read: { messageId: 39, method: 'GET', versions: { 1: {} } } } + expect(() => resolveProtocolInteraction(sample, 'missing', 1)).toThrow('Unknown interaction') + expect(() => resolveProtocolInteraction(sample, 'read', 2)).toThrow('unknown revision') + sample.interactions.read.versions[1] = { messageVersion: 1 } + expect(validateProtocolInteractions(sample).join('\n')).toContain('unversioned source') + sample.interactions.read.versions[1] = {} + sample.messages[39].methods.GET = { exchange: {} } + expect(validateProtocolInteractions(sample).join('\n')).toContain('at least one request, response or publication') + sample.interactions.read = { messageId: 58, context: 'missing', versions: { 1: { messageVersion: 2 } } } + expect(validateProtocolInteractions(sample).join('\n')).toContain('unknown context') + sample.interactions = [] + expect(validateProtocolInteractions(sample)).toEqual(['Protocol interactions must be a mapping']) + }) +}) diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index cc559e7bd..92e288521 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -1,12 +1,11 @@ import { calculateCRC16XMODEM, getElementByteSize, parseRawMessage, readTypedData } from '../src/protocol/base.gen' -import { parseByteString, type ByteStringEncoding } from './ByteStringParser' +import { parseByteString } from './ByteStringParser' import { formatSentinelValue } from './ProtocolSentinels' /** Structured message documentation. Wire definitions remain in header and message.data. */ export interface DocumentationField { description?: string - /** Omit for the normal optional case; use ignored only for accepted-but-ignored inputs. */ - presence?: 'required' | 'optional' | 'ignored' + presence?: 'required' | 'optional' | 'ignored' | 'omitted' value?: number values?: Record maxBytes?: number @@ -25,7 +24,7 @@ export interface DocumentationContext { export function commonResponseHeaderIds(context: DocumentationContext): string[] { return Object.entries(context.headers || {}).filter(([id, field]) => { if (field.description || field.values || field.maxBytes !== undefined || - !['required', 'optional', undefined].includes(field.presence)) return false + !['required', 'optional'].includes(field.presence || '')) return false return id === '3' && field.value === undefined || id === '4' && field.value === 0 }).map(([id]) => id) } @@ -35,17 +34,7 @@ export interface DocumentationExample { provenance: 'generated' | 'captured' description?: string target?: string - frames: { role: 'request' | 'response' | 'publication' | 'upload'; label: string; bytes: string; encoding?: ByteStringEncoding; normalizedBytes?: number[] }[] -} - -function normalizeDocumentationExamples(examples: DocumentationExample[] = []): DocumentationExample[] { - return examples.map(example => ({ - ...example, - frames: example.frames.map(frame => ({ - ...frame, - normalizedBytes: parseByteString(frame.bytes, frame.encoding || 'auto').bytes, - })), - })) + frames: { role: 'request' | 'response' | 'publication' | 'upload'; label: string; bytes: string }[] } /** Align each exchange stage without changing frame order or published anchors. */ @@ -64,7 +53,7 @@ export function capturedDocumentationValues(example: DocumentationExample, messa if (example.provenance !== 'captured') return [] return example.frames.flatMap(frame => { try { - const bytes = frame.normalizedBytes ?? parseByteString(frame.bytes, frame.encoding || 'auto').bytes + const { bytes } = parseByteString(frame.bytes) const start = bytes[0] === 0x4c && bytes[1] === 0x42 ? 2 : 0 const parsed = parseRawMessage(bytes) if (parsed.protocolVersion !== 3 || parsed.messageType !== messageId || parsed.encrypted || parsed.length !== bytes.length - start) return [] @@ -193,7 +182,6 @@ export function getMessageDocumentation(message: any): MessageDocumentation | un const addOperation = (id: string, source: any, method?: string) => { if (!source || (!source.exchange && !source.versions)) return const contextualDescriptions = (exchange: any) => Object.fromEntries(Object.entries(exchange || {}).map(([key, value]: [string, any]) => { - if (key === 'examples') return [key, normalizeDocumentationExamples(value)] if (!['request', 'response'].includes(key) || !value?.fields || value.messageId !== undefined) return [key, value] return [key, { ...value, fields: Object.fromEntries(Object.entries(value.fields).map(([id, usage]: [string, any]) => [ id, { description: source[key]?.[id]?.description, ...usage }, @@ -263,9 +251,7 @@ export function resolveDocumentationFields( sentinels: definition.sentinels, baseDescription: definition.description || '', description: context.description ?? definition.description ?? '', - // Only entries explicitly listed in an exchange context are shown; - // absent presence on such an entry means optional, not forbidden. - presence: context.presence ?? 'optional', + presence: context.presence, value: context.value, valueName: context.value === undefined ? undefined : definition.values?.[context.value]?.name, values: Object.entries(context.values ?? (context.value === undefined ? definition.values || {} : {})).map(([value, details]: [string, any]) => ({ @@ -345,7 +331,7 @@ function validateInlineDocumentation(message: any): string[] { if (context?.messageId !== undefined) continue for (const [id, usage] of Object.entries(context?.fields || {}) as [string, any][]) { const applicable = message.data?.[id]?.versions - if (Array.isArray(applicable) && !applicable.includes(Number(version)) && usage?.presence !== 'ignored') { + if (Array.isArray(applicable) && !applicable.includes(Number(version)) && !['omitted', 'ignored'].includes(usage?.presence)) { errors.push(`${name}/${version} ${role} uses field ${id} outside its versions`) } } @@ -407,7 +393,7 @@ export function validateMessageDocumentation(protocol: any, messageId: number): fail(`${label} ${kind} ${key} must be an object`) continue } - if (field.presence && !['required', 'optional', 'ignored'].includes(field.presence)) { + if (field.presence && !['required', 'optional', 'ignored', 'omitted'].includes(field.presence)) { fail(`${label} ${kind} ${key} has invalid presence`) } if (field.maxBytes !== undefined && (!Number.isInteger(field.maxBytes) || field.maxBytes < 0)) { diff --git a/utils/ProtocolInteractions.ts b/utils/ProtocolInteractions.ts new file mode 100644 index 000000000..4208d8022 --- /dev/null +++ b/utils/ProtocolInteractions.ts @@ -0,0 +1,121 @@ +import { + getMessageDocumentation, + type DocumentationOperation, + type DocumentationVariant, + type MessageDocumentation, +} from './MessageDocumentation' + +interface InteractionReference { + messageId: number + method?: string + context?: string + target?: string + versions: Record +} + +export type ResolvedProtocolInteraction = DocumentationVariant & { + interactionId: string + interactionVersion: number + messageId: number + operationId: string + method?: string +} + +const object = (value: any): value is Record => !!value && typeof value === 'object' && !Array.isArray(value) +const selector = (reference: InteractionReference) => reference.method?.toLowerCase() ?? reference.context! +const sourceFor = (protocol: any, reference: InteractionReference) => { + const message = protocol.messages?.[reference.messageId] + return reference.method === undefined ? message?.contexts?.[reference.context!] : message?.methods?.[reference.method] +} + +/** Interactions reference existing documentation; they never redefine wire messages or exchanges. */ +export function validateProtocolInteractions(protocol: any): string[] { + if (protocol.interactions === undefined) return [] + if (!object(protocol.interactions)) return ['Protocol interactions must be a mapping'] + const errors: string[] = [] + const keys = (value: Record, allowed: string[], label: string) => { + for (const key of Object.keys(value)) if (!allowed.includes(key)) errors.push(`${label}: unknown property ${key}`) + } + const target = (value: any, label: string) => { + if (value !== undefined && (typeof value !== 'string' || !value.trim())) errors.push(`${label}: target must be a nonempty string`) + } + for (const [id, value] of Object.entries(protocol.interactions)) { + const label = `Interaction ${id}` + if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(id)) errors.push(`${label}: needs a stable lowercase id`) + if (!object(value)) { errors.push(`${label}: must be an object`); continue } + keys(value, ['messageId', 'method', 'context', 'versions', 'target'], label) + target(value.target, label) + const reference = value as unknown as InteractionReference + if (!Number.isSafeInteger(reference.messageId) || reference.messageId < 0 || !protocol.messages?.[reference.messageId]) errors.push(`${label}: references unknown message ${reference.messageId}`) + if ((reference.method === undefined) === (reference.context === undefined)) errors.push(`${label}: needs exactly one method or context`) + if (reference.method !== undefined && (typeof reference.method !== 'string' || !Object.prototype.hasOwnProperty.call(protocol.messages?.[reference.messageId]?.methods || {}, reference.method))) errors.push(`${label}: references unknown method ${reference.method}`) + if (reference.context !== undefined && (typeof reference.context !== 'string' || !Object.prototype.hasOwnProperty.call(protocol.messages?.[reference.messageId]?.contexts || {}, reference.context))) errors.push(`${label}: references unknown context ${reference.context}`) + const source = sourceFor(protocol, reference) + if (!object(source) || (!source.exchange && !source.versions)) errors.push(`${label}: source needs an exchange or versions`) + if (!object(reference.versions) || !Object.keys(reference.versions).length) { errors.push(`${label}: versions must be a nonempty mapping`); continue } + for (const [revision, selection] of Object.entries(reference.versions)) { + const versionLabel = `${label}/${revision}` + if (!/^[1-9]\d*$/.test(revision) || !Number.isSafeInteger(Number(revision))) errors.push(`${versionLabel}: revision must be a positive safe integer`) + if (!object(selection)) { errors.push(`${versionLabel}: must be an object`); continue } + keys(selection, ['messageVersion', 'target'], versionLabel) + target(selection.target, versionLabel) + if (source?.versions !== undefined) { + if (typeof selection.messageVersion !== 'number' || !Number.isInteger(selection.messageVersion)) errors.push(`${versionLabel}: needs an explicit messageVersion`) + else if (!Object.prototype.hasOwnProperty.call(source.versions, selection.messageVersion)) errors.push(`${versionLabel}: references unknown source messageVersion ${selection.messageVersion}`) + else if (!Object.prototype.hasOwnProperty.call(protocol.messages?.[reference.messageId]?.versions || {}, selection.messageVersion)) errors.push(`${versionLabel}: references unknown messageVersion ${selection.messageVersion}`) + } else if (selection.messageVersion !== undefined) errors.push(`${versionLabel}: unversioned source cannot select messageVersion`) + const exchange = { ...source?.exchange, ...source?.versions?.[selection.messageVersion!] } + if (!['request', 'response', 'publication'].some(role => object(exchange[role]))) errors.push(`${versionLabel}: source needs at least one request, response or publication message`) + } + } + return errors +} + +function checkedInteractions(protocol: any): Record { + const errors = validateProtocolInteractions(protocol) + if (errors.length) throw new Error(errors.join('\n')) + return protocol.interactions || {} +} + +function resolveReference(protocol: any, id: string, revision: number, reference: InteractionReference): ResolvedProtocolInteraction { + const selection = reference.versions[revision] + if (!selection) throw new Error(`Interaction ${id}: unknown revision ${revision}`) + const docs = getMessageDocumentation(protocol.messages[reference.messageId])! + const operation = docs.operations.find(item => item.id === selector(reference) && item.method === reference.method) + if (!operation) throw new Error(`Interaction ${id}: source has no normalized operation`) + const variant = selection.messageVersion === undefined ? operation + : operation.variants?.find(item => item.messageVersion === selection.messageVersion) ?? (operation.messageVersion === selection.messageVersion ? operation : undefined) + if (!variant) throw new Error(`Interaction ${id}: source has no normalized messageVersion ${selection.messageVersion}`) + const { variants, ...view } = { ...operation, ...variant } as DocumentationOperation + return { + ...view, + target: selection.target ?? reference.target ?? view.target ?? docs.target, + interactionId: id, + interactionVersion: revision, + messageId: reference.messageId, + operationId: operation.id, + } +} + +/** Resolve one authored revision without treating it as a wire version or choosing an implicit default. */ +export function resolveProtocolInteraction(protocol: any, id: string, revision: number): ResolvedProtocolInteraction { + const interactions = checkedInteractions(protocol) + const reference = Object.prototype.hasOwnProperty.call(interactions, id) ? interactions[id] : undefined + if (!reference) throw new Error(`Unknown interaction ${id}`) + if (!Number.isSafeInteger(revision) || revision < 1) throw new Error(`Interaction ${id}: revision must be a positive safe integer`) + return resolveReference(protocol, id, revision, reference) +} + +/** Keep existing normalized operation identities and anchors for renderers, helpers and links. */ +export function getInteractionDocumentation(protocol: any, messageId: number): (MessageDocumentation & { interactions?: ResolvedProtocolInteraction[] }) | undefined { + const interactions = checkedInteractions(protocol) + const docs = getMessageDocumentation(protocol.messages?.[messageId]) + if (!docs) return undefined + const references = Object.entries(interactions).filter(([, reference]) => reference.messageId === messageId) + if (!references.length) return docs + return { + ...docs, + interactions: references.flatMap(([id, reference]) => Object.keys(reference.versions).map(Number).sort((a, b) => b - a) + .map(revision => resolveReference(protocol, id, revision, reference))), + } +} diff --git a/yaml-data.data.ts b/yaml-data.data.ts index 3f3d0094e..39b039736 100644 --- a/yaml-data.data.ts +++ b/yaml-data.data.ts @@ -1,6 +1,7 @@ import fs from 'node:fs' import jsyaml from 'js-yaml' import { validateMessageDocumentation } from './utils/MessageDocumentation' +import { validateProtocolInteractions } from './utils/ProtocolInteractions' export interface YamlDataInterface { [key: string]: any @@ -17,8 +18,10 @@ export default { const yamlContent = fs.readFileSync(yamlFile, 'utf-8') const parsedYaml = jsyaml.load(yamlContent) as YamlDataInterface - const documentationErrors = Object.keys(parsedYaml.messages || {}).flatMap(id => - validateMessageDocumentation(parsedYaml, Number(id))) + const documentationErrors = [ + ...Object.keys(parsedYaml.messages || {}).flatMap(id => validateMessageDocumentation(parsedYaml, Number(id))), + ...validateProtocolInteractions(parsedYaml), + ] if (documentationErrors.length) throw new Error(documentationErrors.join('\n')) return parsedYaml From 7ff499b1f14ec967000401006ac49b836f607270 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:39:07 +0000 Subject: [PATCH 11/24] Define V3 usage interactions inline with each message --- components/Protocol/StructuredMessagePage.vue | 34 +- devices/api/messages/[messageId].md | 4 +- devices/api/protocol/responses.md | 29 +- public/files/protocol-v3.yaml | 1443 ++++++++--------- utils/MessageDocumentation.test.ts | 227 ++- utils/MessageDocumentation.ts | 128 +- utils/ProtocolInteractions.ts | 116 +- yaml-data.data.ts | 6 +- 8 files changed, 972 insertions(+), 1015 deletions(-) diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index bcd57bc01..6a53d7052 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -2,6 +2,7 @@ import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue' import { useRouter, withBase } from 'vitepress' import Message from './Message.vue' +import ExamplesSection from './ExamplesSection.vue' import DocumentationText from './DocumentationText.vue' import SentinelValues from './SentinelValues.vue' import { @@ -20,11 +21,11 @@ import { documentationExamplesForContext, documentationTargetOverride, getDocumentationFormat, + getMessageDocumentation, getOperationVariant, resolveDocumentationFields, type DocumentationOperation, } from '../../utils/MessageDocumentation' -import { getInteractionDocumentation } from '../../utils/ProtocolInteractions' const props = defineProps<{ messageId: number @@ -32,7 +33,7 @@ const props = defineProps<{ }>() const message = computed(() => props.yamlData.messages?.[props.messageId]) -const documentation = computed(() => getInteractionDocumentation(props.yamlData, props.messageId)) +const documentation = computed(() => getMessageDocumentation(message.value)) const copyStatus = ref('') const router = useRouter() let removeRouteCorrection: (() => void) | undefined @@ -43,7 +44,7 @@ let activeFrame = 0 const exampleColumns = ref([]) const jumpBarHeight = ref(64) let jumpBarObserver: ResizeObserver | undefined -const operationAnchor = (item: DocumentationOperation) => `message-${props.messageId}-operation-${item.id}` +const operationAnchor = (item: DocumentationOperation) => `message-${props.messageId}-operation-${item.anchorId || item.id}` const acknowledgmentUrl = withBase('/devices/api/messages/5-ack#header') const responseReferenceUrl = withBase('/devices/api/protocol/responses') const panels = computed(() => (documentation.value?.operations || []).flatMap(item => { @@ -106,11 +107,6 @@ const panels = computed(() => (documentation.value?.operations || []).flatMap(it }) })) -const interactionLinks = computed(() => (documentation.value?.interactions || []).flatMap(interaction => { - const panel = panels.value.find(item => item.operation.id === interaction.operationId && item.variant.messageVersion === interaction.messageVersion) - return panel ? [{ ...interaction, anchor: panel.anchor }] : [] -})) - function fieldsWithExamples(fields: ReturnType, selectedPanels: typeof panels.value) { const samples = selectedPanels.flatMap(panel => panel.contexts.flatMap(context => context.examples.flatMap(example => capturedDocumentationValues(example, props.messageId, message.value.data, panel.variant.messageVersion).map(sample => ({ @@ -188,6 +184,7 @@ const outlineEntries = computed(() => { entries.push({ id: panel.anchor, title: panel.operation.method || 'Upload', depth }) } } + if (message.value.examples?.length) entries.push({ id: `message-${props.messageId}-wire-examples`, title: 'Wire examples', depth: 0 }) entries.push({ id: `message-${props.messageId}-constants`, title: 'Constants', depth: 0 }) return entries }) @@ -328,15 +325,6 @@ onBeforeUnmount(() => {

{{ documentation.summary }}

Applies to {{ documentation.target }}

-
- Named interactions - -
@@ -373,6 +361,7 @@ onBeforeUnmount(() => { {{ field.type }}

+

Minimum {{ field.minBytes }} bytes

Maximum {{ field.maxBytes }} bytes

  • {{ value.value }} · {{ value.name }}: {{ value.description }}
  • @@ -438,6 +427,7 @@ onBeforeUnmount(() => {

    Value {{ field.value }} · {{ field.valueName }}

    @@ -465,7 +455,7 @@ onBeforeUnmount(() => {

Value {{ field.value }} · {{ field.valueName }}

-

+

  • {{ value.value }} · {{ value.name }}: {{ value.description }} diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index f585c29d3..183734923 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1216,9 +1216,7 @@ messages: 31: name: GSM Control id: gsmControl - description: >- - GET returns GSM state directly. Successful SET operations return an ACK only when the request - includes a nonzero Message ID. + description: Controls the GSM modem, including flight mode and network search. group: gsm header: - 5 @@ -3497,8 +3495,8 @@ messages: description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: - '0': Version 1 (also the omitted/malformed-width fallback) - '1': Version 1 + 0: Version 1 (also the omitted/malformed-width fallback) + 1: Version 1 response: title: Legacy cached payload description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) @@ -3684,8 +3682,8 @@ messages: description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: - '0': Version 1 (also the omitted/malformed-width fallback) - '1': Version 1 + 0: Version 1 (also the omitted/malformed-width fallback) + 1: Version 1 publication: title: Legacy cached payload update description: Version 1 updates use the additive checksum and legacy chunks. Empty payload data diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 7dbc25551..2289a5efd 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -79,6 +79,13 @@ describe('documentation links', () => { expect(parts.filter(part => part.href).map(part => part.href)).toEqual(['https://mcc-mnc.net/', 'https://example.test/code']) expect(documentationTextParts('https://user:secret@example.test/ https://').every(part => !part.href)).toBe(true) }) + + it('links known MT references but leaves code, existing links, and unknown message types alone', () => { + const text = 'MT58 and `MT5` [MT58](./existing) MT999' + const parts = documentationTextParts(text, { '58': { name: 'Message Box' }, '5': { name: 'ACK' } }, path => `/base${path}`) + expect(parts.map(part => part.text).join('')).toBe(text) + expect(parts.filter(part => part.href)).toEqual([{ text: 'MT58', href: '/base/devices/api/messages/58-message-box' }]) + }) }) describe('shared response conventions', () => { diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index 1655da95f..749b47020 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -85,18 +85,38 @@ export function capturedDocumentationValues(example: DocumentationExample, messa }) } -/** Link only explicit HTTP(S) URLs; surrounding prose remains escaped Vue text. */ -export function documentationTextParts(text: string) { +/** Link explicit URLs and known message types; leave code and Markdown links untouched. */ +export function documentationTextParts(text: string, messages?: Record, withBase: (path: string) => string = path => path) { const parts: { text: string; href?: string }[] = [] + const protectedRanges: [number, number][] = [] + for (const match of text.matchAll(/(`+)[\s\S]*?\1|\[[^\]]*\]\([^)]*\)/g)) { + protectedRanges.push([match.index!, match.index! + match[0].length]) + } let end = 0 - for (const match of text.matchAll(/https?:\/\/[^\s<>"']+/gi)) { - let link = match[0].replace(/[.,;:!?]+$/, '') + const tokens = [ + ...Array.from(text.matchAll(/https?:\/\/[^\s<>"']+/gi), match => ({ index: match.index!, value: match[0], kind: 'url' as const })), + ...Array.from(text.matchAll(/\bMT(\d+)\b/g), match => ({ index: match.index!, value: match[0], kind: 'message' as const, id: match[1] })), + ].sort((a, b) => a.index - b.index) + for (const token of tokens) { + const { index, value } = token + const tokenEnd = index + value.length + if (index < end || protectedRanges.some(([start, stop]) => index >= start && tokenEnd <= stop)) continue + if (token.kind === 'message') { + const message = messages?.[token.id] + if (!message?.name) continue + const slug = message.name.toLowerCase().replace(/ /g, '-') + const href = withBase(`/devices/api/messages/${token.id}-${slug}`) + parts.push({ text: text.slice(end, index) }, { text: value, href }) + end = tokenEnd + continue + } + let link = value.replace(/[.,;:!?]+$/, '') while (link.endsWith(')') && (link.match(/\)/g)?.length || 0) > (link.match(/\(/g)?.length || 0)) link = link.slice(0, -1) try { const url = new URL(link) if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) continue - parts.push({ text: text.slice(end, match.index) }, { text: link, href: url.href }) - end = match.index! + link.length + parts.push({ text: text.slice(end, index) }, { text: link, href: url.href }) + end = index + link.length } catch { /* Invalid URLs remain plain text. */ } } parts.push({ text: text.slice(end) }) From c72c191c96966831c5f8f6779e0d8e6042d86a7e Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:39:52 +0000 Subject: [PATCH 14/24] Centralize response correlation guidance --- public/files/protocol-v3.yaml | 69 ++++++++++++----------------------- 1 file changed, 24 insertions(+), 45 deletions(-) diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 183734923..523064e4f 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1348,8 +1348,7 @@ messages: id: simSettings description: >- For devices that have dual-sim functionality, control which SIM is active and set APN parameters - for SIM2. GET returns settings directly. Successful SET operations return an ACK only when the - request includes a nonzero Message ID. + for SIM2. group: gsm header: - 5 @@ -1605,14 +1604,12 @@ messages: description: No payload fields are required. Method must be included; this message does not default to GET. headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 2} response: title: Device status (MT34) description: A successful GET returns Device Status directly, without a separate success ACK. - Returned fields vary by target and available readings. Response To and Status may be omitted - when the request has no nonzero Message ID. + Returned fields vary by target and available readings. headers: 3: {} 4: {value: 0} @@ -1657,8 +1654,7 @@ messages: default subscription documented here. Updates are subject to the selected interval and message level. headers: - 1: - description: Include a nonzero Message ID if you need a setup acknowledgment. + 1: {} 5: {presence: required, value: 3} 6: description: Publication interval in milliseconds. Omitted or 0 allows updates as new status @@ -1679,9 +1675,8 @@ messages: description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. response: messageId: 5 - description: A successful setup returns an MT5 acknowledgment with Status 0 when the request includes - a nonzero Message ID. This acknowledges the request, not delivery of a status update. No acknowledgment - is sent for an omitted or zero Message ID. + description: A successful setup returns an MT5 acknowledgment with Status 0. This acknowledges the + request, not delivery of a status update. headers: 3: {presence: required} 4: {presence: required, value: 0} @@ -1721,13 +1716,11 @@ messages: description: No payload fields are required. Omit Subscription ID; this operation removes the default subscription only. headers: - 1: - description: Include a nonzero Message ID if you need an acknowledgment. + 1: {} 5: {presence: required, value: 5} response: messageId: 5 - description: A successful cancellation returns an MT5 acknowledgment with Status 0 when the request - includes a nonzero Message ID. No acknowledgment is sent for an omitted or zero Message ID. + description: A successful cancellation returns an MT5 acknowledgment with Status 0. headers: 3: {presence: required} 4: {presence: required, value: 0} @@ -1780,8 +1773,7 @@ messages: request: description: No payload fields are required. Include Method GET to request the device identifiers. headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 2} response: title: Device IDs (MT35) @@ -2112,8 +2104,7 @@ messages: 1: request: headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 2} response: title: GPS state (MT39) @@ -2149,8 +2140,7 @@ messages: request: description: Sending the read-only GPS status (field 1) in SET is rejected with Invalid Parameter (4). headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 1} fields: 2: @@ -2163,8 +2153,7 @@ messages: the requested state. response: messageId: 5 - description: For a request with a nonzero Message ID, successful SET returns an ACK, not GPS state. - Use GET to read the current state afterward. + description: Successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. headers: 3: {} 4: {presence: required, value: 0} @@ -3487,8 +3476,7 @@ messages: description: Use the unchanged legacy wire layout and additive checksum. request: headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 2} 22: maxBytes: 1 @@ -3546,8 +3534,7 @@ messages: description: Select the complete extended payload and its CRC-16/XMODEM. request: headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 2} 22: presence: required @@ -3591,8 +3578,7 @@ messages: the outer message-frame CRC protects the SET request itself. Optional supplied checksum fields 1 and 2 are ignored. headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 1} 22: presence: required @@ -3606,9 +3592,8 @@ messages: the field is an error. Extended-length encoding uses a uint16 little-endian length prefix. response: messageId: 5 - description: For a request with a nonzero Message ID, successful SET returns an ACK. It does not - return the cached bytes; subscriber publications are separate asynchronous messages and are - not this reply. + description: Successful SET returns an ACK, not the cached bytes. Subscriber publications are + separate asynchronous messages and are not this reply. headers: 3: {} 4: {presence: required, value: 0} @@ -3636,10 +3621,8 @@ messages: response: messageId: 5 title: Response (MT5 - ACK) - description: For a request with a nonzero Message ID, successful SUBSCRIBE returns a control ACK confirming - the subscription request only. It does not contain the cache. Success ACKs are suppressed for an - omitted or zero Message ID; error ACKs are not suppressed for this reason. Updates arrive as asynchronous - MT58 publications, not as direct replies to SUBSCRIBE. + description: Successful SUBSCRIBE returns a control ACK confirming the subscription request only. It does + not contain the cache. Updates arrive as asynchronous MT58 publications, not as direct replies to SUBSCRIBE. headers: '3': {presence: optional} '4': {presence: required, value: 0} @@ -3664,8 +3647,7 @@ messages: publication format. request: headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 3} 6: description: Optional publication interval in milliseconds. If omitted, updates are sent when @@ -3736,8 +3718,7 @@ messages: description: Explicit version 2 selects the shared extended-payload and CRC publication format. request: headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 3} 6: description: Optional publication interval in milliseconds. If omitted, updates are sent when @@ -3792,16 +3773,14 @@ messages: 1: request: headers: - 1: - description: Include a nonzero Message ID to correlate the reply. + 1: {} 5: {presence: required, value: 5} 17: description: Use the Subscription ID to remove, or omit it for the default subscription (0). response: messageId: 5 - description: For a request with a nonzero Message ID, successful UNSUBSCRIBE returns a control - ACK confirming the unsubscribe request, not a final cached-message publication. Success ACKs - are suppressed for an omitted or zero Message ID; error ACKs are not suppressed for this reason. + description: Successful UNSUBSCRIBE returns a control ACK confirming the unsubscribe request, not a + final cached-message publication. headers: 3: {} 4: {presence: required, value: 0} From ab6fea6a69c9ca4748ce6040ec799c5ab05466d4 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:40:25 +0000 Subject: [PATCH 15/24] Link message references throughout protocol prose --- components/Protocol/StructuredMessagePage.vue | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index 5ed8a8b9d..b3820c027 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -326,13 +326,13 @@ onBeforeUnmount(() => {
-

{{ documentation.summary }}

+

Applies to {{ documentation.target }}

{{ note.title }}

-

{{ note.description }}

+

@@ -399,8 +399,8 @@ onBeforeUnmount(() => { {{ panel.operation.title }} -

{{ panel.operation.description }}

-

{{ panel.variant.description }}

+

+

Target {{ panel.target }}

@@ -411,7 +411,7 @@ onBeforeUnmount(() => { {{ context.title }}

{{ context.subtitle }}

-

{{ context.description }}

+

Correlation, status and acknowledgment rules

{{ group.title }} @@ -451,7 +451,7 @@ onBeforeUnmount(() => {
{{ error.code }} {{ error.name }}
-
{{ error.description }}
+
@@ -473,7 +473,7 @@ onBeforeUnmount(() => { Example {{ example.exampleIndex + 1 }}{{ example.stageTitle }}
{{ example.provenance === 'generated' ? 'Synthetic example' : 'Captured' }} · Details -

{{ example.description }}

+

{{ example.provenance === 'generated' ? 'Synthetic example' : 'Captured' }}

Generated for illustration; not a device capture.

@@ -503,7 +503,7 @@ onBeforeUnmount(() => {
{{ error.code }} {{ error.name }}
-
{{ error.description }}
+
@@ -513,7 +513,7 @@ onBeforeUnmount(() => {

{{ note.title }}

-

{{ note.description }}

+

From 1539bd1eed9e298fe8eaea7810e3a432cf109137 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:40:31 +0000 Subject: [PATCH 16/24] Finish interaction authoring guidance and preserve SDK compatibility --- components/Protocol/StructuredMessagePage.vue | 1 + devices/api/protocol/responses.md | 40 ++++++- public/files/protocol-v3.yaml | 14 +-- utils/MessageDocumentation.test.ts | 104 +++++++++++++++++- utils/MessageDocumentation.ts | 20 +++- 5 files changed, 161 insertions(+), 18 deletions(-) diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index b3820c027..2edd6e690 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -327,6 +327,7 @@ onBeforeUnmount(() => {

+

Methods {{ documentation.methods.join(', ') }}

Applies to {{ documentation.target }}

diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 0df5ce6ff..0f39f0f73 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -14,6 +14,8 @@ Include a nonzero [Message ID (header 1)](./headers#1-message-id) when you need For GPS Control GET and Message Box GET, a successful typed reply includes Response to and Status `0` only when the request has a nonzero Message ID. With an omitted or zero ID, both reply headers are omitted; the typed payload can still be returned. +Device Status GET also returns its typed payload directly; Response to and Status may be omitted when the request has no nonzero Message ID. + Response to can also identify a subscription in some message types. Do not assume every unsolicited update carries it: for example, Message Box publications use their subscription context rather than replying to the SUBSCRIBE request. ## Typed responses and ACKs @@ -31,6 +33,14 @@ An ACK can identify the original request through Response to and/or its **ACK Ty Whether an ACK is sent depends on the operation and target. A missing or zero Message ID does not guarantee silence: typed replies and error replies may still be sent. Follow the message page's documented behavior. +The following operation-specific conditions belong to this shared response reference, linked from each operation's response section: + +- [GSM Control SET](../messages/31-gsm-control#message-31-operation-control-flight-mode) (including network search), [SIM settings SET](../messages/33-sim-settings#message-33-operation-select-sim1) (both SIM choices), and [Device Status SUBSCRIBE/UNSUBSCRIBE](../messages/34-device-status#message-34-operation-subscribe) send a success MT5 ACK only when the request includes a nonzero Message ID. They send no success ACK for an omitted or zero ID. +- For a request with a nonzero Message ID, [GPS Control SET](../messages/39-gps-control#message-39-operation-set) and [Message Box SET](../messages/58-message-box#message-58-operation-set) return a success ACK rather than the message-specific payload. +- [Message Box SUBSCRIBE/UNSUBSCRIBE](../messages/58-message-box#message-58-operation-subscribe) suppress success ACKs for an omitted or zero Message ID; error ACKs are not suppressed for this reason. + +These conditions do not establish a universal rule for every MT5 reply. + ## Status and errors [Status (header 4)](./headers#4-status) belongs to the reply's **header**, not its data fields: @@ -54,7 +64,7 @@ For example, current-format Message Box GET responses and publications carry hea ## Interaction revisions -Usage documentation lives inline at `messages[messageId].interactions`. Each named interaction defines one or more messages through `request`, direct successful `response` (including ACK where applicable), and/or later or unsolicited `publication` stages. These definitions drive the documentation and SDK-facing usage metadata; they are not an index of definitions elsewhere. +Usage documentation lives inline at `messages[messageId].interactions`. Each named interaction defines one or more messages through `request`, direct successful `response` (including ACK where applicable), and/or later or unsolicited `publication` stages. These definitions drive the documentation and interaction helper. Existing SDK consumers still use the retained method maps. Interaction revisions and wire message formats are independent. For example, the first revision of this interaction uses Message Box's existing format 2: @@ -65,24 +75,46 @@ messages: interactions: replace-message-box: method: SET + title: Replace the cached message versions: 1: messageVersion: 2 request: headers: 5: {presence: required, value: 1} - 22: {presence: required, value: 2, maxBytes: 1} + 22: {presence: required, value: 2} fields: 129: {presence: required, maxBytes: 1024} response: messageId: 5 ``` -Stages inherit the containing message type unless they specify `messageId`, so the response above uses the existing MT5 definition. Field names, types, units, enums and descriptions come from that message's `data` and the shared `header` definitions. +`replace-message-box` is the stable lookup key; `title` is the display text and can change without renaming the interaction. The key `1` under `versions` identifies interaction revision 1, not wire format 1. Keep that revision explicit even when it is the only revision. The `messageVersion: 2` reference selects the existing wire format, while header 22 describes its presence and value on the request. An optional `anchorId` preserves an existing documentation fragment independently of the key and title. + +Stages inherit the containing message type unless they specify `messageId`, so the response above uses the existing MT5 definition. Field names, types, units, enums and descriptions come from that message's `data` and the shared `header` definitions. The uint8 type already gives header 22 its one-byte width; variable-size payload bounds such as `maxBytes: 1024` remain meaningful. + +A publication-only interaction uses the same explicit revision shape without inventing a method or request. This shortened example shows the existing tracking upload, not a new wire format: + +```yaml +messages: + 58: + interactions: + tracking-message-box-upload: + title: Tracking-session uploads + versions: + 1: + messageVersion: 2 + publication: + headers: + 22: {presence: required, value: 2} + fields: + 129: + description: Independent Transmit Now upload data. +``` Request mappings list expected inputs, optional by default; mark required inputs explicitly. Leave unrelated inputs out, and keep important ignored or rejected input behavior in concise descriptions. An unlisted input is not a statement that firmware ignores, rejects or accepts it. Response and publication mappings can still mark omitted fields where wire-format or correlation differences matter. Write field descriptions only where the meaning differs. -Existing method-keyed SDK request/response maps remain available without duplicating the interaction documentation. +Documentation method lists are derived from the distinct `method` values on interactions. Existing method-keyed SDK request/response maps remain unchanged, with validation requiring their method names to match the interactions for migrated messages. Multiple interactions may use one method, and publication-only interactions add no method. Removing or regenerating the SDK maps is a separate migration. `messageVersion` references the containing message's existing wire-version definition. It does not itself insert header 22; the stage's headers describe what is sent. Unversioned controls omit it, even if other interactions on that message use versioned payloads. A new interaction revision may reuse the same wire version. Publication-only interactions need no dummy request or method. Applicability can be narrowed with `target` without making fields required. diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 523064e4f..6277564ad 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1269,6 +1269,7 @@ messages: 1: {} 5: {presence: required, value: 2} response: + description: Successful GET returns GSM state directly. headers: 3: {} 4: {value: 0} @@ -1384,7 +1385,6 @@ messages: id: sim2Iccid description: SIM2 ICCID if known, read-only and ignored by SET. This value may be cached from a previous read and stale. type: ascii - readonly: true methods: GET: null SET: null @@ -1400,8 +1400,8 @@ messages: 5: {presence: required, value: 2} response: description: >- - APN and credentials are returned only while SIM2 is active. A cached SIM2 ICCID may - be returned with either active SIM. + Successful GET returns SIM settings directly. APN and credentials are returned only while + SIM2 is active. A cached SIM2 ICCID may be returned with either active SIM. headers: 3: {} 4: {value: 0} @@ -3479,7 +3479,6 @@ messages: 1: {} 5: {presence: required, value: 2} 22: - maxBytes: 1 description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: @@ -3538,7 +3537,6 @@ messages: 5: {presence: required, value: 2} 22: presence: required - maxBytes: 1 value: 2 response: title: Cached payload @@ -3549,7 +3547,6 @@ messages: 4: {value: 0} 22: presence: required - maxBytes: 1 value: 2 fields: 1: @@ -3582,7 +3579,6 @@ messages: 5: {presence: required, value: 1} 22: presence: required - maxBytes: 1 value: 2 fields: 129: @@ -3660,7 +3656,6 @@ messages: description: Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. 22: - maxBytes: 1 description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: @@ -3732,7 +3727,6 @@ messages: unsubscribing. 22: presence: required - maxBytes: 1 value: 2 publication: title: Cached payload update @@ -3746,7 +3740,6 @@ messages: description: Identifies nonzero subscription IDs for this publication. 22: presence: required - maxBytes: 1 value: 2 fields: 1: @@ -3809,7 +3802,6 @@ messages: headers: 22: presence: required - maxBytes: 1 value: 2 fields: 2: diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 2289a5efd..a948478a0 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -11,6 +11,7 @@ import { documentationTextParts, documentationExamplesForContext, getMessageDocumentation, + getDocumentationMethods, getOperationVariant, getDocumentationFormat, documentationTargetOverride, @@ -539,6 +540,105 @@ describe('Device IDs reference', () => { }) describe('canonical inline interactions', () => { + it('derives unique documentation methods from interactions without changing SDK maps', () => { + const before = clone(protocol) + for (const id of [31, 33, 34, 35, 39, 58]) { + const message = protocol.messages[id] + expect(getDocumentationMethods(message).slice().sort()).toEqual(Object.keys(message.methods).sort()) + expect(getMessageDocumentation(message)!.methods).toEqual(getDocumentationMethods(message)) + } + expect(getDocumentationMethods(protocol.messages[31])).toEqual(['GET', 'SET']) + const publication = { interactions: { upload: { versions: { 1: { publication: {} } } } } } + expect(getDocumentationMethods(publication)).toEqual([]) + expect(getDocumentationMethods({ methods: { GET: null, SET: null } })).toEqual(['GET', 'SET']) + const changed = clone(protocol.messages[31]) + changed.methods = { SUBSCRIBE: null } + expect(getDocumentationMethods(changed)).toEqual(['GET', 'SET']) + expect(protocol).toEqual(before) + }) + + it('rejects method drift in either direction while allowing repeated and methodless interactions', () => { + const missing = clone(protocol) + delete missing.messages[31].methods.SET + expect(validateProtocolInteractions(missing).join('\n')).toContain('interaction method SET is missing from the SDK methods map') + const extra = clone(protocol) + extra.messages[33].methods.SUBSCRIBE = null + expect(validateProtocolInteractions(extra).join('\n')).toContain('SDK method SUBSCRIBE has no interaction') + const publication = { ...clone(protocol), messages: { 31: { + description: 'Publication only', data: {}, interactions: { upload: { versions: { 1: { publication: {} } } } }, + } } } + expect(validateProtocolInteractions(publication)).toEqual([]) + expect(validateProtocolInteractions(protocol)).toEqual([]) + }) + + it('keeps interaction keys and public anchors stable when display titles change', () => { + for (const id of [31, 33, 34, 35, 39, 58]) { + const original = getMessageDocumentation(protocol.messages[id])! + const sample = clone(protocol.messages[id]) + for (const interaction of Object.values(sample.interactions) as any[]) interaction.title = 'Revised display title' + const changed = getMessageDocumentation(sample)! + const identities = (docs: typeof original) => docs.operations.map(operation => ({ + id: operation.id, anchorId: operation.anchorId, + revisions: operation.variants?.map(variant => [variant.id, variant.anchorId]), + })) + expect(identities(changed)).toEqual(identities(original)) + expect(changed.operations.every(operation => operation.title === 'Revised display title')).toBe(true) + } + }) + + it('relies on uint8 for Message Version width while retaining variable payload limits and legacy selectors', () => { + expect(protocol.header[22].type).toBe('uint8') + for (const id of [31, 33, 34, 35, 39, 58]) { + const docs = getMessageDocumentation(protocol.messages[id])! + for (const operation of docs.operations) for (const variant of operation.variants || [operation]) { + const view = getOperationVariant(operation, variant.id) + for (const role of ['request', 'response', 'publication'] as const) { + expect(view[role]?.headers?.[22]?.maxBytes).toBeUndefined() + } + } + } + const legacy = resolveProtocolInteraction(protocol, 58, 'read-message-box', 1) + expect(legacy.request?.headers?.[22]?.description).toContain('Omitted, explicitly 0, or malformed-width') + expect(legacy.response?.headers?.[22]?.presence).toBe('omitted') + expect(legacy.response?.fields?.[10]?.maxBytes).toBe(255) + expect(resolveProtocolInteraction(protocol, 58, 'replace-message-box', 1).request?.fields?.[129]?.maxBytes).toBe(1024) + expect(resolveProtocolInteraction(protocol, 33, 'select-sim2', 1).request?.fields?.[2]?.minBytes).toBe(1) + }) + + it('validates both published authoring examples against the existing wire definitions', () => { + const guide = readFileSync(resolve(__dirname, '../devices/api/protocol/responses.md'), 'utf8') + const examples = [...guide.matchAll(/```yaml\n([\s\S]*?)```/g)].map(match => yaml.load(match[1]).messages[58]) + expect(examples).toHaveLength(2) + for (const example of examples) { + const sample = clone(protocol) + const methods = Object.fromEntries(getDocumentationMethods(example).map(method => [method, null])) + sample.messages[58] = { ...sample.messages[58], ...example, methods } + expect(validateMessageDocumentation(sample, 58)).toEqual([]) + for (const source of Object.values(example.interactions) as any[]) { + expect(Object.keys(source.versions)).toEqual(['1']) + expect(source.versions[1].messageVersion).toBe(2) + } + } + }) + + it('keeps ACK schemas local and operation-specific suppression in the linked response reference', () => { + for (const [id, names] of [ + [31, ['control-flight-mode', 'start-search']], + [33, ['select-sim1', 'select-sim2']], + ] as const) for (const name of names) { + const response = resolveProtocolInteraction(protocol, id, name, 1).response! + expect(response.messageId).toBe(5) + expect(response.fields?.[1]?.value).toBe(id) + } + const guide = readFileSync(resolve(__dirname, '../devices/api/protocol/responses.md'), 'utf8') + expect(guide).toContain('GSM Control SET') + expect(guide).toContain('SIM settings SET') + expect(guide).toContain('Device Status SUBSCRIBE/UNSUBSCRIBE') + expect(guide).toContain('send no success ACK for an omitted or zero ID') + expect(guide).toContain('error ACKs are not suppressed for this reason') + expect(guide).toContain('do not establish a universal rule for every MT5 reply') + }) + it('uses inline interactions as the only documentation source without mutating wire definitions', () => { const before = clone(protocol) expect(protocol.interactions).toBeUndefined() @@ -624,7 +724,8 @@ describe('canonical inline interactions', () => { expect(sim1.request?.fields?.[1].value).toBe(0) expect(sim2.request?.fields?.[1].value).toBe(1) expect(sim2.request?.fields?.[2]).toMatchObject({ presence: 'required', minBytes: 1 }) - expect(sim.data[8].readonly).toBe(true) + // Retain the legacy SDK setter API until its separate migration. + expect(sim.data[8].readonly).toBeUndefined() expect(sim1.response?.messageId).toBe(5) }) @@ -664,6 +765,7 @@ describe('canonical inline interactions', () => { it.each([ ['unknown property', (source: any) => { source.context = 'old-alias' }], + ['empty method', (source: any) => { source.method = '' }], ['invalid title', (source: any) => { source.title = 4 }], ['empty revisions', (source: any) => { source.versions = {} }], ['zero revision', (source: any) => { source.versions = { 0: source.versions[1] } }], diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index 749b47020..5051689e0 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -162,6 +162,8 @@ export interface DocumentationFormat { export interface MessageDocumentation { summary: string + /** Derived from interactions for migrated messages, never a second authored list. */ + methods: string[] target?: string /** Message-specific field summaries, referencing message.data definitions. */ fields?: Record @@ -186,6 +188,14 @@ export function hasInlineMessageDocumentation(message: any): boolean { Object.values(message.methods || {}).some((method: any) => method?.exchange !== undefined || method?.versions !== undefined)) } +/** Distinct methods in authoring order; publications need no placeholder method. */ +export function getDocumentationMethods(message: any): string[] { + if (message?.interactions === undefined) return Object.keys(message?.methods || {}) + return [...new Set(Object.values(message.interactions || {}) + .map((interaction: any) => interaction?.method) + .filter((method): method is string => typeof method === 'string' && !!method.trim()))] +} + function wireVersion(exchange: any): number | undefined { for (const role of ['request', 'response', 'publication']) { const header = exchange?.[role]?.headers?.[22] @@ -277,7 +287,7 @@ export function getMessageDocumentation(message: any): MessageDocumentation | un } }) return { - summary: message.description || '', target: message.target, notes: message.notes, + summary: message.description || '', methods: getDocumentationMethods(message), target: message.target, notes: message.notes, fields: formats.length ? undefined : fieldsFor(), formats: formats.length ? formats : undefined, operations, } @@ -389,7 +399,7 @@ function validateInlineDocumentation(message: any, messageId: number, protocol: else for (const [id, source] of Object.entries(message.interactions) as [string, any][]) { if (!object(source)) { errors.push(`${id} interaction must be an object`); continue } knownKeys(source, ['method', 'title', 'description', 'target', 'anchorId', 'versions', 'errors', 'examples', 'request', 'response', 'publication'], id) - text(source, ['title', 'description', 'target', 'anchorId'], id) + text(source, ['method', 'title', 'description', 'target', 'anchorId'], id) if (!object(source.versions) || !Object.keys(source.versions).length) { errors.push(`${id} versions must be a nonempty mapping`); continue } validateExchangeShape(source, id, true) for (const [revision, exchange] of Object.entries(source.versions) as [string, any][]) { @@ -425,6 +435,12 @@ function validateInlineDocumentation(message: any, messageId: number, protocol: if (message.contexts !== undefined || Object.values(message.methods || {}).some((method: any) => method?.exchange !== undefined || method?.versions !== undefined)) { errors.push('interaction documentation must not also be authored in methods or contexts') } + // SDK maps remain unchanged until their consumers migrate. Compare only + // method membership: their request/response maps are not usage contexts. + const methods = getDocumentationMethods(message) + const sdkMethods = Object.keys(message.methods || {}) + for (const method of methods) if (!sdkMethods.includes(method)) errors.push(`interaction method ${method} is missing from the SDK methods map`) + for (const method of sdkMethods) if (!methods.includes(method)) errors.push(`SDK method ${method} has no interaction`) } for (const [name, source] of [...Object.entries(message.methods || {}), ...Object.entries(message.contexts || {})] as [string, any][]) { if (!source) continue From 5745361a382d5c212d989acd32f5b5c5c7fc2a99 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 10:40:39 +0000 Subject: [PATCH 17/24] Flatten interactions and keep documentation metadata out of the protocol --- components/Protocol/StructuredMessagePage.vue | 3 +- devices/api/messages/[messageId].md | 2 +- devices/api/protocol/responses.md | 57 +- public/files/protocol-v3.yaml | 1259 ++++++++--------- utils/MessageDocumentation.test.ts | 278 ++-- utils/MessageDocumentation.ts | 131 +- utils/ProtocolInteractions.ts | 45 - yaml-data.data.ts | 2 +- 8 files changed, 811 insertions(+), 966 deletions(-) delete mode 100644 utils/ProtocolInteractions.ts diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index 2edd6e690..0fd6139a6 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -33,7 +33,7 @@ const props = defineProps<{ }>() const message = computed(() => props.yamlData.messages?.[props.messageId]) -const documentation = computed(() => getMessageDocumentation(message.value)) +const documentation = computed(() => getMessageDocumentation(message.value, props.yamlData)) const copyStatus = ref('') const router = useRouter() let removeRouteCorrection: (() => void) | undefined @@ -386,6 +386,7 @@ onBeforeUnmount(() => {
+
diff --git a/devices/api/messages/[messageId].md b/devices/api/messages/[messageId].md index 709261acc..eb22a2a31 100644 --- a/devices/api/messages/[messageId].md +++ b/devices/api/messages/[messageId].md @@ -15,7 +15,7 @@ const route = useRoute() // Extract numeric ID from "12-close" format const messageId = computed(() => parseInt((route.data.params?.messageId || '').split('-')[0])) const messageData = computed(() => protocolData?.messages?.[messageId.value]) -const structuredDocumentation = computed(() => getMessageDocumentation(messageData.value)) +const structuredDocumentation = computed(() => getMessageDocumentation(messageData.value, protocolData)) // The legacy composable takes a numeric ID; re-create its view when the route changes. const sections = computed(() => useMessageSections(messageId.value, protocolData)) diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 0f39f0f73..551adddc3 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -62,11 +62,11 @@ A request may select a format, and a response or publication may identify the fo For example, current-format Message Box GET responses and publications carry header 22 with value `2`, but its MT5 control ACKs and terminal subscription status messages do not. Legacy Message Box responses omit it. [Message Box's format sections](../messages/58-message-box#message-58-format-current) describe those differences; the dates used as documentation format names do not replace numeric values on the wire. -## Interaction revisions + -Usage documentation lives inline at `messages[messageId].interactions`. Each named interaction defines one or more messages through `request`, direct successful `response` (including ACK where applicable), and/or later or unsolicited `publication` stages. These definitions drive the documentation and interaction helper. Existing SDK consumers still use the retained method maps. +## Authoring interactions -Interaction revisions and wire message formats are independent. For example, the first revision of this interaction uses Message Box's existing format 2: +Usage definitions live inline at `messages[messageId].interactions`. Each stable key describes an exchange through `request`, direct successful `response` (including ACK where applicable), and/or later or unsolicited `publication` stages. Existing SDK consumers still use the retained method maps. ```yaml messages: @@ -74,26 +74,25 @@ messages: # Existing data fields and wire-version definitions remain here. interactions: replace-message-box: - method: SET title: Replace the cached message - versions: - 1: - messageVersion: 2 - request: - headers: - 5: {presence: required, value: 1} - 22: {presence: required, value: 2} - fields: - 129: {presence: required, maxBytes: 1024} - response: - messageId: 5 + messageVersion: 2 + request: + headers: + 5: {presence: required, value: 1} + 22: {presence: required, value: 2} + fields: + 129: {presence: required, maxBytes: 1024} + response: + messageId: 5 ``` -`replace-message-box` is the stable lookup key; `title` is the display text and can change without renaming the interaction. The key `1` under `versions` identifies interaction revision 1, not wire format 1. Keep that revision explicit even when it is the only revision. The `messageVersion: 2` reference selects the existing wire format, while header 22 describes its presence and value on the request. An optional `anchorId` preserves an existing documentation fragment independently of the key and title. +`replace-message-box` is the stable key; its title can change without renaming the interaction. The request's Method header value `1` means SET, using the shared header enum. There is no second authored method label or interaction-revision layer. Documentation links and layout are maintained by the site code, not the protocol YAML. -Stages inherit the containing message type unless they specify `messageId`, so the response above uses the existing MT5 definition. Field names, types, units, enums and descriptions come from that message's `data` and the shared `header` definitions. The uint8 type already gives header 22 its one-byte width; variable-size payload bounds such as `maxBytes: 1024` remain meaningful. +`messageVersion: 2` references the containing message's existing wire format. It does not insert header 22; each stage's headers describe what is sent. Unversioned controls omit `messageVersion`, even if other interactions on the same message use versioned payloads. Message Box's current `read-message-box` and legacy `read-message-box-v1` are separate interactions, as are `subscribe-message-box` and `subscribe-message-box-v1`. Keep their keys stable; do not silently change an existing key to refer to a different wire format. -A publication-only interaction uses the same explicit revision shape without inventing a method or request. This shortened example shows the existing tracking upload, not a new wire format: +Stages inherit the containing message type unless they specify `messageId`, so the response above uses MT5. Field names, types, units, enums and descriptions come from that message's `data` and the shared `header` definitions. The uint8 type already gives header 22 its one-byte width; variable-size payload bounds such as `maxBytes: 1024` remain meaningful. Keep explicit selector behavior: legacy Message Box GET/SUBSCRIBE accepts omitted, zero or malformed-width selectors as version 1, and legacy responses omit header 22. + +A publication-only interaction needs no method or request. This shortened example describes the existing tracking upload: ```yaml messages: @@ -101,24 +100,20 @@ messages: interactions: tracking-message-box-upload: title: Tracking-session uploads - versions: - 1: - messageVersion: 2 - publication: - headers: - 22: {presence: required, value: 2} - fields: - 129: - description: Independent Transmit Now upload data. + messageVersion: 2 + publication: + headers: + 22: {presence: required, value: 2} + fields: + 129: + description: Independent Transmit Now upload data. ``` Request mappings list expected inputs, optional by default; mark required inputs explicitly. Leave unrelated inputs out, and keep important ignored or rejected input behavior in concise descriptions. An unlisted input is not a statement that firmware ignores, rejects or accepts it. Response and publication mappings can still mark omitted fields where wire-format or correlation differences matter. Write field descriptions only where the meaning differs. -Documentation method lists are derived from the distinct `method` values on interactions. Existing method-keyed SDK request/response maps remain unchanged, with validation requiring their method names to match the interactions for migrated messages. Multiple interactions may use one method, and publication-only interactions add no method. Removing or regenerating the SDK maps is a separate migration. - -`messageVersion` references the containing message's existing wire-version definition. It does not itself insert header 22; the stage's headers describe what is sent. Unversioned controls omit it, even if other interactions on that message use versioned payloads. A new interaction revision may reuse the same wire version. Publication-only interactions need no dummy request or method. Applicability can be narrowed with `target` without making fields required. +Documentation method lists are derived from request header 5, with validation requiring a known selector for each request. An absent selector is not inferred as GET. Existing method-keyed SDK request/response maps remain unchanged, with validation requiring their method names to match the interactions for migrated messages. Multiple interactions may use one method, and publication-only interactions add none. Removing or regenerating the SDK maps is a separate migration. -An interaction describes an exchange, not arbitrary ordered sequences of requests. Its stages remain subject to the correlation, suppression and target rules above; defining a response does not guarantee it is sent. +An interaction describes an exchange, not arbitrary ordered sequences of requests. Applicability can be narrowed with `target` without making fields required. Its stages remain subject to the correlation, suppression and target rules above; defining a response does not guarantee it is sent. ## Subscription replies and later updates diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 6277564ad..313a149f1 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -1260,70 +1260,60 @@ messages: SET: null interactions: read-state: - method: GET title: Read GSM state - versions: - 1: - request: - headers: - 1: {} - 5: {presence: required, value: 2} - response: - description: Successful GET returns GSM state directly. - headers: - 3: {} - 4: {value: 0} - fields: - 1: {presence: required} - 2: - description: Remaining external modem reservation time in minutes, returned with field 4. - 3: {presence: required} - 4: - description: Present with value true when the modem is reserved for external use. + request: + headers: + 1: {} + 5: { presence: required, value: 2 } + response: + description: Successful GET returns GSM state directly. + headers: + 3: {} + 4: { value: 0 } + fields: + 1: { presence: required } + 2: + description: Remaining external modem reservation time in minutes, returned with field 4. + 3: { presence: required } + 4: + description: Present with value true when the modem is reserved for external use. control-flight-mode: - method: SET title: Control flight mode - versions: - 1: - request: + request: + description: >- + Omit Start Search (field 5), which takes priority over flight-mode controls when present. GSM + Active and Request Control (fields 3 and 4) are ignored by SET. + headers: + 1: {} + 5: { presence: required, value: 1 } + 7: {} + fields: + 1: + description: Enable or disable flight mode. Omission disables it. + 2: description: >- - Omit Start Search (field 5), which takes priority over flight-mode controls when present. - GSM Active and Request Control (fields 3 and 4) are ignored by SET. - headers: - 1: {} - 5: {presence: required, value: 1} - 7: {} - fields: - 1: - description: Enable or disable flight mode. Omission disables it. - 2: - description: >- - When enabling flight mode, provide 1 to 259200 minutes. If omitted, use header - Duration in milliseconds divided by 60000 and rounded down. Disabling flight mode - ignores the duration. - response: &gsmControlAck - messageId: 5 - headers: - 3: {presence: required} - 4: {presence: required, value: 0} - fields: - 1: {presence: required, value: 31} + When enabling flight mode, provide 1 to 259200 minutes. If omitted, use header Duration in + milliseconds divided by 60000 and rounded down. Disabling flight mode ignores the duration. + response: &gsmControlAck + messageId: 5 + headers: + 3: { presence: required } + 4: { presence: required, value: 0 } + fields: + 1: { presence: required, value: 31 } start-search: - method: SET title: Start a network search description: Leave flight mode and trigger the selected network search. - versions: - 1: - request: - description: >- - Start Search takes priority even when its value is 0. Fields 1 to 4 and header Duration - (7) are ignored when Start Search is present. - headers: - 1: {} - 5: {presence: required, value: 1} - fields: - 5: {presence: required} - response: *gsmControlAck + request: + description: >- + Start Search takes priority even when its value is 0. Fields 1 to 4 and header Duration (7) are + ignored when Start Search is present. + headers: + 1: {} + 5: { presence: required, value: 1 } + fields: + 5: { presence: required } + response: *gsmControlAck 32: name: GSM Ownership id: gsmOwnership @@ -1390,65 +1380,56 @@ messages: SET: null interactions: read-settings: - method: GET title: Read SIM settings - versions: - 1: - request: - headers: - 1: {} - 5: {presence: required, value: 2} - response: - description: >- - Successful GET returns SIM settings directly. APN and credentials are returned only while - SIM2 is active. A cached SIM2 ICCID may be returned with either active SIM. - headers: - 3: {} - 4: {value: 0} - fields: - 1: - presence: required - description: Currently active SIM. - 2: {} - 3: {} - 4: {} - 8: {} + request: + headers: + 1: {} + 5: { presence: required, value: 2 } + response: + description: >- + Successful GET returns SIM settings directly. APN and credentials are returned only while SIM2 is + active. A cached SIM2 ICCID may be returned with either active SIM. + headers: + 3: {} + 4: { value: 0 } + fields: + 1: + presence: required + description: Currently active SIM. + 2: {} + 3: {} + 4: {} + 8: {} select-sim1: - method: SET title: Select SIM1 - versions: - 1: - request: - description: SIM2 APN and credentials are ignored when selecting SIM1. - headers: - 1: {} - 5: {presence: required, value: 1} - fields: - 1: {presence: required, value: 0} - response: &simSettingsAck - messageId: 5 - headers: - 3: {presence: required} - 4: {presence: required, value: 0} - fields: - 1: {presence: required, value: 33} + request: + description: SIM2 APN and credentials are ignored when selecting SIM1. + headers: + 1: {} + 5: { presence: required, value: 1 } + fields: + 1: { presence: required, value: 0 } + response: &simSettingsAck + messageId: 5 + headers: + 3: { presence: required } + 4: { presence: required, value: 0 } + fields: + 1: { presence: required, value: 33 } select-sim2: - method: SET title: Select SIM2 and configure its network credentials - versions: - 1: - request: - headers: - 1: {} - 5: {presence: required, value: 1} - fields: - 1: {presence: required, value: 1} - 2: {presence: required, minBytes: 1} - 3: - description: Omission clears the configured SIM2 username. - 4: - description: Omission clears the configured SIM2 password. - response: *simSettingsAck + request: + headers: + 1: {} + 5: { presence: required, value: 1 } + fields: + 1: { presence: required, value: 1 } + 2: { presence: required, minBytes: 1 } + 3: + description: Omission clears the configured SIM2 username. + 4: + description: Omission clears the configured SIM2 password. + response: *simSettingsAck examples: - name: Enable SIM2 with APN settings bytes: 3 42 0 33 0 2 0 1 5 4 22 0 0 0 1 1 2 0 1 2 4 1 0 0 0 14 115 111 109 101 46 97 112 110 46 112 108 97 99 101 85 240 @@ -1594,136 +1575,122 @@ messages: UNSUBSCRIBE: null interactions: read-device-status: - method: GET - anchorId: get title: Read device status description: Request the currently available status fields. - versions: - 1: - request: - description: No payload fields are required. Method must be included; this message does not default - to GET. - headers: - 1: {} - 5: {presence: required, value: 2} - response: - title: Device status (MT34) - description: A successful GET returns Device Status directly, without a separate success ACK. - Returned fields vary by target and available readings. - headers: - 3: {} - 4: {value: 0} - fields: - 1: {} - 2: {} - 3: {} - 4: {} - 5: {} - 6: {} - 7: {} - 10: {} - 12: {} - 13: {} - 14: {} - examples: - - title: GET exchange - provenance: captured - target: RH2 over I2C - description: Captured on 2025-10-10 during normal device communications. The request and response - share Message ID / Response To 1048863264; the response reports firmware 2287. These are the - original captured bytes. - frames: + request: + description: No payload fields are required. Method must be included; this message does not default to GET. + headers: + 1: {} + 5: { presence: required, value: 2 } + response: + title: Device status (MT34) + description: A successful GET returns Device Status directly, without a separate success ACK. Returned + fields vary by target and available readings. + headers: + 3: {} + 4: { value: 0 } + fields: + 1: {} + 2: {} + 3: {} + 4: {} + 5: {} + 6: {} + 7: {} + 10: {} + 12: {} + 13: {} + 14: {} + examples: + - title: GET exchange + provenance: captured + target: RH2 over I2C + description: Captured on 2025-10-10 during normal device communications. The request and response share + Message ID / Response To 1048863264; the response reports firmware 2287. These are the original + captured bytes. + frames: - role: request label: GET request for device status bytes: 3 20 0 34 0 2 0 5 1 1 2 4 32 98 132 62 0 0 194 229 - role: response label: Device status response - bytes: 3 49 0 34 0 2 0 3 4 4 32 98 132 62 1 0 8 0 1 3 7 10 2 4 5 6 1 88 1 0 4 239 8 0 0 1 48 - 1 64 1 0 2 0 0 2 0 0 108 94 + bytes: 3 49 0 34 0 2 0 3 4 4 32 98 132 62 1 0 8 0 1 3 7 10 2 4 5 6 1 88 1 0 4 239 8 0 0 1 48 1 64 1 0 2 + 0 0 2 0 0 108 94 subscribe-device-status: - method: SUBSCRIBE - anchorId: subscribe title: Subscribe to status updates description: Create or update the default Device Status subscription. Setup acknowledgment and later status publications are separate; subscribing does not itself request an immediate status snapshot. Use GET when you need the current status. - versions: - 1: - request: - description: No payload fields are required. Omit Subscription ID (header 17), or use 0, for the - default subscription documented here. Updates are subject to the selected interval and message - level. - headers: - 1: {} - 5: {presence: required, value: 3} - 6: - description: Publication interval in milliseconds. Omitted or 0 allows updates as new status - data becomes available. - 7: - description: Subscription duration in milliseconds. Omitted or 0 keeps the subscription active - until unsubscribed. - 8: - description: Time in milliseconds to wait for the first matching status update. Omitted or - 0 does not set a timeout. - 15: - description: Storage/retry policy for publications. Defaults to None (0). - 16: - description: Minimum publication level. The default Info-Auto (2) receives normal status updates; - no explicit level is required. - 17: - value: 0 - description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. - response: - messageId: 5 - description: A successful setup returns an MT5 acknowledgment with Status 0. This acknowledges the - request, not delivery of a status update. - headers: - 3: {presence: required} - 4: {presence: required, value: 0} - publication: - title: Status update (MT34) - description: Later status updates produce Device Status messages, filtered by the subscription - interval and level. They are not replies to the original SUBSCRIBE request and do not carry - its Response To. Available payload fields vary by target and readings. - headers: - 3: - presence: omitted - description: A later publication is not correlated to the subscription request. - 4: - presence: omitted - description: Status updates carry status data, not a command-result envelope. - fields: - 1: {} - 2: {} - 3: {} - 4: {} - 5: {} - 6: {} - 7: {} - 10: {} - 12: {} - 13: {} - 14: {} + request: + description: No payload fields are required. Omit Subscription ID (header 17), or use 0, for the default + subscription documented here. Updates are subject to the selected interval and message level. + headers: + 1: {} + 5: { presence: required, value: 3 } + 6: + description: Publication interval in milliseconds. Omitted or 0 allows updates as new status data + becomes available. + 7: + description: Subscription duration in milliseconds. Omitted or 0 keeps the subscription active until + unsubscribed. + 8: + description: Time in milliseconds to wait for the first matching status update. Omitted or 0 does not + set a timeout. + 15: + description: Storage/retry policy for publications. Defaults to None (0). + 16: + description: Minimum publication level. The default Info-Auto (2) receives normal status updates; no + explicit level is required. + 17: + value: 0 + description: Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it. + response: + messageId: 5 + description: A successful setup returns an MT5 acknowledgment with Status 0. This acknowledges the + request, not delivery of a status update. + headers: + 3: { presence: required } + 4: { presence: required, value: 0 } + publication: + title: Status update (MT34) + description: Later status updates produce Device Status messages, filtered by the subscription interval + and level. They are not replies to the original SUBSCRIBE request and do not carry its Response + To. Available payload fields vary by target and readings. + headers: + 3: + presence: omitted + description: A later publication is not correlated to the subscription request. + 4: + presence: omitted + description: Status updates carry status data, not a command-result envelope. + fields: + 1: {} + 2: {} + 3: {} + 4: {} + 5: {} + 6: {} + 7: {} + 10: {} + 12: {} + 13: {} + 14: {} stop-device-status-subscription: - method: UNSUBSCRIBE - anchorId: unsubscribe title: Stop the default status subscription description: Stop the default Device Status subscription (ID 0). This operation does not select a named subscription; supplying another Subscription ID does not cancel that named subscription. - versions: - 1: - request: - description: No payload fields are required. Omit Subscription ID; this operation removes the - default subscription only. - headers: - 1: {} - 5: {presence: required, value: 5} - response: - messageId: 5 - description: A successful cancellation returns an MT5 acknowledgment with Status 0. - headers: - 3: {presence: required} - 4: {presence: required, value: 0} + request: + description: No payload fields are required. Omit Subscription ID; this operation removes the default + subscription only. + headers: + 1: {} + 5: { presence: required, value: 5 } + response: + messageId: 5 + description: A successful cancellation returns an MT5 acknowledgment with Status 0. + headers: + 3: { presence: required } + 4: { presence: required, value: 0 } 35: name: Device IDs id: deviceIds @@ -1764,46 +1731,41 @@ messages: GET: null interactions: read-device-ids: - method: GET - anchorId: get title: Read device IDs description: Request the available device and SIM identifiers. - versions: - 1: - request: - description: No payload fields are required. Include Method GET to request the device identifiers. - headers: - 1: {} - 5: {presence: required, value: 2} - response: - title: Device IDs (MT35) - description: The GET response contains the available device identifiers. Not all fields are available - on every device type. Cached SIM2 ICCID is a previously read value and may be stale. - headers: - 3: {} - 4: {value: 0} - fields: - 1: {} - 2: {} - 3: {} - 4: {} - 8: {} - examples: - - title: GET exchange - provenance: captured - target: RH2 over I2C - description: Captured on 2025-10-10 during normal communications over I2C with the ESP32 co-processor. - Toit on the ESP32 sends the request; RH2 P1 v2287 responds. These are the original captured - bytes. - frames: + request: + description: No payload fields are required. Include Method GET to request the device identifiers. + headers: + 1: {} + 5: { presence: required, value: 2 } + response: + title: Device IDs (MT35) + description: The GET response contains the available device identifiers. Not all fields are available on + every device type. Cached SIM2 ICCID is a previously read value and may be stale. + headers: + 3: {} + 4: { value: 0 } + fields: + 1: {} + 2: {} + 3: {} + 4: {} + 8: {} + examples: + - title: GET exchange + provenance: captured + target: RH2 over I2C + description: Captured on 2025-10-10 during normal communications over I2C with the ESP32 co-processor. + Toit on the ESP32 sends the request; RH2 P1 v2287 responds. These are the original captured + bytes. + frames: - role: request label: GET request for device ids bytes: 3 20 0 35 0 2 0 5 1 1 2 4 31 187 53 226 0 0 191 169 - role: response label: Device IDs response - bytes: 3 65 0 35 0 2 0 3 4 4 31 187 53 226 1 0 3 0 1 2 3 4 3 109 161 0 15 56 54 52 57 53 48 - 48 54 48 50 49 50 53 56 55 20 56 57 52 53 55 51 48 48 48 48 48 48 50 50 50 49 52 56 48 54 - 6 251 + bytes: 3 65 0 35 0 2 0 3 4 4 31 187 53 226 1 0 3 0 1 2 3 4 3 109 161 0 15 56 54 52 57 53 48 48 54 48 50 + 49 50 53 56 55 20 56 57 52 53 55 51 48 48 48 48 48 48 50 50 50 49 52 56 48 54 6 251 36: name: Device Time id: deviceTime @@ -2093,76 +2055,69 @@ messages: response: null interactions: read-gps-state: - method: GET - anchorId: get title: Read GPS state - description: Return the current GPS and correction-service state, not a position fix. No payload fields are needed. + description: Return the current GPS and correction-service state, not a position fix. No payload fields + are needed. errors: - - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' - versions: - 1: - request: - headers: - 1: {} - 5: {presence: required, value: 2} - response: - title: GPS state (MT39) - description: A successful GET returns GPS Control directly, with no separate success ACK. An unsuccessful - request returns MT5 (ACK) with Status, not this payload. - headers: - 3: {} - 4: {value: 0} - fields: - 1: - presence: required - description: Whether the GPS service is on. - 2: - presence: required - description: Whether correction data is enabled. - 3: - presence: omitted - description: Start mode is a SET input, not returned state. + - code: 7 + description: 'Not Supported: the product or firmware does not support this operation.' + request: + headers: + 1: {} + 5: { presence: required, value: 2 } + response: + title: GPS state (MT39) + description: A successful GET returns GPS Control directly, with no separate success ACK. An + unsuccessful request returns MT5 (ACK) with Status, not this payload. + headers: + 3: {} + 4: { value: 0 } + fields: + 1: + presence: required + description: Whether the GPS service is on. + 2: + presence: required + description: Whether correction data is enabled. + 3: + presence: omitted + description: Start mode is a SET input, not returned state. configure-gps: - method: SET - anchorId: set title: Configure corrections and start mode description: Enable correction data and/or restart the GPS in the requested boot mode. errors: - - code: 4 - description: 'Invalid Parameter: a read-only GPS status field or an unsupported start mode was supplied.' - - code: 5 - description: 'Invalid State: the correction service cannot be enabled in the current device state.' - - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' - versions: - 1: - request: - description: Sending the read-only GPS status (field 1) in SET is rejected with Invalid Parameter (4). - headers: - 1: {} - 5: {presence: required, value: 1} - fields: - 2: - description: Request and apply correction data to the GPS, such as RTK; this automatically - controls the GPS module. Omitting this field sets API-enabled corrections to disabled, so - a start-mode-only SET does not preserve the previous correction setting. Include 1 to keep - API-enabled corrections on. - 3: - description: If GPS is enabled, reboot it in this mode. If it is disabled, enable it with - the requested state. - response: - messageId: 5 - description: Successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. - headers: - 3: {} - 4: {presence: required, value: 0} - fields: - 1: - presence: required - value: 39 - description: ACK Type identifies the original message type (39). No message-specific state - is returned in this ACK. + - code: 4 + description: 'Invalid Parameter: a read-only GPS status field or an unsupported start mode was supplied.' + - code: 5 + description: 'Invalid State: the correction service cannot be enabled in the current device state.' + - code: 7 + description: 'Not Supported: the product or firmware does not support this operation.' + request: + description: Sending the read-only GPS status (field 1) in SET is rejected with Invalid Parameter (4). + headers: + 1: {} + 5: { presence: required, value: 1 } + fields: + 2: + description: Request and apply correction data to the GPS, such as RTK; this automatically controls the + GPS module. Omitting this field sets API-enabled corrections to disabled, so a start-mode-only + SET does not preserve the previous correction setting. Include 1 to keep API-enabled + corrections on. + 3: + description: If GPS is enabled, reboot it in this mode. If it is disabled, enable it with the requested + state. + response: + messageId: 5 + description: Successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. + headers: + 3: {} + 4: { presence: required, value: 0 } + fields: + 1: + presence: required + value: 39 + description: ACK Type identifies the original message type (39). No message-specific state is returned + in this ACK. 40: name: Haptics Control id: hapticsControl @@ -3458,369 +3413,357 @@ messages: UNSUBSCRIBE: null interactions: read-message-box: - method: GET - anchorId: get title: Read the cached message - description: GET chooses its own response format, regardless of the selected subscription format. A - successful GET returns MT58 directly, rather than a separate success ACK. - errors: - - code: 4 - description: 'Invalid Parameter: a decoded Message Version value above 2.' - - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' - versions: - 1: - anchorId: v1 - messageVersion: 1 - title: 2025-10 · legacy chunks - description: Use the unchanged legacy wire layout and additive checksum. - request: - headers: - 1: {} - 5: {presence: required, value: 2} - 22: - description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version - 1; an explicit 1 also selects version 1. - values: - 0: Version 1 (also the omitted/malformed-width fallback) - 1: Version 1 - response: - title: Legacy cached payload - description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) - with Status instead. - headers: - 3: {} - 4: {value: 0} - 22: - presence: omitted - description: Legacy version 1 responses retain their original wire layout and omit Message - Version. - fields: - 1: - presence: required - description: 'Additive checksum: sum of all cached payload bytes modulo 65536.' - 2: - presence: omitted - description: The CRC field belongs to version 2. - 10: - maxBytes: 255 - description: Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 11: - maxBytes: 255 - description: Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 12: - maxBytes: 255 - description: Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 13: - maxBytes: 255 - description: Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 14: - maxBytes: 255 - description: Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 129: - presence: omitted - description: Version 1 retains the legacy wire layout; it does not include the extended full-payload - field. - 2: - anchorId: v2 - messageVersion: 2 - title: 2026-10 · complete payload - description: Select the complete extended payload and its CRC-16/XMODEM. - request: - headers: - 1: {} - 5: {presence: required, value: 2} - 22: - presence: required - value: 2 - response: - title: Cached payload - description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) - with Status instead. - headers: - 3: {} - 4: {value: 0} - 22: - presence: required - value: 2 - fields: - 1: - presence: omitted - description: The legacy additive checksum is absent from version 2 responses. - 2: - presence: required - description: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty - cache. One- or two-byte little-endian encoding may omit a high zero byte. - 129: - maxBytes: 1024 - description: Complete cached payload in an extended-length field with a uint16 little-endian - length prefix. Empty payload data is omitted. + description: >- + GET chooses its own response format, regardless of the selected subscription format. A successful + GET returns MT58 directly, rather than a separate success ACK. + + + Select the complete extended payload and its CRC-16/XMODEM. + errors: &messageBoxReadErrors + - code: 4 + description: 'Invalid Parameter: a decoded Message Version value above 2.' + - code: 7 + description: 'Not Supported: the product or firmware does not support this operation.' + messageVersion: 2 + request: + headers: + 1: {} + 5: { presence: required, value: 2 } + 22: + presence: required + value: 2 + response: + title: Cached payload + description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with + Status instead. + headers: + 3: {} + 4: { value: 0 } + 22: + presence: required + value: 2 + fields: + 1: + presence: omitted + description: The legacy additive checksum is absent from version 2 responses. + 2: + presence: required + description: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- + or two-byte little-endian encoding may omit a high zero byte. + 129: + maxBytes: 1024 + description: Complete cached payload in an extended-length field with a uint16 little-endian length + prefix. Empty payload data is omitted. + read-message-box-v1: + title: Read the cached message (legacy v1) + description: >- + GET chooses its own response format, regardless of the selected subscription format. A successful + GET returns MT58 directly, rather than a separate success ACK. + + + Use the unchanged legacy wire layout and additive checksum. + errors: *messageBoxReadErrors + messageVersion: 1 + request: + headers: + 1: {} + 5: { presence: required, value: 2 } + 22: + description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an + explicit 1 also selects version 1. + values: + 0: Version 1 (also the omitted/malformed-width fallback) + 1: Version 1 + response: + title: Legacy cached payload + description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with + Status instead. + headers: + 3: {} + 4: { value: 0 } + 22: + presence: omitted + description: Legacy version 1 responses retain their original wire layout and omit Message Version. + fields: + 1: + presence: required + description: 'Additive checksum: sum of all cached payload bytes modulo 65536.' + 2: + presence: omitted + description: The CRC field belongs to version 2. + 10: + maxBytes: 255 + description: Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 11: + maxBytes: 255 + description: Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 12: + maxBytes: 255 + description: Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 13: + maxBytes: 255 + description: Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 14: + maxBytes: 255 + description: Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 129: + presence: omitted + description: Version 1 retains the legacy wire layout; it does not include the extended full-payload field. replace-message-box: - method: SET - anchorId: set title: Replace or clear the cached message description: Every accepted SET updates the cache, writes it to persistent storage when enabled, and - publishes to current subscribers, even for identical bytes. SET does not change the selected subscription - format. - versions: - 1: - messageVersion: 2 - request: - description: Message Version 2 and field 129 are required. The device calculates the payload CRC; - the outer message-frame CRC protects the SET request itself. Optional supplied checksum fields - 1 and 2 are ignored. - headers: - 1: {} - 5: {presence: required, value: 1} - 22: - presence: required - value: 2 - fields: - 129: - presence: required - maxBytes: 1024 - description: Complete new cache bytes. An explicit zero-length field clears the cache; omitting - the field is an error. Extended-length encoding uses a uint16 little-endian length prefix. - response: - messageId: 5 - description: Successful SET returns an ACK, not the cached bytes. Subscriber publications are - separate asynchronous messages and are not this reply. - headers: - 3: {} - 4: {presence: required, value: 0} - fields: - 1: - presence: required - value: 58 - description: ACK Type identifies the original message type (58). No message-specific state - is returned in this ACK. - errors: - - code: 2 - description: 'Missing Parameter: field 129 is absent.' - - code: 4 - description: 'Invalid Parameter: Message Version is missing, malformed-width, or any value other - than 2; or field 129 exceeds 1024 bytes.' - - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' + publishes to current subscribers, even for identical bytes. SET does not change the selected + subscription format. + messageVersion: 2 + request: + description: Message Version 2 and field 129 are required. The device calculates the payload CRC; the + outer message-frame CRC protects the SET request itself. Optional supplied checksum fields 1 and 2 + are ignored. + headers: + 1: {} + 5: { presence: required, value: 1 } + 22: + presence: required + value: 2 + fields: + 129: + presence: required + maxBytes: 1024 + description: Complete new cache bytes. An explicit zero-length field clears the cache; omitting the + field is an error. Extended-length encoding uses a uint16 little-endian length prefix. + response: + messageId: 5 + description: Successful SET returns an ACK, not the cached bytes. Subscriber publications are separate + asynchronous messages and are not this reply. + headers: + 3: {} + 4: { presence: required, value: 0 } + fields: + 1: + presence: required + value: 58 + description: ACK Type identifies the original message type (58). No message-specific state is returned + in this ACK. + errors: + - code: 2 + description: 'Missing Parameter: field 129 is absent.' + - code: 4 + description: 'Invalid Parameter: Message Version is missing, malformed-width, or any value other than 2; + or field 129 exceeds 1024 bytes.' + - code: 7 + description: 'Not Supported: the product or firmware does not support this operation.' subscribe-message-box: - method: SUBSCRIBE - anchorId: subscribe title: Subscribe to cached-message updates - description: The latest valid SUBSCRIBE selects one shared format for all Message Box publications, - not a format per subscriber. A decoded version above 2 leaves both the existing format selection and - subscription unchanged. Control acknowledgment and later publications are distinct messages. - response: + description: >- + The latest valid SUBSCRIBE selects one shared format for all Message Box publications, not a format + per subscriber. A decoded version above 2 leaves both the existing format selection and subscription + unchanged. Control acknowledgment and later publications are distinct messages. + + + Explicit version 2 selects the shared extended-payload and CRC publication format. + response: &messageBoxSubscribeAck messageId: 5 title: Response (MT5 - ACK) - description: Successful SUBSCRIBE returns a control ACK confirming the subscription request only. It does - not contain the cache. Updates arrive as asynchronous MT58 publications, not as direct replies to SUBSCRIBE. + description: Successful SUBSCRIBE returns a control ACK confirming the subscription request only. It + does not contain the cache. Updates arrive as asynchronous MT58 publications, not as direct + replies to SUBSCRIBE. headers: - '3': {presence: optional} - '4': {presence: required, value: 0} + '3': { presence: optional } + '4': { presence: required, value: 0 } fields: '1': presence: required value: 58 - description: ACK Type identifies the original message type (58). No message-specific state is - returned in this ACK. - errors: - - code: 4 - description: 'Invalid Parameter: a decoded Message Version value above 2; existing selection and subscription - are unchanged.' - - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' - versions: - 1: - anchorId: v1 - messageVersion: 1 - title: Version 1 · legacy publications - description: Omitted, explicitly 0, malformed-width, or explicit version 1 selects the shared legacy - publication format. - request: - headers: - 1: {} - 5: {presence: required, value: 3} - 6: - description: Optional publication interval in milliseconds. If omitted, updates are sent when - new data is available. - 7: - description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. - 16: - description: Minimum publication level. - 17: - description: Subscription ID; omit for the default subscription (0). Use the same ID when - unsubscribing. - 22: - description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version - 1; an explicit 1 also selects version 1. - values: - 0: Version 1 (also the omitted/malformed-width fallback) - 1: Version 1 - publication: - title: Legacy cached payload update - description: Version 1 updates use the additive checksum and legacy chunks. Empty payload data - is omitted. - headers: - 3: - presence: omitted - description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - 17: - description: Identifies nonzero subscription IDs for this publication. - 22: - presence: omitted - description: Legacy version 1 responses retain their original wire layout and omit Message - Version. - fields: - 1: - presence: required - description: 'Additive checksum: sum of all cached payload bytes modulo 65536.' - 2: - presence: omitted - description: The CRC field belongs to version 2. - 10: - maxBytes: 255 - description: Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 11: - maxBytes: 255 - description: Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 12: - maxBytes: 255 - description: Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 13: - maxBytes: 255 - description: Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 14: - maxBytes: 255 - description: Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload - data is omitted. - 129: - presence: omitted - description: Version 1 retains the legacy wire layout; it does not include the extended full-payload - field. - 2: - anchorId: v2 - messageVersion: 2 - title: Version 2 · complete-payload publications - description: Explicit version 2 selects the shared extended-payload and CRC publication format. - request: - headers: - 1: {} - 5: {presence: required, value: 3} - 6: - description: Optional publication interval in milliseconds. If omitted, updates are sent when - new data is available. - 7: - description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. - 16: - description: Minimum publication level. - 17: - description: Subscription ID; omit for the default subscription (0). Use the same ID when - unsubscribing. - 22: - presence: required - value: 2 - publication: - title: Cached payload update - description: Version 2 updates include Message Version 2 and field 2. Field 129 carries the complete - cached payload when nonempty; empty payload data is omitted. - headers: - 3: - presence: omitted - description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - 17: - description: Identifies nonzero subscription IDs for this publication. - 22: - presence: required - value: 2 - fields: - 1: - presence: omitted - description: The legacy additive checksum is absent from version 2 responses. - 2: - presence: required - description: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty - cache. One- or two-byte little-endian encoding may omit a high zero byte. - 129: - maxBytes: 1024 - description: Complete cached payload in an extended-length field with a uint16 little-endian - length prefix. Empty payload data is omitted. + description: ACK Type identifies the original message type (58). No message-specific state is returned + in this ACK. + errors: &messageBoxSubscribeErrors + - code: 4 + description: 'Invalid Parameter: a decoded Message Version value above 2; existing selection and + subscription are unchanged.' + - code: 7 + description: 'Not Supported: the product or firmware does not support this operation.' + messageVersion: 2 + request: + headers: + 1: {} + 5: { presence: required, value: 3 } + 6: + description: Optional publication interval in milliseconds. If omitted, updates are sent when new data + is available. + 7: + description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. + 16: + description: Minimum publication level. + 17: + description: Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. + 22: + presence: required + value: 2 + publication: + title: Cached payload update + description: Version 2 updates include Message Version 2 and field 2. Field 129 carries the complete + cached payload when nonempty; empty payload data is omitted. + headers: + 3: + presence: omitted + description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. + 17: + description: Identifies nonzero subscription IDs for this publication. + 22: + presence: required + value: 2 + fields: + 1: + presence: omitted + description: The legacy additive checksum is absent from version 2 responses. + 2: + presence: required + description: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- + or two-byte little-endian encoding may omit a high zero byte. + 129: + maxBytes: 1024 + description: Complete cached payload in an extended-length field with a uint16 little-endian length + prefix. Empty payload data is omitted. + subscribe-message-box-v1: + title: Subscribe to cached-message updates (legacy v1) + description: >- + The latest valid SUBSCRIBE selects one shared format for all Message Box publications, not a format + per subscriber. A decoded version above 2 leaves both the existing format selection and subscription + unchanged. Control acknowledgment and later publications are distinct messages. + + + Omitted, explicitly 0, malformed-width, or explicit version 1 selects the shared legacy publication + format. + response: *messageBoxSubscribeAck + errors: *messageBoxSubscribeErrors + messageVersion: 1 + request: + headers: + 1: {} + 5: { presence: required, value: 3 } + 6: + description: Optional publication interval in milliseconds. If omitted, updates are sent when new data + is available. + 7: + description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. + 16: + description: Minimum publication level. + 17: + description: Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. + 22: + description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an + explicit 1 also selects version 1. + values: + 0: Version 1 (also the omitted/malformed-width fallback) + 1: Version 1 + publication: + title: Legacy cached payload update + description: Version 1 updates use the additive checksum and legacy chunks. Empty payload data is omitted. + headers: + 3: + presence: omitted + description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. + 17: + description: Identifies nonzero subscription IDs for this publication. + 22: + presence: omitted + description: Legacy version 1 responses retain their original wire layout and omit Message Version. + fields: + 1: + presence: required + description: 'Additive checksum: sum of all cached payload bytes modulo 65536.' + 2: + presence: omitted + description: The CRC field belongs to version 2. + 10: + maxBytes: 255 + description: Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 11: + maxBytes: 255 + description: Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 12: + maxBytes: 255 + description: Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 13: + maxBytes: 255 + description: Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 14: + maxBytes: 255 + description: Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload data is + omitted. + 129: + presence: omitted + description: Version 1 retains the legacy wire layout; it does not include the extended full-payload field. stop-message-box-subscription: - method: UNSUBSCRIBE - anchorId: unsubscribe title: Stop a subscription - description: Remove the addressed subscription. Message Version (header 22) is ignored; UNSUBSCRIBE - does not select or reset the publication format, and neither does subscription expiry. + description: Remove the addressed subscription. Message Version (header 22) is ignored; UNSUBSCRIBE does + not select or reset the publication format, and neither does subscription expiry. errors: - - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' - versions: - 1: - request: - headers: - 1: {} - 5: {presence: required, value: 5} - 17: - description: Use the Subscription ID to remove, or omit it for the default subscription (0). - response: - messageId: 5 - description: Successful UNSUBSCRIBE returns a control ACK confirming the unsubscribe request, not a - final cached-message publication. - headers: - 3: {} - 4: {presence: required, value: 0} - fields: - 1: - presence: required - value: 58 - description: ACK Type identifies the original message type (58). No message-specific state - is returned in this ACK. + - code: 7 + description: 'Not Supported: the product or firmware does not support this operation.' + request: + headers: + 1: {} + 5: { presence: required, value: 5 } + 17: + description: Use the Subscription ID to remove, or omit it for the default subscription (0). + response: + messageId: 5 + description: Successful UNSUBSCRIBE returns a control ACK confirming the unsubscribe request, not a + final cached-message publication. + headers: + 3: {} + 4: { presence: required, value: 0 } + fields: + 1: + presence: required + value: 58 + description: ACK Type identifies the original message type (58). No message-specific state is returned + in this ACK. tracking-message-box-upload: - anchorId: tracking-session title: Tracking-session uploads - description: A separate device-to-server context, not a GET response or subscription update. Tracking-session - messages always use Message Version 2. Field 129 may carry independent Transmit Now upload data, not - the cached down-synced payload. Cached-message CRC reporting is Viper-only. Independent Transmit Now - uploads can use MT58 without cached Message Box support; those upload-only messages omit field 2. + description: A separate device-to-server context, not a GET response or subscription update. + Tracking-session messages always use Message Version 2. Field 129 may carry independent Transmit Now + upload data, not the cached down-synced payload. Cached-message CRC reporting is Viper-only. + Independent Transmit Now uploads can use MT58 without cached Message Box support; those upload-only + messages omit field 2. target: Viper or Transmit Now upload-enabled firmware - versions: - 1: - messageVersion: 2 - publication: - title: Device upload (MT58) - description: When Message Box support is enabled, field 2 reports the cached-message CRC, including - 0 for an empty cache. Independent upload bytes in field 129 do not form part of that cached-message - CRC. - headers: - 22: - presence: required - value: 2 - fields: - 2: - description: 'Present when Message Box support is enabled: CRC-16/XMODEM of the cached down-synced - message, not a checksum of the upload in field 129. Zero for an empty cache.' - 129: - description: Independent Transmit Now upload data; do not compare its CRC with field 2 to - validate the upload. + messageVersion: 2 + publication: + title: Device upload (MT58) + description: When Message Box support is enabled, field 2 reports the cached-message CRC, including 0 + for an empty cache. Independent upload bytes in field 129 do not form part of that cached-message + CRC. + headers: + 22: + presence: required + value: 2 + fields: + 2: + description: 'Present when Message Box support is enabled: CRC-16/XMODEM of the cached down-synced + message, not a checksum of the upload in field 129. Zero for an empty cache.' + 129: + description: Independent Transmit Now upload data; do not compare its CRC with field 2 to validate the + upload. notes: - id: support title: Unsupported products - placement: overview description: >- The cached feature requires supporting firmware. Unsupported products return Not Supported (Status header 4, code 7). Independent Transmit Now uploads are documented separately below and do not imply support for the cached feature. - id: sync-lifecycle title: How syncing works - placement: overview description: | The device reports its cached-message checksum during a tracking session. If a completed session contains a valid report and the server's configured data has a different checksum, the server can send a version 2 SET with the desired bytes. Unconfigured or invalid server data leaves the cache unchanged; an explicitly configured empty payload requests a clear. @@ -3829,7 +3772,6 @@ messages: Later tracking-session reports let the server check the reported cache checksum and offer the update again if it still differs. Sending an update or receiving an ACK alone does not confirm that the cache is synchronized. - id: message-versions title: Format dates and wire selectors - placement: reference description: >- The date labels identify when each documented format was introduced in source, not a firmware release date. The 2026-10 format uses Message Version 2; the earlier 2025-10 @@ -3837,7 +3779,6 @@ messages: The numeric values remain visible in the request and response header documentation. - id: checksum-scope title: Payload CRC and frame CRC are different - placement: reference description: >- The device calculates and stores CRC-16/XMODEM of the cached payload: polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000. The outer diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index a948478a0..4d16a1bcc 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -1,7 +1,6 @@ import { describe, expect, it } from '@jest/globals' import { readFileSync } from 'node:fs' import { resolve } from 'node:path' -import { resolveProtocolInteraction, validateProtocolInteractions } from './ProtocolInteractions' import { calculateCRC16XMODEM, parseRawMessage, readTypedData } from '../src/protocol/base.gen' // The repository's YAML dependency is intentionally untyped. const yaml = require('js-yaml') @@ -17,12 +16,14 @@ import { documentationTargetOverride, resolveDocumentationFields, validateMessageDocumentation, + validateProtocolInteractions, type DocumentationOperation, } from './MessageDocumentation' const protocol: any = yaml.load(readFileSync(resolve(__dirname, '../public/files/protocol-v3.yaml'), 'utf8')) const clone = (value: any) => JSON.parse(JSON.stringify(value)) -const authoredInteraction = (message: any, selector: string): any => Object.values(message.interactions).find((interaction: any) => interaction.method === selector || interaction.anchorId === selector) +const authoredInteraction = (message: any, method: string): any => Object.values(message.interactions).find((interaction: any) => protocol.header[5].values[interaction.request?.headers?.[5]?.value]?.name === method) +const interactionView = (messageId: number, id: string) => getMessageDocumentation(protocol.messages[messageId], protocol)!.operations.find(operation => operation.id === id)! describe('Cell Info signal strength terminology', () => { it('names raw CSQ as signal strength while preserving the field identity and type', () => { @@ -61,13 +62,13 @@ describe('paired exchange stages', () => { for (const id of [39, 58]) { const message = protocol.messages[id] expect(message.examples).toBeUndefined() - const docs = getMessageDocumentation(message)! + const docs = getMessageDocumentation(message, protocol)! for (const operation of docs.operations) for (const variant of operation.variants || [operation]) { expect(getOperationVariant(operation, variant.id).examples).toBeUndefined() } expect(validateMessageDocumentation(protocol, id)).toEqual([]) } - expect(getMessageDocumentation(protocol.messages[5])).toBeUndefined() + expect(getMessageDocumentation(protocol.messages[5], protocol)).toBeUndefined() expect(protocol.messages[5].examples.some((example: any) => example.bytes && example.real)).toBe(true) }) }) @@ -101,7 +102,7 @@ describe('shared response conventions', () => { expect(commonResponseHeaderIds({ headers: { '3': { presence: 'optional', description: 'A message-specific correlation rule.' }, '4': { presence: 'required', value: 0, maxBytes: 1 } } })).toEqual([]) }) it('keeps MT58 version/payload rules and explicit publication correlation distinct', () => { - const message = getMessageDocumentation(protocol.messages[58])! + const message = getMessageDocumentation(protocol.messages[58], protocol)! const get = getOperationVariant(message.operations.find(operation => operation.method === 'GET')!, '2') const subscribe = getOperationVariant(message.operations.find(operation => operation.method === 'SUBSCRIBE')!, '2') expect(commonResponseHeaderIds(get.response!)).toEqual(['3', '4']) @@ -120,9 +121,9 @@ describe('shared response conventions', () => { describe('optional message documentation', () => { it('leaves legacy messages on their existing renderer', () => { const legacy = { description: 'Existing prose', methods: { GET: null }, data: {} } - expect(getMessageDocumentation(legacy)).toBeUndefined() + expect(getMessageDocumentation(legacy, protocol)).toBeUndefined() expect(validateMessageDocumentation({ messages: { 15: legacy } }, 15)).toEqual([]) - expect(getMessageDocumentation(protocol.messages[15])).toBeUndefined() + expect(getMessageDocumentation(protocol.messages[15], protocol)).toBeUndefined() }) it('inherits operation contexts and selects variants without mutating either', () => { @@ -167,7 +168,7 @@ describe('optional message documentation', () => { const message = sample.messages[39] delete message.interactions message.methods.GET = { exchange: { request: { headers: { 5: { value: 2 } } } } } - message.notes = [{ id: 'detail', title: 'Detail', description: 'Text', placement: 'unknown' }] + message.notes = [{ id: 'detail', title: 'Detail', description: 'Text' }] message.methods.UNSUPPORTED = { exchange: { request: { headers: { 5: { value: 99 }, 250: {} }, fields: { 99: {} } }, response: { messageId: 9999 }, @@ -180,7 +181,6 @@ describe('optional message documentation', () => { expect(errors).toContain('unknown headers id 250') expect(errors).toContain('unknown fields id 99') expect(errors).toContain('unknown message 9999') - expect(errors).toContain('invalid note placement') }) it('puts required fields first while preserving order within each group', () => { @@ -194,35 +194,27 @@ describe('optional message documentation', () => { const before = clone(usage) expect(resolveDocumentationFields(protocol, protocol.messages[58], usage, 'headers').map(field => field.id)).toEqual([4, 5, 1, 17, 22]) expect(usage).toEqual(before) - const set = getMessageDocumentation(protocol.messages[58])!.operations.find((operation: DocumentationOperation) => operation.method === 'SET') + const set = getMessageDocumentation(protocol.messages[58], protocol)!.operations.find((operation: DocumentationOperation) => operation.method === 'SET') expect(resolveDocumentationFields(protocol, protocol.messages[58], set!.request!.headers, 'headers').map(field => field.id)).toEqual([5, 22, 1]) expect(resolveDocumentationFields(protocol, protocol.messages[58], set!.request!.fields, 'fields')[0].id).toBe(129) }) - it('accepts optional reference-note placement while retaining the overview default', () => { - const sample = clone(protocol) - sample.messages[39].notes = [ - { id: 'purpose', title: 'Purpose', description: 'Overview text' }, - { id: 'detail', title: 'Details', description: 'Reference text', placement: 'reference' }, - ] - expect(validateMessageDocumentation(sample, 39)).toEqual([]) - }) - it('groups dated formats by their wire selector without classifying shared controls as current', () => { - const docs = getMessageDocumentation(protocol.messages[58])! + const docs = getMessageDocumentation(protocol.messages[58], protocol)! expect(docs.formats?.map(format => [format.label, format.messageVersion, !!format.legacy])).toEqual([ ['2026-10', 2, false], ['2025-10', 1, true], ]) - for (const id of ['get', 'set', 'subscribe', 'tracking-session']) { - const operation = docs.operations.find(item => (item.anchorId || item.id) === id)! + for (const id of ['read-message-box', 'replace-message-box', 'subscribe-message-box', 'tracking-message-box-upload']) { + const operation = docs.operations.find(item => item.id === id)! expect(getDocumentationFormat(docs, getOperationVariant(operation))?.id).toBe('2') } for (const method of ['GET', 'SUBSCRIBE']) { - const operation = docs.operations.find(item => item.method === method)! - expect(getDocumentationFormat(docs, getOperationVariant(operation, 'v1'))?.id).toBe('1') + const operation = docs.operations.find(item => item.method === method && item.messageVersion === 1)! + expect(getDocumentationFormat(docs, operation)?.id).toBe('1') + expect(operation.legacy).toBe(true) } expect(getDocumentationFormat(docs, docs.operations.find(item => item.method === 'UNSUBSCRIBE')!)).toBeUndefined() - expect(getMessageDocumentation(protocol.messages[39])!.formats).toBeUndefined() + expect(getMessageDocumentation(protocol.messages[39], protocol)!.formats).toBeUndefined() const syncParagraphs = docs.notes!.find(note => note.id === 'sync-lifecycle')!.description.trim().split('\n\n') expect(syncParagraphs).toHaveLength(3) expect(syncParagraphs.every(paragraph => !paragraph.includes('\n'))).toBe(true) @@ -242,7 +234,7 @@ describe('optional message documentation', () => { it('suppresses inherited targets but retains explicit overrides', () => { expect(documentationTargetOverride(undefined, 'Viper devices only')).toBeUndefined() expect(documentationTargetOverride(' Viper devices ONLY ', 'Viper devices only')).toBeUndefined() - const docs = getMessageDocumentation(protocol.messages[58])! + const docs = getMessageDocumentation(protocol.messages[58], protocol)! const upload = docs.operations.find(item => (item.anchorId || item.id) === 'tracking-session')! expect(documentationTargetOverride(upload.target, docs.target)).toBe(upload.target) expect(documentationTargetOverride('Different target', upload.target)).toBe('Different target') @@ -250,47 +242,36 @@ describe('optional message documentation', () => { it('accepts a response payload scoped to its actual ACK message', () => { const sample = clone(protocol) - authoredInteraction(sample.messages[39], 'SET').versions[1].response = { messageId: 5, fields: { 1: { value: 39 } } } + authoredInteraction(sample.messages[39], 'SET').response = { messageId: 5, fields: { 1: { value: 39 } } } expect(validateMessageDocumentation(sample, 39)).toEqual([]) }) it('validates references for each migrated message', () => { - expect(Object.entries(protocol.messages).filter(([, value]: [string, any]) => getMessageDocumentation(value)).map(([id]) => Number(id))).toEqual([31, 33, 34, 35, 39, 58]) + expect(Object.entries(protocol.messages).filter(([, value]: [string, any]) => getMessageDocumentation(value, protocol)).map(([id]) => Number(id))).toEqual([31, 33, 34, 35, 39, 58]) for (const id of [31, 33, 34, 35, 39, 58]) expect(validateMessageDocumentation(protocol, id)).toEqual([]) }) it('summarizes every message field within its applicable version', () => { for (const id of [31, 33, 34, 35, 39, 58]) { - const docs = getMessageDocumentation(protocol.messages[id])! + const docs = getMessageDocumentation(protocol.messages[id], protocol)! const groups = docs.formats?.map(format => format.fields || {}) || [docs.fields || {}] expect(groups.flatMap(fields => Object.keys(fields)).sort()).toEqual(Object.keys(protocol.messages[id].data).sort()) } - const formats = getMessageDocumentation(protocol.messages[58])!.formats! + const formats = getMessageDocumentation(protocol.messages[58], protocol)!.formats! expect(Object.keys(formats.find(format => format.id === '2')!.fields!)).toEqual(['2', '129']) expect(Object.keys(formats.find(format => format.id === '1')!.fields!)).toEqual(['1', '10', '11', '12', '13', '14']) }) - it('makes Message Box v2 primary while retaining explicit legacy v1 variants', () => { - const docs = getMessageDocumentation(protocol.messages[58])! - for (const method of ['GET', 'SUBSCRIBE']) { - const operation = docs.operations.find(item => item.method === method)! - expect(getOperationVariant(operation).messageVersion).toBe(2) - expect(getOperationVariant(operation).legacy).not.toBe(true) - const legacy = operation.variants!.filter(variant => variant.legacy) - expect(legacy).toHaveLength(1) - expect(legacy[0].messageVersion).toBe(1) - } - }) }) -describe('inline numeric-version authoring', () => { +describe('wire-version authoring', () => { it('normalizes numeric keys in newest-first order without changing the source', () => { const before = clone(protocol) const message = protocol.messages[58] expect(Object.keys(message.versions)).toEqual(['1', '2']) expect(message.data[129].versions).toEqual([2]) expect(message.data[1].versions).toEqual([1]) - const docs = getMessageDocumentation(message)! + const docs = getMessageDocumentation(message, protocol)! expect(docs.formats!.map(format => format.id)).toEqual(['2', '1']) expect(docs.formats!.map(format => format.label)).toEqual(['2026-10', '2025-10']) expect(docs.formats![1].anchorId).toBe('legacy') @@ -320,8 +301,8 @@ describe('inline numeric-version authoring', () => { const sample = clone(protocol) const message = sample.messages[58] message.data[129].versions = [9] - authoredInteraction(message, 'SET').versions[9] = { ...authoredInteraction(message, 'SET').versions[1], messageVersion: 9 } - authoredInteraction(message, 'GET').versions[2].response.headers[22].value = 1 + authoredInteraction(message, 'SET').messageVersion = 9 + authoredInteraction(message, 'GET').response.headers[22].value = 1 const errors = validateMessageDocumentation(sample, 58).join('\n') expect(errors).toContain('field 129 references unknown version 9') expect(errors).toContain('references unknown message version 9') @@ -333,8 +314,8 @@ describe('inline numeric-version authoring', () => { it('rejects malformed inline contexts before normalization can conceal them', () => { for (const update of [ - (message: any) => { authoredInteraction(message, 'SET').versions[1].request.fields[2] = null }, - (message: any) => { authoredInteraction(message, 'SET').versions[1].request = 'broken' }, + (message: any) => { authoredInteraction(message, 'SET').request.fields[2] = null }, + (message: any) => { authoredInteraction(message, 'SET').request = 'broken' }, (message: any) => { message.contexts = [] }, (message: any) => { message.contexts = { tracking: null } }, ]) { @@ -343,47 +324,32 @@ describe('inline numeric-version authoring', () => { expect(validateMessageDocumentation(sample, 39).length).toBeGreaterThan(0) } const sample = clone(protocol) - authoredInteraction(sample.messages[58], 'GET').versions[2].response.fields[2] = null + authoredInteraction(sample.messages[58], 'GET').response.fields[2] = null expect(validateMessageDocumentation(sample, 58).join('\n')).toContain('fields 2 must be an object') }) - it('keeps version identity and deep links stable when a display label changes', () => { - const sample = clone(protocol) - const message = sample.messages[58] - message.versions[2].label = '2027-02' - const docs = getMessageDocumentation(message)! - const get = docs.operations.find(operation => (operation.anchorId || operation.id) === 'get')! - expect(get.variants!.map(variant => variant.id)).toEqual(['2', '1']) - expect(getOperationVariant(get).format).toBe('2') - expect(getOperationVariant(get, 'v2').format).toBe('2') - expect(getOperationVariant(get, 'v1').format).toBe('1') - expect(docs.formats![0]).toMatchObject({ id: '2', label: '2027-02', messageVersion: 2, anchorId: 'current' }) - expect(validateMessageDocumentation(sample, 58)).toEqual([]) - }) - it('inherits existing method field descriptions before base descriptions', () => { const message = clone(protocol.messages[39]) - delete authoredInteraction(message, 'SET').versions[1].request.fields[2].description - const docs = getMessageDocumentation(message)! + delete authoredInteraction(message, 'SET').request.fields[2].description + const docs = getMessageDocumentation(message, protocol)! const set = docs.operations.find(operation => operation.method === 'SET')! expect(set.request!.fields![2].description).toBe(message.methods.SET.request[2].description) - expect(authoredInteraction(message, 'SET').versions[1].request.fields[2].description).toBeUndefined() + expect(authoredInteraction(message, 'SET').request.fields[2].description).toBeUndefined() }) it('keeps ignored checksums out of SET inputs without deleting the compatibility rule', () => { - const set = authoredInteraction(protocol.messages[58], 'SET').versions[1] + const set = authoredInteraction(protocol.messages[58], 'SET') expect(Object.keys(set!.request!.fields)).toEqual(['129']) expect(set.request.description).toContain('checksum fields 1 and 2 are ignored') expect(set!.request!.fields[129]).toMatchObject({ presence: 'required', maxBytes: 1024 }) - const get = authoredInteraction(protocol.messages[58], 'GET').versions[2] + const get = authoredInteraction(protocol.messages[58], 'GET') expect(get.response.fields[2].presence).toBe('required') }) }) - describe('Device Status reference', () => { const message = protocol.messages[34] - const docs = getMessageDocumentation(message)! + const docs = getMessageDocumentation(message, protocol)! it('documents optional fields 12–14 in GET responses and later publications', () => { const message = protocol.messages[34]; expect(message.data[12]).toMatchObject({ id: 'batteryResistance', type: 'uint16', unit: 'mOhm' }); @@ -392,8 +358,8 @@ describe('Device Status reference', () => { const fields = resolveDocumentationFields(protocol, message, docs.fields, 'fields'); expect(fields.find(field => field.id === 13)?.sentinels).toEqual(message.data[13].sentinels); expect(message.data[14]).toMatchObject({ id: 'batteryChargeAh', type: 'float32', unit: 'Ah' }); - for (const context of [message.methods.GET.exchange.response, message.methods.SUBSCRIBE.exchange.publication]) { - for (const id of [12, 13, 14]) expect(context.fields[id]).toEqual({ presence: 'optional' }); + for (const context of [docs.operations[0].response!, docs.operations[1].publication!]) { + for (const id of [12, 13, 14]) expect(context.fields![id]).toMatchObject({ presence: 'optional' }); } expect(validateMessageDocumentation(protocol, 34)).toEqual([]); }); @@ -484,7 +450,7 @@ describe('Device Status reference', () => { describe('Device IDs reference', () => { const message = protocol.messages[35] - const docs = getMessageDocumentation(message)! + const docs = getMessageDocumentation(message, protocol)! const get = docs.operations[0] it('keeps GET unversioned and preserves every wire field, including uncaptured identifiers', () => { @@ -544,16 +510,21 @@ describe('canonical inline interactions', () => { const before = clone(protocol) for (const id of [31, 33, 34, 35, 39, 58]) { const message = protocol.messages[id] - expect(getDocumentationMethods(message).slice().sort()).toEqual(Object.keys(message.methods).sort()) - expect(getMessageDocumentation(message)!.methods).toEqual(getDocumentationMethods(message)) + expect(getDocumentationMethods(message, protocol).slice().sort()).toEqual(Object.keys(message.methods).sort()) + expect(getMessageDocumentation(message, protocol)!.methods).toEqual(getDocumentationMethods(message, protocol)) } - expect(getDocumentationMethods(protocol.messages[31])).toEqual(['GET', 'SET']) - const publication = { interactions: { upload: { versions: { 1: { publication: {} } } } } } - expect(getDocumentationMethods(publication)).toEqual([]) - expect(getDocumentationMethods({ methods: { GET: null, SET: null } })).toEqual(['GET', 'SET']) + expect(getDocumentationMethods(protocol.messages[31], protocol)).toEqual(['GET', 'SET']) + const publication = { interactions: { upload: { publication: {} } } } + expect(getDocumentationMethods(publication, protocol)).toEqual([]) + expect(getDocumentationMethods({ methods: { GET: null, SET: null } }, protocol)).toEqual(['GET', 'SET']) const changed = clone(protocol.messages[31]) changed.methods = { SUBSCRIBE: null } - expect(getDocumentationMethods(changed)).toEqual(['GET', 'SET']) + expect(getDocumentationMethods(changed, protocol)).toEqual(['GET', 'SET']) + const renamedEnum = clone(protocol) + renamedEnum.header[5].values[2].name = 'READ' + expect(getDocumentationMethods(changed, renamedEnum)).toEqual(['READ', 'SET']) + expect(interactionView(58, 'tracking-message-box-upload').method).toBeUndefined() + expect(interactionView(34, 'read-device-status').messageVersion).toBeUndefined() expect(protocol).toEqual(before) }) @@ -565,31 +536,16 @@ describe('canonical inline interactions', () => { extra.messages[33].methods.SUBSCRIBE = null expect(validateProtocolInteractions(extra).join('\n')).toContain('SDK method SUBSCRIBE has no interaction') const publication = { ...clone(protocol), messages: { 31: { - description: 'Publication only', data: {}, interactions: { upload: { versions: { 1: { publication: {} } } } }, + description: 'Publication only', data: {}, interactions: { upload: { publication: {} } }, } } } expect(validateProtocolInteractions(publication)).toEqual([]) expect(validateProtocolInteractions(protocol)).toEqual([]) }) - it('keeps interaction keys and public anchors stable when display titles change', () => { - for (const id of [31, 33, 34, 35, 39, 58]) { - const original = getMessageDocumentation(protocol.messages[id])! - const sample = clone(protocol.messages[id]) - for (const interaction of Object.values(sample.interactions) as any[]) interaction.title = 'Revised display title' - const changed = getMessageDocumentation(sample)! - const identities = (docs: typeof original) => docs.operations.map(operation => ({ - id: operation.id, anchorId: operation.anchorId, - revisions: operation.variants?.map(variant => [variant.id, variant.anchorId]), - })) - expect(identities(changed)).toEqual(identities(original)) - expect(changed.operations.every(operation => operation.title === 'Revised display title')).toBe(true) - } - }) - it('relies on uint8 for Message Version width while retaining variable payload limits and legacy selectors', () => { expect(protocol.header[22].type).toBe('uint8') for (const id of [31, 33, 34, 35, 39, 58]) { - const docs = getMessageDocumentation(protocol.messages[id])! + const docs = getMessageDocumentation(protocol.messages[id], protocol)! for (const operation of docs.operations) for (const variant of operation.variants || [operation]) { const view = getOperationVariant(operation, variant.id) for (const role of ['request', 'response', 'publication'] as const) { @@ -597,12 +553,12 @@ describe('canonical inline interactions', () => { } } } - const legacy = resolveProtocolInteraction(protocol, 58, 'read-message-box', 1) + const legacy = interactionView(58, 'read-message-box-v1') expect(legacy.request?.headers?.[22]?.description).toContain('Omitted, explicitly 0, or malformed-width') expect(legacy.response?.headers?.[22]?.presence).toBe('omitted') expect(legacy.response?.fields?.[10]?.maxBytes).toBe(255) - expect(resolveProtocolInteraction(protocol, 58, 'replace-message-box', 1).request?.fields?.[129]?.maxBytes).toBe(1024) - expect(resolveProtocolInteraction(protocol, 33, 'select-sim2', 1).request?.fields?.[2]?.minBytes).toBe(1) + expect(interactionView(58, 'replace-message-box').request?.fields?.[129]?.maxBytes).toBe(1024) + expect(interactionView(33, 'select-sim2').request?.fields?.[2]?.minBytes).toBe(1) }) it('validates both published authoring examples against the existing wire definitions', () => { @@ -611,12 +567,12 @@ describe('canonical inline interactions', () => { expect(examples).toHaveLength(2) for (const example of examples) { const sample = clone(protocol) - const methods = Object.fromEntries(getDocumentationMethods(example).map(method => [method, null])) + const methods = Object.fromEntries(getDocumentationMethods(example, protocol).map(method => [method, null])) sample.messages[58] = { ...sample.messages[58], ...example, methods } expect(validateMessageDocumentation(sample, 58)).toEqual([]) for (const source of Object.values(example.interactions) as any[]) { - expect(Object.keys(source.versions)).toEqual(['1']) - expect(source.versions[1].messageVersion).toBe(2) + expect(source.versions).toBeUndefined() + expect(source.messageVersion).toBe(2) } } }) @@ -626,7 +582,7 @@ describe('canonical inline interactions', () => { [31, ['control-flight-mode', 'start-search']], [33, ['select-sim1', 'select-sim2']], ] as const) for (const name of names) { - const response = resolveProtocolInteraction(protocol, id, name, 1).response! + const response = interactionView(id, name).response! expect(response.messageId).toBe(5) expect(response.fields?.[1]?.value).toBe(id) } @@ -645,19 +601,13 @@ describe('canonical inline interactions', () => { expect(validateProtocolInteractions(protocol)).toEqual([]) for (const messageId of [31, 33, 34, 35, 39, 58]) { const message = protocol.messages[messageId] - const docs = getMessageDocumentation(message)! + const docs = getMessageDocumentation(message, protocol)! expect(docs.operations.map(operation => operation.id)).toEqual(Object.keys(message.interactions)) expect(message.contexts).toBeUndefined() for (const method of Object.values(message.methods) as any[]) { expect(method?.exchange).toBeUndefined() expect(method?.versions).toBeUndefined() } - for (const [id, source] of Object.entries(message.interactions) as [string, any][]) { - for (const revision of Object.keys(source.versions).map(Number)) { - const interaction = resolveProtocolInteraction(protocol, messageId, id, revision) - expect(interaction).toMatchObject({ interactionId: id, interactionVersion: revision, messageId, operationId: id }) - } - } } expect(protocol).toEqual(before) const duplicate = clone(protocol) @@ -665,36 +615,6 @@ describe('canonical inline interactions', () => { expect(validateMessageDocumentation(duplicate, 39).join('\n')).toContain('must not also be authored in methods or contexts') }) - it('keeps interaction revisions independent from wire formats, including revisions above 255', () => { - const sample = clone(protocol) - const source = sample.messages[58].interactions['replace-message-box'] - source.versions[700] = source.versions[1] - delete source.versions[1] - const resolved = resolveProtocolInteraction(sample, 58, 'replace-message-box', 700) - expect(resolved).toMatchObject({ id: 'replace-message-box', interactionVersion: 700, messageVersion: 2, format: '2', anchorId: 'set' }) - expect(resolved.request?.headers?.[22].value).toBe(2) - expect(resolved.response?.messageId).toBe(5) - expect(resolved.response?.fields?.[1].value).toBe(58) - const upload = resolveProtocolInteraction(protocol, 58, 'tracking-message-box-upload', 1) - expect(upload.publication).toBeDefined() - expect(upload.request).toBeUndefined() - expect(upload.method).toBeUndefined() - expect(resolveProtocolInteraction(protocol, 58, 'stop-message-box-subscription', 1).messageVersion).toBeUndefined() - }) - - it('supports applicability revisions of one wire format with distinct revision anchors', () => { - const sample = clone(protocol) - const source = sample.messages[58].interactions['replace-message-box'] - delete source.versions[1].anchorId - source.versions[2] = { ...clone(source.versions[1]), target: 'A different caller profile' } - expect(validateMessageDocumentation(sample, 58)).toEqual([]) - const operation = getMessageDocumentation(sample.messages[58])!.operations.find(item => item.id === 'replace-message-box')! - expect(operation.variants!.map(variant => [variant.id, variant.anchorId, variant.messageVersion])).toEqual([ - ['2', 'r2', 2], ['1', 'r1', 2], - ]) - expect(resolveProtocolInteraction(sample, 58, 'replace-message-box', 2).target).toBe('A different caller profile') - expect(resolveProtocolInteraction(sample, 58, 'replace-message-box', 1).target).toBe(sample.messages[58].target) - }) it('keeps old method and context documentation readable when no inline interactions exist', () => { const legacy = { @@ -702,7 +622,7 @@ describe('canonical inline interactions', () => { GET: { title: 'Read', exchange: { request: { headers: { 5: { value: 2 } } }, response: { fields: {} } } }, }, contexts: { upload: { exchange: { publication: { fields: {} } } } }, } - const docs = getMessageDocumentation(legacy)! + const docs = getMessageDocumentation(legacy, protocol)! expect(docs.operations.map(operation => operation.id)).toEqual(['get', 'upload']) expect(docs.operations[0].method).toBe('GET') expect(docs.operations[1].publication).toBeDefined() @@ -714,13 +634,13 @@ describe('canonical inline interactions', () => { const sim = protocol.messages[33] expect(gsm.methods).toEqual({ GET: null, SET: null }) expect(sim.methods).toEqual({ GET: null, SET: null }) - const flight = resolveProtocolInteraction(protocol, 31, 'control-flight-mode', 1) - const search = resolveProtocolInteraction(protocol, 31, 'start-search', 1) + const flight = interactionView(31, 'control-flight-mode') + const search = interactionView(31, 'start-search') expect(Object.keys(flight.request!.fields!)).toEqual(['1', '2']) expect(flight.request?.description).toContain('Omit Start Search (field 5)') expect(search.request?.fields?.[5].presence).toBe('required') - const sim1 = resolveProtocolInteraction(protocol, 33, 'select-sim1', 1) - const sim2 = resolveProtocolInteraction(protocol, 33, 'select-sim2', 1) + const sim1 = interactionView(33, 'select-sim1') + const sim2 = interactionView(33, 'select-sim2') expect(sim1.request?.fields?.[1].value).toBe(0) expect(sim2.request?.fields?.[1].value).toBe(1) expect(sim2.request?.fields?.[2]).toMatchObject({ presence: 'required', minBytes: 1 }) @@ -730,15 +650,15 @@ describe('canonical inline interactions', () => { }) it('lists expected GSM and SIM inputs while retaining ignored-input behavior in prose', () => { - const flight = resolveProtocolInteraction(protocol, 31, 'control-flight-mode', 1) - const search = resolveProtocolInteraction(protocol, 31, 'start-search', 1) + const flight = interactionView(31, 'control-flight-mode') + const search = interactionView(31, 'start-search') expect(flight.request?.description).toContain('fields 3 and 4) are ignored by SET') expect(Object.keys(search.request!.headers!)).toEqual(['1', '5']) expect(Object.keys(search.request!.fields!)).toEqual(['5']) expect(search.request?.description).toContain('even when its value is 0') expect(search.request?.description).toContain('Fields 1 to 4 and header Duration (7) are ignored') - const sim1 = resolveProtocolInteraction(protocol, 33, 'select-sim1', 1) - const sim2 = resolveProtocolInteraction(protocol, 33, 'select-sim2', 1) + const sim1 = interactionView(33, 'select-sim1') + const sim2 = interactionView(33, 'select-sim2') expect(Object.keys(sim1.request!.fields!)).toEqual(['1']) expect(sim1.request?.description).toContain('SIM2 APN and credentials are ignored') expect(Object.keys(sim2.request!.fields!)).toEqual(['1', '2', '3', '4']) @@ -748,14 +668,14 @@ describe('canonical inline interactions', () => { }) it('keeps GPS rejection and Message Box format exceptions without advertising them as inputs', () => { - const get = resolveProtocolInteraction(protocol, 39, 'read-gps-state', 1) - const set = resolveProtocolInteraction(protocol, 39, 'configure-gps', 1) + const get = interactionView(39, 'read-gps-state') + const set = interactionView(39, 'configure-gps') expect(get.request?.fields).toBeUndefined() expect(get.description).toContain('No payload fields are needed') expect(Object.keys(set.request!.fields!)).toEqual(['2', '3']) expect(set.request?.description).toContain('field 1) in SET is rejected with Invalid Parameter (4)') expect(set.request?.fields?.[2].description).toContain('sets API-enabled corrections to disabled') - const stop = resolveProtocolInteraction(protocol, 58, 'stop-message-box-subscription', 1) + const stop = interactionView(58, 'stop-message-box-subscription') expect(Object.keys(stop.request!.headers!)).toEqual(['1', '5', '17']) expect(stop.description).toContain('Message Version (header 22) is ignored') expect(stop.description).toContain('does not select or reset the publication format') @@ -764,25 +684,47 @@ describe('canonical inline interactions', () => { }) it.each([ - ['unknown property', (source: any) => { source.context = 'old-alias' }], - ['empty method', (source: any) => { source.method = '' }], + ['authored method', (source: any) => { source.method = 'SET' }], + ['site anchor', (source: any) => { source.anchorId = 'set' }], + ['nested revisions', (source: any) => { source.versions = { 1: {} } }], ['invalid title', (source: any) => { source.title = 4 }], - ['empty revisions', (source: any) => { source.versions = {} }], - ['zero revision', (source: any) => { source.versions = { 0: source.versions[1] } }], - ['unsafe revision', (source: any) => { source.versions = { '9007199254740992': source.versions[1] } }], - ['missing wire selector', (source: any) => { delete source.versions[1].messageVersion }], - ['unknown wire selector', (source: any) => { source.versions[1].messageVersion = 99 }], - ['unknown revision property', (source: any) => { source.versions[1].wireVersion = 2 }], - ['empty exchange', (source: any) => { source.versions = { 1: { messageVersion: 2 } } }], - ['unknown field', (source: any) => { source.versions[1].request.fields[999] = {} }], - ['method disagreement', (source: any) => { source.versions[1].request.headers[5].value = 2 }], - ['unknown message', (source: any) => { source.versions[1].response.messageId = 65534 }], - ['invalid minBytes', (source: any) => { source.versions[1].request.fields[129].minBytes = -1 }], - ['conflicting byte bounds', (source: any) => { source.versions[1].request.fields[129].minBytes = 1025 }], - ])('rejects %s before resolving an interaction', (_label, change) => { + ['missing wire version', (source: any) => { delete source.messageVersion }], + ['unknown wire version', (source: any) => { source.messageVersion = 99 }], + ['missing method selector', (source: any) => { delete source.request.headers[5] }], + ['unknown method selector', (source: any) => { source.request.headers[5].value = 99 }], + ['empty exchange', (source: any) => { delete source.request; delete source.response }], + ['unknown field', (source: any) => { source.request.fields[999] = {} }], + ['unknown message', (source: any) => { source.response.messageId = 65534 }], + ['conflicting byte bounds', (source: any) => { source.request.fields[129].minBytes = 1025 }], + ])('rejects %s in a flat interaction', (_label, change) => { const sample = clone(protocol) change(sample.messages[58].interactions['replace-message-box']) expect(validateMessageDocumentation(sample, 58).length).toBeGreaterThan(0) - expect(() => resolveProtocolInteraction(sample, 58, 'replace-message-box', 1)).toThrow() + }) + + it('keeps site aliases and layout out of YAML while preserving published links', () => { + for (const message of Object.values(protocol.messages) as any[]) { + for (const source of Object.values(message.interactions || {}) as any[]) { + expect(source.anchorId).toBeUndefined() + expect(source.method).toBeUndefined() + expect(source.versions).toBeUndefined() + } + for (const note of message.notes || []) expect(note.placement).toBeUndefined() + } + const message = clone(protocol.messages[58]) + const before = getMessageDocumentation(message, protocol)! + message.versions[2].label = '2027-02' + for (const source of Object.values(message.interactions) as any[]) source.title = 'New title' + const after = getMessageDocumentation(message, protocol)! + expect(after.operations.map(({ id, anchorId, anchorAliases }) => [id, anchorId, anchorAliases])) + .toEqual(before.operations.map(({ id, anchorId, anchorAliases }) => [id, anchorId, anchorAliases])) + expect(after.operations.filter(item => item.method === 'GET').map(({ id, messageVersion, anchorId, anchorAliases }) => + [id, messageVersion, anchorId, anchorAliases])).toEqual([ + ['read-message-box', 2, 'get-variant-v2', ['get']], + ['read-message-box-v1', 1, 'get-variant-v1', []], + ]) + const sample = clone(protocol) + sample.messages[58].notes[0].placement = 'overview' + expect(validateMessageDocumentation(sample, 58).join('\n')).toContain('note has unknown property placement') }) }) diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index 5051689e0..7761440d2 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -126,7 +126,6 @@ export function documentationTextParts(text: string, messages?: Record method?.exchange !== undefined || method?.versions !== undefined)) } +/** Read the method from the actual request selector, using the shared wire enum. */ +function interactionMethod(interaction: any, protocol: any): string | undefined { + const header = interaction?.request?.headers?.[5] + if (!header || ['ignored', 'omitted'].includes(header.presence)) return undefined + return protocol?.header?.[5]?.values?.[header.value]?.name +} + /** Distinct methods in authoring order; publications need no placeholder method. */ -export function getDocumentationMethods(message: any): string[] { +export function getDocumentationMethods(message: any, protocol: any): string[] { if (message?.interactions === undefined) return Object.keys(message?.methods || {}) return [...new Set(Object.values(message.interactions || {}) - .map((interaction: any) => interaction?.method) - .filter((method): method is string => typeof method === 'string' && !!method.trim()))] + .map(interaction => interactionMethod(interaction, protocol)) + .filter((method): method is string => typeof method === 'string'))] +} + +// Published site fragments predate the stable interaction keys. Keep this +// compatibility concern here, out of the protocol specification. +const interactionAnchors: Record> = { + deviceStatus: { + 'read-device-status': ['get'], 'subscribe-device-status': ['subscribe'], + 'stop-device-status-subscription': ['unsubscribe'], + }, + deviceIds: { 'read-device-ids': ['get'] }, + gpsControl: { 'read-gps-state': ['get'], 'configure-gps': ['set'] }, + _msgBox: { + 'read-message-box': ['get-variant-v2', 'get'], 'read-message-box-v1': ['get-variant-v1'], + 'replace-message-box': ['set'], + 'subscribe-message-box': ['subscribe-variant-v2', 'subscribe'], 'subscribe-message-box-v1': ['subscribe-variant-v1'], + 'stop-message-box-subscription': ['unsubscribe'], 'tracking-message-box-upload': ['tracking-session'], + }, } function wireVersion(exchange: any): number | undefined { @@ -207,7 +232,7 @@ function wireVersion(exchange: any): number | undefined { return undefined } -export function getMessageDocumentation(message: any): MessageDocumentation | undefined { +export function getMessageDocumentation(message: any, protocol: any): MessageDocumentation | undefined { if (!hasInlineMessageDocumentation(message)) return undefined const versions = message.versions || {} const operations: DocumentationOperation[] = [] @@ -236,9 +261,10 @@ export function getMessageDocumentation(message: any): MessageDocumentation | un } if (message.interactions !== undefined) { for (const [id, source] of Object.entries(message.interactions) as [string, any][]) { + const method = interactionMethod(source, protocol) const contexts = (value: any) => Object.fromEntries(['request', 'response', 'publication'].filter(role => value?.[role] !== undefined).map(role => { const context = value[role] - const inherited = message.methods?.[source.method]?.[role] + const inherited = message.methods?.[method || '']?.[role] return [role, { ...context, ...Object.fromEntries(['headers', 'fields'].filter(kind => context?.[kind] !== undefined).map(kind => [ kind, Object.fromEntries(Object.entries(context[kind]).map(([fieldId, usage]: [string, any]) => [ fieldId, { @@ -248,22 +274,15 @@ export function getMessageDocumentation(message: any): MessageDocumentation | un ])), ])) }] })) - const base: DocumentationOperation = { - ...contexts(source), id, method: source.method, anchorId: source.anchorId || id, + const [anchorId, ...anchorAliases] = interactionAnchors[message.id]?.[id] || [id] + operations.push({ + ...contexts(source), id, method, anchorId, anchorAliases, title: source.title || id, description: source.description, target: source.target, + messageVersion: source.messageVersion, + format: source.messageVersion === undefined ? undefined : String(source.messageVersion), + legacy: !!versions[source.messageVersion]?.legacy, errors: source.errors, examples: source.examples, - } - const variants: DocumentationVariant[] = Object.entries(source.versions || {}).sort(([a], [b]) => Number(b) - Number(a)) - .map(([revision, value]: [string, any]) => ({ - ...value, ...contexts(value), id: revision, interactionVersion: Number(revision), - title: value.title || versions[value.messageVersion]?.label || revision, - anchorId: value.anchorId || `r${revision}`, - format: value.messageVersion === undefined ? undefined : String(value.messageVersion), - legacy: !!versions[value.messageVersion]?.legacy, - })) - operations.push(variants.length === 1 - ? { ...base, ...variants[0], id, title: base.title, anchorId: base.anchorId } - : { ...base, variants }) + }) } } else { for (const [method, value] of Object.entries(message.methods || {})) addOperation(method.toLowerCase(), value, method) @@ -287,7 +306,9 @@ export function getMessageDocumentation(message: any): MessageDocumentation | un } }) return { - summary: message.description || '', methods: getDocumentationMethods(message), target: message.target, notes: message.notes, + summary: message.description || '', methods: getDocumentationMethods(message, protocol), target: message.target, + notes: message.notes?.map((note: any) => ({ ...note, placement: message.id === '_msgBox' && + ['message-versions', 'checksum-scope'].includes(note.id) ? 'reference' : 'overview' })), fields: formats.length ? undefined : fieldsFor(), formats: formats.length ? formats : undefined, operations, } @@ -376,7 +397,10 @@ function validateInlineDocumentation(message: any, messageId: number, protocol: for (const [id, context] of Object.entries(object(message.contexts) ? message.contexts : {})) { if (!object(context) || (!(context as any).exchange && !(context as any).versions)) errors.push(`${id} context needs an exchange or versions`) } - if (message.notes !== undefined && (!Array.isArray(message.notes) || message.notes.some((note: any) => !object(note)))) errors.push('notes must be a list of objects') + if (message.notes !== undefined) { + if (!Array.isArray(message.notes) || message.notes.some((note: any) => !object(note))) errors.push('notes must be a list of objects') + else for (const note of message.notes) knownKeys(note, ['id', 'title', 'description'], 'note') + } const versions = object(message.versions) ? message.versions : {} if (message.versions !== undefined && !object(message.versions)) errors.push('versions must be a numeric-keyed mapping') for (const [id, version] of Object.entries(versions) as [string, any][]) { @@ -398,37 +422,24 @@ function validateInlineDocumentation(message: any, messageId: number, protocol: if (!object(message.interactions)) errors.push('interactions must be a mapping') else for (const [id, source] of Object.entries(message.interactions) as [string, any][]) { if (!object(source)) { errors.push(`${id} interaction must be an object`); continue } - knownKeys(source, ['method', 'title', 'description', 'target', 'anchorId', 'versions', 'errors', 'examples', 'request', 'response', 'publication'], id) - text(source, ['method', 'title', 'description', 'target', 'anchorId'], id) - if (!object(source.versions) || !Object.keys(source.versions).length) { errors.push(`${id} versions must be a nonempty mapping`); continue } + knownKeys(source, ['title', 'description', 'target', 'messageVersion', 'errors', 'examples', 'request', 'response', 'publication'], id) + text(source, ['title', 'description', 'target'], id) validateExchangeShape(source, id, true) - for (const [revision, exchange] of Object.entries(source.versions) as [string, any][]) { - const label = `${id}/${revision}` - if (!/^[1-9]\d*$/.test(revision) || !Number.isSafeInteger(Number(revision))) errors.push(`${label} interaction revision must be a positive safe integer`) - if (!object(exchange)) { errors.push(`${label} exchange must be an object`); continue } - knownKeys(exchange, ['messageVersion', 'anchorId', 'title', 'description', 'target', 'request', 'response', 'publication', 'errors', 'examples'], label) - text(exchange, ['title', 'description', 'target', 'anchorId'], label) - validateExchangeShape(exchange, label, true) - const selected = exchange.messageVersion - if (selected !== undefined && (!Number.isInteger(selected) || !Object.prototype.hasOwnProperty.call(versions, selected))) errors.push(`${label} references unknown message version ${selected}`) - const merged = { ...source, ...exchange } - if (!['request', 'response', 'publication'].some(role => object(merged[role]))) errors.push(`${label} needs at least one request, response or publication message`) - for (const role of ['request', 'response', 'publication']) { - const context = merged[role] - if (role === 'request' && source.method && context?.headers?.[5]?.value !== undefined) { - const method = Object.entries(protocol.header?.[5]?.values || {}).find(([, value]: [string, any]) => value.name === source.method) - if (method && context.headers[5].value !== Number(method[0])) errors.push(`${label} request header 5 disagrees with its method`) - } - if (!object(context) || context.messageId !== undefined && context.messageId !== messageId) continue - const wire = ['ignored', 'omitted'].includes(context.headers?.[22]?.presence) ? undefined : wireVersion({ [role]: context }) - if (wire !== undefined && selected === undefined) errors.push(`${label} needs an explicit messageVersion`) - else if (wire !== undefined && wire !== selected) errors.push(`${label} ${role} header 22 disagrees with its message version`) - for (const [fieldId, usage] of Object.entries(context.fields || {}) as [string, any][]) { - if (['omitted', 'ignored'].includes(usage?.presence)) continue - const applicable = message.data?.[fieldId]?.versions - if (Array.isArray(applicable) && selected === undefined) errors.push(`${label} needs an explicit messageVersion for field ${fieldId}`) - else if (Array.isArray(applicable) && !applicable.includes(selected)) errors.push(`${label} ${role} uses field ${fieldId} outside its versions`) - } + const selected = source.messageVersion + if (selected !== undefined && (!Number.isInteger(selected) || !Object.prototype.hasOwnProperty.call(versions, selected))) errors.push(`${id} references unknown message version ${selected}`) + if (!['request', 'response', 'publication'].some(role => object(source[role]))) errors.push(`${id} needs at least one request, response or publication message`) + if (source.request !== undefined && !interactionMethod(source, protocol)) errors.push(`${id} request needs a known Method value in header 5`) + for (const role of ['request', 'response', 'publication']) { + const context = source[role] + if (!object(context) || context.messageId !== undefined && context.messageId !== messageId) continue + const wire = ['ignored', 'omitted'].includes(context.headers?.[22]?.presence) ? undefined : wireVersion({ [role]: context }) + if (wire !== undefined && selected === undefined) errors.push(`${id} needs an explicit messageVersion`) + else if (wire !== undefined && wire !== selected) errors.push(`${id} ${role} header 22 disagrees with its message version`) + for (const [fieldId, usage] of Object.entries(context.fields || {}) as [string, any][]) { + if (['omitted', 'ignored'].includes(usage?.presence)) continue + const applicable = message.data?.[fieldId]?.versions + if (Array.isArray(applicable) && selected === undefined) errors.push(`${id} needs an explicit messageVersion for field ${fieldId}`) + else if (Array.isArray(applicable) && !applicable.includes(selected)) errors.push(`${id} ${role} uses field ${fieldId} outside its versions`) } } } @@ -437,7 +448,7 @@ function validateInlineDocumentation(message: any, messageId: number, protocol: } // SDK maps remain unchanged until their consumers migrate. Compare only // method membership: their request/response maps are not usage contexts. - const methods = getDocumentationMethods(message) + const methods = getDocumentationMethods(message, protocol) const sdkMethods = Object.keys(message.methods || {}) for (const method of methods) if (!sdkMethods.includes(method)) errors.push(`interaction method ${method} is missing from the SDK methods map`) for (const method of sdkMethods) if (!methods.includes(method)) errors.push(`SDK method ${method} has no interaction`) @@ -477,7 +488,7 @@ export function validateMessageDocumentation(protocol: any, messageId: number): const prefix = `Message ${messageId} documentation` const authoringErrors = validateInlineDocumentation(message, messageId, protocol) if (authoringErrors.length) return authoringErrors.map(error => `${prefix}: ${error}`) - const docs = getMessageDocumentation(message)! + const docs = getMessageDocumentation(message, protocol)! const errors: string[] = [] const fail = (text: string) => errors.push(`${prefix}: ${text}`) const identifier = /^[a-z][a-z0-9-]*$/ @@ -508,12 +519,6 @@ export function validateMessageDocumentation(protocol: any, messageId: number): validateAnchors(docs.operations, 'operation') if (docs.notes) { validateIds(docs.notes, 'note') - for (const note of docs.notes) { - if (!note || typeof note !== 'object') continue - if (note.placement !== undefined && !['overview', 'reference'].includes(note.placement)) { - fail(`${note.id} has invalid note placement`) - } - } } const validateContext = (context: DocumentationContext | undefined, label: string) => { @@ -588,3 +593,9 @@ export function validateMessageDocumentation(protocol: any, messageId: number): } return errors } + +/** Validate inline interactions before publishing the specification and its reference pages. */ +export function validateProtocolInteractions(protocol: any): string[] { + const errors = protocol.interactions === undefined ? [] : ['Interactions belong inside their message definitions'] + return errors.concat(Object.keys(protocol.messages || {}).flatMap(id => validateMessageDocumentation(protocol, Number(id)))) +} diff --git a/utils/ProtocolInteractions.ts b/utils/ProtocolInteractions.ts deleted file mode 100644 index 59d98b878..000000000 --- a/utils/ProtocolInteractions.ts +++ /dev/null @@ -1,45 +0,0 @@ -import { - getMessageDocumentation, - getOperationVariant, - validateMessageDocumentation, - type DocumentationOperation, - type DocumentationVariant, -} from './MessageDocumentation' - -export type ResolvedProtocolInteraction = DocumentationVariant & { - interactionId: string - interactionVersion: number - messageId: number - operationId: string - method?: string -} - -/** Validate the same inline definitions used by the documentation renderer. */ -export function validateProtocolInteractions(protocol: any): string[] { - const errors = protocol.interactions === undefined ? [] : ['Interactions belong inside their message definitions'] - return errors.concat(Object.keys(protocol.messages || {}).flatMap(id => validateMessageDocumentation(protocol, Number(id)))) -} - -/** Select an interaction revision explicitly; it never supplies or infers a wire selector. */ -export function resolveProtocolInteraction(protocol: any, messageId: number, id: string, revision: number): ResolvedProtocolInteraction { - const message = protocol.messages?.[messageId] - if (!message) throw new Error(`Unknown message ${messageId}`) - const errors = validateMessageDocumentation(protocol, messageId) - if (errors.length) throw new Error(errors.join('\n')) - const authored = Object.prototype.hasOwnProperty.call(message.interactions || {}, id) ? message.interactions[id] : undefined - if (!authored) throw new Error(`Message ${messageId}: unknown interaction ${id}`) - if (!Number.isSafeInteger(revision) || revision < 1 || !Object.prototype.hasOwnProperty.call(authored.versions, revision)) { - throw new Error(`Interaction ${id}: unknown revision ${revision}`) - } - const docs = getMessageDocumentation(message)! - const operation = docs.operations.find(item => item.id === id)! - const { variants, ...view } = getOperationVariant(operation, String(revision)) as DocumentationOperation - return { - ...view, - interactionId: id, - interactionVersion: revision, - messageId, - operationId: operation.id, - target: view.target ?? docs.target, - } -} diff --git a/yaml-data.data.ts b/yaml-data.data.ts index b6fca3ce3..d19165003 100644 --- a/yaml-data.data.ts +++ b/yaml-data.data.ts @@ -1,6 +1,6 @@ import fs from 'node:fs' import jsyaml from 'js-yaml' -import { validateProtocolInteractions } from './utils/ProtocolInteractions' +import { validateProtocolInteractions } from './utils/MessageDocumentation' export interface YamlDataInterface { [key: string]: any From 1e1d47601d3ece3d3f2a491abda66f23e6a39071 Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 11:44:48 +0000 Subject: [PATCH 18/24] Inherit shared V3 field and error descriptions --- components/Protocol/StructuredMessagePage.vue | 14 +- devices/api/protocol/responses.md | 31 +++- public/files/protocol-v3.yaml | 108 +++-------- utils/MessageDocumentation.test.ts | 169 +++++++++++++++++- utils/MessageDocumentation.ts | 37 +++- 5 files changed, 261 insertions(+), 98 deletions(-) diff --git a/components/Protocol/StructuredMessagePage.vue b/components/Protocol/StructuredMessagePage.vue index 0fd6139a6..d98b868d9 100644 --- a/components/Protocol/StructuredMessagePage.vue +++ b/components/Protocol/StructuredMessagePage.vue @@ -23,6 +23,7 @@ import { getDocumentationFormat, getMessageDocumentation, getOperationVariant, + resolveDocumentationErrors, resolveDocumentationFields, type DocumentationOperation, } from '../../utils/MessageDocumentation' @@ -105,7 +106,7 @@ const panels = computed(() => (documentation.value?.operations || []).flatMap(it ...context, examplesAnchor: `${anchor}${context.role === (contexts.find(item => item.examples.length)?.role || contexts[0]?.role) ? '' : `-${context.role}`}-examples`, })), - errors: (view.errors || []).map(error => ({ ...error, name: props.yamlData.header?.[4]?.values?.[error.code]?.name })), + errors: resolveDocumentationErrors(props.yamlData, view.errors), } }) })) @@ -327,8 +328,14 @@ onBeforeUnmount(() => {

-

Methods {{ documentation.methods.join(', ') }}

+

Documented Method (5) values {{ documentation.methods.join(', ') }}

Applies to {{ documentation.target }}

+

+ Shared optional header · Message ID (1) + can identify a request, response or publication. A response's own ID is separate from + Response To (3). + Message ID and reply rules apply unless an interaction states an exception. +

@@ -414,6 +421,7 @@ onBeforeUnmount(() => { {{ context.title }}

{{ context.subtitle }}

+

Shared optional Message ID and reply rules

Correlation, status and acknowledgment rules

{{ group.title }} @@ -449,7 +457,7 @@ onBeforeUnmount(() => {
Unsuccessful replies -

Operation-specific causes. Codes are values of Status header 4, not payload fields.

+

Applicable errors and operation-specific causes. Codes are values of Status header 4, not payload fields.

{{ error.code }} {{ error.name }}
diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 551adddc3..1a94dd7cc 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -8,6 +8,16 @@ A request and its reply are separate frames, with separate headers and data fiel Use the operation's required request headers. An omitted [Method (header 5)](./headers#5-method) is not a universal GET default; GPS Control and Message Box require an explicit method. +## Message IDs + +[Message ID (header 1)](./headers#1-message-id) is a shared optional header for requests, responses and publications. Individual implementations, transports or client services can impose additional requirements. Send helpers may add an ID automatically; that is not a requirement to serialize one in every frame. + +- On a request, use a nonzero ID when acknowledgment or reply correlation is needed. The operation's reply rules still determine what is sent. +- On a response, an optional Message ID identifies the response itself. It is independent of [Response to (header 3)](./headers#3-response-to), which identifies the original request. Correlate using Response to, not the response's own ID. A response can contain both, either, or neither as permitted by its send path. +- Publications can also have their own IDs. An ID does not by itself make a publication a reply to a request. + +The interaction YAML need not repeat an empty `1: {}` in every header list. It inherits this shared optional-ID convention; a local header-1 entry describes an actual requirement or exception. Omitting that entry is not an assertion that the wire frame lacks an ID. Separate ID-less interactions are unnecessary when only the shared acknowledgment or correlation rules differ. + ## Correlating a reply Include a nonzero [Message ID (header 1)](./headers#1-message-id) when you need to match replies to requests. A correlated reply carries that ID in [Response to (header 3)](./headers#3-response-to), not as its own Message ID. @@ -33,6 +43,8 @@ An ACK can identify the original request through Response to and/or its **ACK Ty Whether an ACK is sent depends on the operation and target. A missing or zero Message ID does not guarantee silence: typed replies and error replies may still be sent. Follow the message page's documented behavior. +Do not turn success-ACK suppression into a universal no-ID rule. OPEN/CLOSE handling and transport-specific send paths can have different acknowledgment behavior. + The following operation-specific conditions belong to this shared response reference, linked from each operation's response section: - [GSM Control SET](../messages/31-gsm-control#message-31-operation-control-flight-mode) (including network search), [SIM settings SET](../messages/33-sim-settings#message-33-operation-select-sim1) (both SIM choices), and [Device Status SUBSCRIBE/UNSUBSCRIBE](../messages/34-device-status#message-34-operation-subscribe) send a success MT5 ACK only when the request includes a nonzero Message ID. They send no success ACK for an omitted or zero ID. @@ -92,6 +104,19 @@ messages: Stages inherit the containing message type unless they specify `messageId`, so the response above uses MT5. Field names, types, units, enums and descriptions come from that message's `data` and the shared `header` definitions. The uint8 type already gives header 22 its one-byte width; variable-size payload bounds such as `maxBytes: 1024` remain meaningful. Keep explicit selector behavior: legacy Message Box GET/SUBSCRIBE accepts omitted, zero or malformed-width selectors as version 1, and legacy responses omit header 22. +Payload descriptions inherit in this order: the canonical `data[fieldId].description`, an optional `versions[messageVersion].fields[fieldId].description`, then an explicit interaction-stage description. For example, a wire version can describe its cached-payload meaning once: + +```yaml +versions: + 2: + label: "2026-10" + fields: + 129: + description: Complete cached payload. Empty payload data is omitted when returned or published. +``` + +Both the version's field reference and its interactions inherit this text. An interaction can still override it when SET clears the cache or an upload carries independent bytes. Version overrides change descriptions only: they do not change field types, presence, limits, or participation. They apply only to that message's fields, never to a different response type such as MT5. Unversioned interactions use the canonical description. Migrated interactions do not inherit descriptions from the legacy SDK method maps. + A publication-only interaction needs no method or request. This shortened example describes the existing tracking upload: ```yaml @@ -109,10 +134,14 @@ messages: description: Independent Transmit Now upload data. ``` -Request mappings list expected inputs, optional by default; mark required inputs explicitly. Leave unrelated inputs out, and keep important ignored or rejected input behavior in concise descriptions. An unlisted input is not a statement that firmware ignores, rejects or accepts it. Response and publication mappings can still mark omitted fields where wire-format or correlation differences matter. Write field descriptions only where the meaning differs. +Request mappings list expected inputs, optional by default; mark required inputs explicitly. Message ID follows the shared rule above and does not need a repeated empty entry. Leave unrelated inputs out, and keep important ignored or rejected input behavior in concise descriptions. An unlisted input is not a statement that firmware ignores, rejects or accepts it. Response and publication mappings can still mark omitted fields where wire-format or correlation differences matter. Write field descriptions only where the meaning differs. + +An error entry needs only its status `code` to inherit the name and general description from header 4. Add `description` only for an operation-specific cause, without repeating the status name. For example, `{code: 7}` inherits Not Supported; `{code: 4, description: "A decoded Message Version value above 2."}` explains a particular Invalid Parameter case. These entries describe applicable errors, not a list of every status a transport might report. Documentation method lists are derived from request header 5, with validation requiring a known selector for each request. An absent selector is not inferred as GET. Existing method-keyed SDK request/response maps remain unchanged, with validation requiring their method names to match the interactions for migrated messages. Multiple interactions may use one method, and publication-only interactions add none. Removing or regenerating the SDK maps is a separate migration. +GET, SET and SUBSCRIBE are values of Method header 5, not separate wire structures. An explicit selector in a documented interaction does not establish that every message requires it: LED controls, for example, can default to SET when Method is omitted. A message- or operation-specific header limit belongs with that use, rather than changing the shared header definition for all messages. + An interaction describes an exchange, not arbitrary ordered sequences of requests. Applicability can be narrowed with `target` without making fields required. Its stages remain subject to the correlation, suppression and target rules above; defining a response does not guarantee it is sent. ## Subscription replies and later updates diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index 313a149f1..ac09ef8b7 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -32,8 +32,10 @@ header: name: Message ID id: id description: | - ID identifying the message. + Optional ID identifying this message, including when it is a response or publication. Can be used by a receiver to ACK, respond to, deduplicate, resend or otherwise track messages. + A response's own Message ID is independent of Response to (header 3), which identifies the original request. + A nonzero request ID enables correlation and may be needed for a success acknowledgment; omission does not guarantee no reply. Some clients and services may require or desire an incrementing message ID for each message sent, acting as a sequence number. type: uint32 2: @@ -1263,7 +1265,6 @@ messages: title: Read GSM state request: headers: - 1: {} 5: { presence: required, value: 2 } response: description: Successful GET returns GSM state directly. @@ -1284,7 +1285,6 @@ messages: Omit Start Search (field 5), which takes priority over flight-mode controls when present. GSM Active and Request Control (fields 3 and 4) are ignored by SET. headers: - 1: {} 5: { presence: required, value: 1 } 7: {} fields: @@ -1309,7 +1309,6 @@ messages: Start Search takes priority even when its value is 0. Fields 1 to 4 and header Duration (7) are ignored when Start Search is present. headers: - 1: {} 5: { presence: required, value: 1 } fields: 5: { presence: required } @@ -1383,7 +1382,6 @@ messages: title: Read SIM settings request: headers: - 1: {} 5: { presence: required, value: 2 } response: description: >- @@ -1405,7 +1403,6 @@ messages: request: description: SIM2 APN and credentials are ignored when selecting SIM1. headers: - 1: {} 5: { presence: required, value: 1 } fields: 1: { presence: required, value: 0 } @@ -1420,7 +1417,6 @@ messages: title: Select SIM2 and configure its network credentials request: headers: - 1: {} 5: { presence: required, value: 1 } fields: 1: { presence: required, value: 1 } @@ -1580,7 +1576,6 @@ messages: request: description: No payload fields are required. Method must be included; this message does not default to GET. headers: - 1: {} 5: { presence: required, value: 2 } response: title: Device status (MT34) @@ -1625,7 +1620,6 @@ messages: description: No payload fields are required. Omit Subscription ID (header 17), or use 0, for the default subscription documented here. Updates are subject to the selected interval and message level. headers: - 1: {} 5: { presence: required, value: 3 } 6: description: Publication interval in milliseconds. Omitted or 0 allows updates as new status data @@ -1683,7 +1677,6 @@ messages: description: No payload fields are required. Omit Subscription ID; this operation removes the default subscription only. headers: - 1: {} 5: { presence: required, value: 5 } response: messageId: 5 @@ -1736,7 +1729,6 @@ messages: request: description: No payload fields are required. Include Method GET to request the device identifiers. headers: - 1: {} 5: { presence: required, value: 2 } response: title: Device IDs (MT35) @@ -2007,13 +1999,13 @@ messages: 1: name: GPS is on id: gpsOn - description: Status of the GPS, is it on? + description: Whether the GPS service is on. type: bool readonly: true 2: name: Corrections Enabled id: correctionsOn - description: Request and apply correction data to the GPS, such as RTK. + description: Whether GPS correction data is enabled. type: uint8 values: 0: @@ -2060,10 +2052,8 @@ messages: are needed. errors: - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' request: headers: - 1: {} 5: { presence: required, value: 2 } response: title: GPS state (MT39) @@ -2075,10 +2065,8 @@ messages: fields: 1: presence: required - description: Whether the GPS service is on. 2: presence: required - description: Whether correction data is enabled. 3: presence: omitted description: Start mode is a SET input, not returned state. @@ -2087,15 +2075,13 @@ messages: description: Enable correction data and/or restart the GPS in the requested boot mode. errors: - code: 4 - description: 'Invalid Parameter: a read-only GPS status field or an unsupported start mode was supplied.' + description: 'A read-only GPS status field or an unsupported start mode was supplied.' - code: 5 - description: 'Invalid State: the correction service cannot be enabled in the current device state.' + description: 'The correction service cannot be enabled in the current device state.' - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' request: description: Sending the read-only GPS status (field 1) in SET is rejected with Invalid Parameter (4). headers: - 1: {} 5: { presence: required, value: 1 } fields: 2: @@ -3345,12 +3331,22 @@ messages: description: >- Complete payload and CRC-16 format. GET and SUBSCRIBE explicitly select wire Message Version 2 with header 22; omitting it selects the legacy format. SET requires 2. + fields: + 129: + description: >- + Complete cached payload in an extended-length field with a uint16 little-endian length + prefix. Empty payload data is omitted when returned or published. 1: label: "2025-10" description: >- Earlier chunked payload and additive-checksum format, retained for existing integrations. GET and SUBSCRIBE use this format when header 22 is omitted or set to 1. No legacy SET is supported. + Concatenate present payload chunks (fields 10-14) in field-ID order; each holds up to + 255 bytes. Empty payload data is omitted. legacy: true + fields: + 1: + description: Additive checksum of the cached payload, calculated as the sum of its bytes modulo 65536. group: info header: - 5 @@ -3359,51 +3355,46 @@ messages: 1: name: Legacy Checksum id: legacyChecksum - description: Legacy additive checksum (sum of payload bytes modulo 65536), used in version 1 responses with the legacy chunk fields. Absent from version 2 responses. Optional and ignored in SET. + description: Checksum of the cached payload. type: uint16 readonly: true versions: [1] 2: name: CRC id: crc - description: CRC-16/XMODEM of the cached payload (polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000), separate from the outer message-frame CRC. Returned in version 2 responses and tracking-session messages, including an empty cache as zero (0x0000). Optional and ignored in SET; the device calculates it from field 129. One- or two-byte little-endian encoding may omit a high zero byte. Implemented only on Viper devices. + description: CRC-16/XMODEM of the cached payload (polynomial 0x1021, initial value 0x0000, no input or output reflection, final XOR 0x0000), separate from the outer message-frame CRC. An empty cache has CRC zero (0x0000). One- or two-byte little-endian encoding may omit a high zero byte. type: uint16 readonly: true versions: [2] 10: name: Legacy Payload Chunk 1 id: legacyChunk1 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 11: name: Legacy Payload Chunk 2 id: legacyChunk2 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 12: name: Legacy Payload Chunk 3 id: legacyChunk3 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 13: name: Legacy Payload Chunk 4 id: legacyChunk4 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 14: name: Legacy Payload Chunk 5 id: legacyChunk5 - description: Message Version 1 GET response payload chunk; contains up to 255 bytes. type: bytes versions: [1] 129: name: Full Payload id: fullPayload - description: Complete message-box bytes in SET requests, GET responses, and subscription updates (up to 1024 bytes). SET must include this field; an explicit zero-length value clears the cache. Uses an extended-length field with a uint16 little-endian length prefix. Tracking-session uploads may use this field for independent Transmit Now data instead. + description: Payload bytes carried in an extended-length field with a uint16 little-endian length prefix. type: bytes versions: [2] methods: @@ -3422,13 +3413,11 @@ messages: Select the complete extended payload and its CRC-16/XMODEM. errors: &messageBoxReadErrors - code: 4 - description: 'Invalid Parameter: a decoded Message Version value above 2.' + description: 'A decoded Message Version value above 2.' - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' messageVersion: 2 request: headers: - 1: {} 5: { presence: required, value: 2 } 22: presence: required @@ -3446,15 +3435,10 @@ messages: fields: 1: presence: omitted - description: The legacy additive checksum is absent from version 2 responses. 2: presence: required - description: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- - or two-byte little-endian encoding may omit a high zero byte. 129: maxBytes: 1024 - description: Complete cached payload in an extended-length field with a uint16 little-endian length - prefix. Empty payload data is omitted. read-message-box-v1: title: Read the cached message (legacy v1) description: >- @@ -3467,7 +3451,6 @@ messages: messageVersion: 1 request: headers: - 1: {} 5: { presence: required, value: 2 } 22: description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an @@ -3488,33 +3471,20 @@ messages: fields: 1: presence: required - description: 'Additive checksum: sum of all cached payload bytes modulo 65536.' 2: presence: omitted - description: The CRC field belongs to version 2. 10: maxBytes: 255 - description: Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is - omitted. 11: maxBytes: 255 - description: Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is - omitted. 12: maxBytes: 255 - description: Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is - omitted. 13: maxBytes: 255 - description: Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is - omitted. 14: maxBytes: 255 - description: Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload data is - omitted. 129: presence: omitted - description: Version 1 retains the legacy wire layout; it does not include the extended full-payload field. replace-message-box: title: Replace or clear the cached message description: Every accepted SET updates the cache, writes it to persistent storage when enabled, and @@ -3526,7 +3496,6 @@ messages: outer message-frame CRC protects the SET request itself. Optional supplied checksum fields 1 and 2 are ignored. headers: - 1: {} 5: { presence: required, value: 1 } 22: presence: required @@ -3552,12 +3521,11 @@ messages: in this ACK. errors: - code: 2 - description: 'Missing Parameter: field 129 is absent.' + description: 'Field 129 is absent.' - code: 4 - description: 'Invalid Parameter: Message Version is missing, malformed-width, or any value other than 2; + description: 'Message Version is missing, malformed-width, or any value other than 2; or field 129 exceeds 1024 bytes.' - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' subscribe-message-box: title: Subscribe to cached-message updates description: >- @@ -3584,14 +3552,12 @@ messages: in this ACK. errors: &messageBoxSubscribeErrors - code: 4 - description: 'Invalid Parameter: a decoded Message Version value above 2; existing selection and + description: 'A decoded Message Version value above 2; existing selection and subscription are unchanged.' - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' messageVersion: 2 request: headers: - 1: {} 5: { presence: required, value: 3 } 6: description: Optional publication interval in milliseconds. If omitted, updates are sent when new data @@ -3621,15 +3587,10 @@ messages: fields: 1: presence: omitted - description: The legacy additive checksum is absent from version 2 responses. 2: presence: required - description: Device-calculated CRC-16/XMODEM of the cached payload, including 0 for an empty cache. One- - or two-byte little-endian encoding may omit a high zero byte. 129: maxBytes: 1024 - description: Complete cached payload in an extended-length field with a uint16 little-endian length - prefix. Empty payload data is omitted. subscribe-message-box-v1: title: Subscribe to cached-message updates (legacy v1) description: >- @@ -3645,7 +3606,6 @@ messages: messageVersion: 1 request: headers: - 1: {} 5: { presence: required, value: 3 } 6: description: Optional publication interval in milliseconds. If omitted, updates are sent when new data @@ -3677,43 +3637,28 @@ messages: fields: 1: presence: required - description: 'Additive checksum: sum of all cached payload bytes modulo 65536.' 2: presence: omitted - description: The CRC field belongs to version 2. 10: maxBytes: 255 - description: Legacy payload chunk 1; concatenate present chunks in field-ID order. Empty payload data is - omitted. 11: maxBytes: 255 - description: Legacy payload chunk 2; concatenate present chunks in field-ID order. Empty payload data is - omitted. 12: maxBytes: 255 - description: Legacy payload chunk 3; concatenate present chunks in field-ID order. Empty payload data is - omitted. 13: maxBytes: 255 - description: Legacy payload chunk 4; concatenate present chunks in field-ID order. Empty payload data is - omitted. 14: maxBytes: 255 - description: Legacy payload chunk 5; concatenate present chunks in field-ID order. Empty payload data is - omitted. 129: presence: omitted - description: Version 1 retains the legacy wire layout; it does not include the extended full-payload field. stop-message-box-subscription: title: Stop a subscription description: Remove the addressed subscription. Message Version (header 22) is ignored; UNSUBSCRIBE does not select or reset the publication format, and neither does subscription expiry. errors: - code: 7 - description: 'Not Supported: the product or firmware does not support this operation.' request: headers: - 1: {} 5: { presence: required, value: 5 } 17: description: Use the Subscription ID to remove, or omit it for the default subscription (0). @@ -3780,9 +3725,8 @@ messages: - id: checksum-scope title: Payload CRC and frame CRC are different description: >- - The device calculates and stores CRC-16/XMODEM of the cached payload: polynomial 0x1021, - initial value 0x0000, no input or output reflection, final XOR 0x0000. The outer - message-frame CRC protects the complete frame. The 16-bit payload CRC can collide for + Field 2 describes the cached payload; the outer message-frame CRC protects the complete + frame. The 16-bit payload CRC can collide for different payloads; an accepted SET still applies changed bytes even when their CRC matches the previous CRC. 61: diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 4d16a1bcc..7952d53fb 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -15,6 +15,7 @@ import { getDocumentationFormat, documentationTargetOverride, resolveDocumentationFields, + resolveDocumentationErrors, validateMessageDocumentation, validateProtocolInteractions, type DocumentationOperation, @@ -195,7 +196,7 @@ describe('optional message documentation', () => { expect(resolveDocumentationFields(protocol, protocol.messages[58], usage, 'headers').map(field => field.id)).toEqual([4, 5, 1, 17, 22]) expect(usage).toEqual(before) const set = getMessageDocumentation(protocol.messages[58], protocol)!.operations.find((operation: DocumentationOperation) => operation.method === 'SET') - expect(resolveDocumentationFields(protocol, protocol.messages[58], set!.request!.headers, 'headers').map(field => field.id)).toEqual([5, 22, 1]) + expect(resolveDocumentationFields(protocol, protocol.messages[58], set!.request!.headers, 'headers').map(field => field.id).filter(id => id !== 1)).toEqual([5, 22]) expect(resolveDocumentationFields(protocol, protocol.messages[58], set!.request!.fields, 'fields')[0].id).toBe(129) }) @@ -276,7 +277,7 @@ describe('wire-version authoring', () => { expect(docs.formats!.map(format => format.label)).toEqual(['2026-10', '2025-10']) expect(docs.formats![1].anchorId).toBe('legacy') expect(docs.formats![0].anchorId).toBe('current') - expect(docs.formats![0].fields).toEqual({ 2: {}, 129: {} }) + expect(docs.formats![0].fields).toEqual({ 2: {}, 129: message.versions[2].fields[129] }) for (const version of Object.values(message.versions) as any[]) { expect(version.id).toBeUndefined() expect(version.messageVersion).toBeUndefined() @@ -328,12 +329,13 @@ describe('wire-version authoring', () => { expect(validateMessageDocumentation(sample, 58).join('\n')).toContain('fields 2 must be an object') }) - it('inherits existing method field descriptions before base descriptions', () => { + it('does not inherit hidden SDK method descriptions in migrated interactions', () => { const message = clone(protocol.messages[39]) delete authoredInteraction(message, 'SET').request.fields[2].description const docs = getMessageDocumentation(message, protocol)! const set = docs.operations.find(operation => operation.method === 'SET')! - expect(set.request!.fields![2].description).toBe(message.methods.SET.request[2].description) + expect(set.request!.fields![2].description).toBeUndefined() + expect(resolveDocumentationFields(protocol, message, set.request!.fields, 'fields').find(field => field.id === 2)?.description).toBe(message.data[2].description || '') expect(authoredInteraction(message, 'SET').request.fields[2].description).toBeUndefined() }) @@ -563,7 +565,13 @@ describe('canonical inline interactions', () => { it('validates both published authoring examples against the existing wire definitions', () => { const guide = readFileSync(resolve(__dirname, '../devices/api/protocol/responses.md'), 'utf8') - const examples = [...guide.matchAll(/```yaml\n([\s\S]*?)```/g)].map(match => yaml.load(match[1]).messages[58]) + const snippets = [...guide.matchAll(/```yaml\n([\s\S]*?)```/g)].map(match => yaml.load(match[1])) + const examples = snippets.filter(snippet => snippet.messages).map(snippet => snippet.messages[58]) + const versionExample = snippets.find(snippet => snippet.versions) + expect(versionExample).toBeDefined() + const versionSample = clone(protocol) + versionSample.messages[58].versions[2] = versionExample.versions[2] + expect(validateMessageDocumentation(versionSample, 58)).toEqual([]) expect(examples).toHaveLength(2) for (const example of examples) { const sample = clone(protocol) @@ -653,7 +661,7 @@ describe('canonical inline interactions', () => { const flight = interactionView(31, 'control-flight-mode') const search = interactionView(31, 'start-search') expect(flight.request?.description).toContain('fields 3 and 4) are ignored by SET') - expect(Object.keys(search.request!.headers!)).toEqual(['1', '5']) + expect(Object.keys(search.request!.headers!).filter(id => id !== '1')).toEqual(['5']) expect(Object.keys(search.request!.fields!)).toEqual(['5']) expect(search.request?.description).toContain('even when its value is 0') expect(search.request?.description).toContain('Fields 1 to 4 and header Duration (7) are ignored') @@ -676,7 +684,7 @@ describe('canonical inline interactions', () => { expect(set.request?.description).toContain('field 1) in SET is rejected with Invalid Parameter (4)') expect(set.request?.fields?.[2].description).toContain('sets API-enabled corrections to disabled') const stop = interactionView(58, 'stop-message-box-subscription') - expect(Object.keys(stop.request!.headers!)).toEqual(['1', '5', '17']) + expect(Object.keys(stop.request!.headers!).filter(id => id !== '1')).toEqual(['5', '17']) expect(stop.description).toContain('Message Version (header 22) is ignored') expect(stop.description).toContain('does not select or reset the publication format') expect(stop.response?.messageId).toBe(5) @@ -728,3 +736,150 @@ describe('canonical inline interactions', () => { expect(validateMessageDocumentation(sample, 58).join('\n')).toContain('note has unknown property placement') }) }) + +describe('canonical, version and interaction descriptions', () => { + const fixture = () => { + const message = { + id: 'sample', description: 'Sample', methods: { GET: { response: { 1: { description: 'Hidden SDK prose' } } } }, + data: { + 1: { name: 'First', type: 'uint8', description: 'Canonical' }, + 2: { name: 'Second', type: 'uint8', description: 'Second canonical', versions: [2] }, + }, + versions: { 1: { label: 'Older' }, 2: { label: 'Current', fields: { 1: { description: 'Version two' }, 2: { description: 'Second version two' } } } }, + interactions: { read: { messageVersion: 2, request: { headers: { 5: { value: 2 } } }, response: { fields: { 1: {} } } } }, + } + return { ...clone(protocol), messages: { ...clone(protocol.messages), 99: message } } as any + } + const description = (sample: any, role = 'response') => { + const message = sample.messages[99] + const view = getMessageDocumentation(message, sample)!.operations[0] + const context = (view as any)[role] + return resolveDocumentationFields(sample, context.messageId === undefined ? message : sample.messages[context.messageId], context.fields, 'fields')[0].description + } + + it('applies descriptions in order without adding participating fields or mutating source objects', () => { + const sample = fixture() + const before = clone(sample) + const message = sample.messages[99] + expect(validateMessageDocumentation(sample, 99)).toEqual([]) + expect(description(sample)).toBe('Version two') + const docs = getMessageDocumentation(message, sample)! + expect(Object.keys(docs.operations[0].response!.fields!)).toEqual(['1']) + expect(resolveDocumentationFields(sample, message, docs.formats![0].fields, 'fields').map(field => field.description)).toEqual(['Version two', 'Second version two']) + expect(sample).toEqual(before) + message.interactions.read.response.fields[1].description = 'Context' + expect(description(sample)).toBe('Context') + message.interactions.read.response.fields[1].description = '' + expect(description(sample)).toBe('') + delete message.interactions.read.response.fields[1].description + delete message.interactions.read.messageVersion + expect(description(sample)).toBe('Canonical') + expect(getMessageDocumentation(message, sample)!.operations[0].messageVersion).toBeUndefined() + }) + + it('uses version prose for explicitly same-message stages but not cross-message responses', () => { + const sample = fixture() + sample.messages[99].interactions.read.response.messageId = 99 + expect(description(sample)).toBe('Version two') + sample.messages[99].interactions.read.response.messageId = 5 + expect(description(sample)).toBe(sample.messages[5].data[1].description || '') + sample.messages[99].interactions.read.response.messageId = 39 + expect(description(sample)).toBe(sample.messages[39].data[1].description || '') + }) + + it('retains legacy method prose only when interactions have not migrated', () => { + const sample = fixture() + const message = sample.messages[99] + delete message.interactions + message.methods.GET.exchange = { response: { fields: { 1: {} } } } + expect(description(sample)).toBe('Hidden SDK prose') + }) + + it.each([ + ['unknown field', (m: any) => { m.versions[2].fields[999] = { description: 'Unknown' } }], + ['non-numeric field', (m: any) => { m.versions[2].fields.first = { description: 'Unknown' } }], + ['non-object fields', (m: any) => { m.versions[2].fields = [] }], + ['non-object override', (m: any) => { m.versions[2].fields[1] = 'Prose' }], + ['non-string description', (m: any) => { m.versions[2].fields[1].description = 2 }], + ['missing description', (m: any) => { m.versions[2].fields[1] = {} }], + ['type override', (m: any) => { m.versions[2].fields[1].type = 'uint32' }], + ['presence override', (m: any) => { m.versions[2].fields[1].presence = 'required' }], + ['bounds override', (m: any) => { m.versions[2].fields[1].maxBytes = 5 }], + ['excluded version', (m: any) => { m.versions[1].fields = { 2: { description: 'Unavailable' } } }], + ['non-numeric version', (m: any) => { m.versions.latest = m.versions[2] }], + ])('rejects %s metadata', (_label, change) => { + const sample = fixture() + change(sample.messages[99]) + expect(validateMessageDocumentation(sample, 99).length).toBeGreaterThan(0) + }) + + it('keeps ID-bearing captures and wire definitions when a request omits redundant Message ID metadata', () => { + const sample = clone(protocol) + const message = sample.messages[35] + const before = clone(message) + delete message.interactions['read-device-ids'].request.headers[1] + const docs = getMessageDocumentation(message, sample)! + expect(docs.operations).toHaveLength(1) + expect(docs.operations[0].request!.headers![1]).toBeUndefined() + expect(docs.operations[0].examples).toEqual(before.interactions['read-device-ids'].examples) + const frames = docs.operations[0].examples![0].frames.map(frame => parseRawMessage(frame.bytes.split(' ').map(Number))) + expect(frames[0].header[1]?.length).toBeGreaterThan(0) + expect(frames[1].header[3]).toEqual(frames[0].header[1]) + expect(message.data).toEqual(before.data) + expect(message.header).toEqual(before.header) + expect(message.methods).toEqual(before.methods) + expect(validateMessageDocumentation(sample, 35)).toEqual([]) + }) +}) + +describe('shared descriptions in the published specification', () => { + it('uses shared ID guidance and canonical GPS/error prose without redundant interaction entries', () => { + for (const message of Object.values(protocol.messages) as any[]) for (const interaction of Object.values(message.interactions || {}) as any[]) { + expect(interaction.request?.headers?.[1]).not.toEqual({}) + } + expect(protocol.header[1].description).toContain('including when it is a response or publication') + const gps = interactionView(39, 'read-gps-state') + const fields = resolveDocumentationFields(protocol, protocol.messages[39], gps.response!.fields, 'fields') + for (const id of [1, 2]) expect(fields.find(field => field.id === id)?.description).toBe(protocol.messages[39].data[id].description) + expect(resolveDocumentationErrors(protocol, gps.errors).find(error => error.code === 7)?.description).toBe(protocol.header[4].values[7].description) + expect(interactionView(39, 'configure-gps').request?.fields?.[2]?.description).toContain('Omitting this field sets API-enabled corrections to disabled') + }) + + it('shares Message Box version prose while preserving SET and tracking exceptions', () => { + const message = protocol.messages[58] + const get = interactionView(58, 'read-message-box') + const subscribe = interactionView(58, 'subscribe-message-box') + expect(get.response!.fields![129].description).toBe(message.versions[2].fields[129].description) + expect(subscribe.publication!.fields![129].description).toBe(message.versions[2].fields[129].description) + expect(interactionView(58, 'read-message-box-v1').response!.fields![1].description).toBe(message.versions[1].fields[1].description) + expect(interactionView(58, 'subscribe-message-box-v1').publication!.fields![1].description).toBe(message.versions[1].fields[1].description) + expect(interactionView(58, 'replace-message-box').request!.fields![129].description).toContain('zero-length') + expect(interactionView(58, 'tracking-message-box-upload').publication!.fields![129].description).toContain('Independent') + }) +}) + +describe('canonical documentation errors', () => { + it('inherits names and meanings while preserving contextual and intentionally empty prose', () => { + const canonical = { header: { 4: { values: { 4: { name: 'Invalid Parameter', description: 'Canonical meaning' } } } } } + const errors = [{ code: 4 }, { code: 4, description: 'Actual cause' }, { code: 4, description: '' }] + const before = clone(errors) + expect(resolveDocumentationErrors(canonical, errors)).toEqual([ + { code: 4, name: 'Invalid Parameter', description: 'Canonical meaning' }, + { code: 4, name: 'Invalid Parameter', description: 'Actual cause' }, + { code: 4, name: 'Invalid Parameter', description: '' }, + ]) + expect(errors).toEqual(before) + expect(resolveDocumentationErrors(canonical)).toEqual([]) + }) + it('validates optional descriptions, unknown statuses and non-string prose', () => { + const sample = clone(protocol) + const operation = sample.messages[39].interactions['configure-gps'] + operation.errors = [{ code: 4 }] + expect(validateMessageDocumentation(sample, 39)).toEqual([]) + operation.errors = [{ code: 999 }, { code: 4, description: 123 }, { code: '4' }] + const errors = validateMessageDocumentation(sample, 39).join('\n') + expect(errors).toContain('unknown status 999') + expect(errors).toContain('unknown status 4') + expect(errors).toContain('description must be a string') + }) +}) diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index 7761440d2..daab298ad 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -138,7 +138,7 @@ export interface DocumentationVariant { request?: DocumentationContext response?: DocumentationContext publication?: DocumentationContext - errors?: { code: number; description: string }[] + errors?: { code: number; description?: string }[] examples?: DocumentationExample[] } @@ -264,11 +264,15 @@ export function getMessageDocumentation(message: any, protocol: any): MessageDoc const method = interactionMethod(source, protocol) const contexts = (value: any) => Object.fromEntries(['request', 'response', 'publication'].filter(role => value?.[role] !== undefined).map(role => { const context = value[role] - const inherited = message.methods?.[method || '']?.[role] + const contextMessage = protocol.messages?.[context.messageId] + const sameMessage = context.messageId === undefined || contextMessage === message || + message.id !== undefined && contextMessage?.id === message.id + const versionFields = sameMessage && source.messageVersion !== undefined + ? versions[source.messageVersion]?.fields : undefined return [role, { ...context, ...Object.fromEntries(['headers', 'fields'].filter(kind => context?.[kind] !== undefined).map(kind => [ kind, Object.fromEntries(Object.entries(context[kind]).map(([fieldId, usage]: [string, any]) => [ fieldId, { - ...(kind === 'fields' && context.messageId === undefined ? { description: inherited?.[fieldId]?.description } : {}), + ...(kind === 'fields' ? versionFields?.[fieldId] : {}), presence: 'optional', ...usage, }, ])), @@ -291,7 +295,7 @@ export function getMessageDocumentation(message: any, protocol: any): MessageDoc const fieldsFor = (version?: string) => Object.fromEntries(Object.entries(message.data || {}) .filter(([, field]: [string, any]) => version === undefined || !field.versions || Array.isArray(field.versions) && field.versions.includes(Number(version))) - .map(([id]) => [id, {}])) + .map(([id]) => [id, version === undefined ? {} : { ...versions[version]?.fields?.[id] }])) let currentAnchorUsed = false let legacyAnchorUsed = false const formats: DocumentationFormat[] = Object.entries(versions).sort(([a], [b]) => Number(b) - Number(a)).map(([id, version]: [string, any]) => { @@ -354,6 +358,14 @@ export function resolveDocumentationFields( .sort((a, b) => Number(b.presence === 'required') - Number(a.presence === 'required')) } +/** Resolve canonical status meaning, retaining only explicitly authored context overrides. */ +export function resolveDocumentationErrors(protocol: any, errors?: { code: number; description?: string }[]) { + return (errors || []).map(error => { + const definition = protocol.header?.[4]?.values?.[error.code] + return { code: error.code, name: definition?.name, description: error.description ?? definition?.description ?? '' } + }) +} + /** Validate the authoring shape before normalization can hide a typo or bad reference. */ function validateInlineDocumentation(message: any, messageId: number, protocol: any): string[] { const errors: string[] = [] @@ -409,6 +421,20 @@ function validateInlineDocumentation(message: any, messageId: number, protocol: else { if (typeof version.label !== 'string' || !version.label.trim()) errors.push(`${id} version needs a label`) if (version.legacy !== undefined && typeof version.legacy !== 'boolean') errors.push(`${id} has invalid legacy flag`) + if (version.fields !== undefined) { + if (!object(version.fields)) errors.push(`${id} version fields must be a mapping`) + else for (const [fieldId, usage] of Object.entries(version.fields) as [string, any][]) { + const label = `${id} version field ${fieldId}` + const field = message.data?.[fieldId] + if (!/^(0|[1-9]\d*)$/.test(fieldId) || !field) errors.push(`${label} references unknown field`) + if (Array.isArray(field?.versions) && !field.versions.includes(Number(id))) errors.push(`${label} is outside its versions`) + if (!object(usage)) errors.push(`${label} must be an object`) + else { + knownKeys(usage, ['description'], label) + if (typeof usage.description !== 'string') errors.push(`${label} description must be a string`) + } + } + } } } for (const [id, field] of Object.entries(message.data || {}) as [string, any][]) { @@ -575,7 +601,8 @@ export function validateMessageDocumentation(protocol: any, messageId: number): const label = `${operation.id}/${variant.id}` for (const role of ['request', 'response', 'publication'] as const) validateContext(view[role], `${label} ${role}`) for (const error of view.errors || []) { - if (!protocol.header?.[4]?.values?.[error.code]) fail(`${label} references unknown status ${error.code}`) + if (!Number.isInteger(error.code) || !protocol.header?.[4]?.values?.[error.code]) fail(`${label} references unknown status ${error.code}`) + if (error.description !== undefined && typeof error.description !== 'string') fail(`${label} status ${error.code} description must be a string`) } for (const example of view.examples || []) { if (!example.title || !['generated', 'captured'].includes(example.provenance)) fail(`${label} example needs title and provenance`) From b292df7c6760028de2b61ad1a08446dfde9dae8c Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 17:33:02 +0000 Subject: [PATCH 19/24] Reuse scoped YAML fragments and export expanded protocol --- .vitepress/config.mts | 9 + .vitepress/plugins/expanded-protocol.cjs | 23 +++ README.md | 55 ++++++ cspell.yaml | 1 + devices/api/protocol/index.md | 7 + devices/api/protocol/responses.md | 28 +++ package.json | 3 +- public/files/protocol-v3.yaml | 209 +++++++---------------- utils/ExpandedProtocol.test.ts | 190 +++++++++++++++++++++ utils/MessageDocumentation.test.ts | 73 ++++++++ utils/MessageDocumentation.ts | 88 +++++++--- utils/expanded-protocol.cjs | 40 +++++ 12 files changed, 552 insertions(+), 174 deletions(-) create mode 100644 .vitepress/plugins/expanded-protocol.cjs create mode 100644 utils/ExpandedProtocol.test.ts create mode 100644 utils/expanded-protocol.cjs diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 6b01568a4..a561d385c 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -1,6 +1,7 @@ import path from 'path'; import fs from 'fs'; import yaml from 'js-yaml'; +import { createRequire } from 'node:module'; import { defineConfig } from 'vitepress'; import { useSidebar } from 'vitepress-openapi'; import { loadSpec } from '../swagger/load'; @@ -20,6 +21,10 @@ import { capabilitySidebar } from '../utils/DeviceCapabilities'; const base = process.env.PREVIEW_BASE || "/" +// Keep the shared Node CLI helpers outside Vite's ESM config bundle. +const requireFromConfig = createRequire(import.meta.url); +const expandedProtocolPlugin = requireFromConfig(path.resolve(__dirname, './plugins/expanded-protocol.cjs')); +const expandedProtocol = requireFromConfig(path.resolve(__dirname, '../utils/expanded-protocol.cjs')); // Load protocol messages from YAML file const protocolYamlPath = path.resolve(__dirname, '../public/files/protocol-v3.yaml'); @@ -203,6 +208,9 @@ export default withMermaid(defineConfig({ description: "home for everything Lightbug", lang: 'en-GB', cleanUrls: true, + buildEnd(siteConfig) { + expandedProtocol.writeExpandedProtocol(siteConfig.outDir, protocolYamlPath); + }, sitemap: { hostname: process.env.DEPLOYMENT_NAME === 'Production' ? 'https://docs.lightbug.io' : 'https://docs-next.lightbug.io' }, @@ -223,6 +231,7 @@ export default withMermaid(defineConfig({ noExternal: ["vuetify", "vitepress-openapi"] }, plugins: [ + expandedProtocolPlugin(protocolYamlPath, base), // Keep the native samples export available on versions that omit it. { name: 'prototype-native-code-samples-export', diff --git a/.vitepress/plugins/expanded-protocol.cjs b/.vitepress/plugins/expanded-protocol.cjs new file mode 100644 index 000000000..687db5fe6 --- /dev/null +++ b/.vitepress/plugins/expanded-protocol.cjs @@ -0,0 +1,23 @@ +const { readExpandedProtocol, expandedProtocolFilename } = require('../../utils/expanded-protocol.cjs'); + +// Production uses VitePress's buildEnd hook. Serve the same export directly +// from the canonical source in development, without an intermediate file. +module.exports = function expandedProtocolPlugin(sourcePath, base = '/') { + const downloadPath = `${base.replace(/\/$/, '')}/files/${expandedProtocolFilename}`; + return { + name: 'expanded-protocol-download', + configureServer(server) { + server.middlewares.use((request, response, next) => { + if (!['GET', 'HEAD'].includes(request.method) || request.url?.split('?')[0] !== downloadPath) return next(); + try { + const source = readExpandedProtocol(sourcePath); + response.setHeader('Content-Type', 'application/yaml; charset=utf-8'); + response.setHeader('Cache-Control', 'no-cache'); + response.end(request.method === 'HEAD' ? undefined : source); + } catch (error) { + next(error); + } + }); + }, + }; +}; diff --git a/README.md b/README.md index 1c98426e5..5f3300b42 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,61 @@ Both scripts use `cross-env` so they work cross-platform. PR preview workflows and administrator setup: [.github/preview](https://github.com/lightbug-io/docs/blob/main/.github/preview/README.md). +## Protocol YAML authoring and export + +`public/files/protocol-v3.yaml` is the canonical source. It uses native YAML +anchors (`&name`), aliases (`*name`) and merge keys (`<<: *name`), parsed by the +same `js-yaml` dependency used by the docs. There is no separate template engine. +Consumers without merge-key support can use the expanded export below. + +- Definitions used only within one message are anchored at their first use in + that message. Use message-specific anchor names: anchors have document scope, + not message scope, and must appear before their aliases. +- Only header maps shared across messages live in the top-level + `templates.headers` registry: `optionalOkReply`, `correlatedOkAck`, and + `optionalCorrelationAck`. An anchor has no effect unless explicitly aliased + or merged into an actual message definition. +- A YAML merge is shallow. An explicit key replaces that entire merged value; + replacing a header entry does not inherit the entry's other properties. + Anchor smaller maps when individual nested values need to be reused. + +### Navigate shared definitions + +In VS Code with [Red Hat YAML](https://github.com/redhat-developer/vscode-yaml), +put the caret on an alias (`*name`) and run **Go to Definition** from the context +menu. The extension's language server +[resolves aliases to their anchors](https://github.com/redhat-developer/yaml-language-server/blob/main/src/languageservice/services/yamlDefinition.ts). +This follows the explicit alias, not an inherited field name or arbitrary string. + +[IntelliJ IDEA's YAML support](https://www.jetbrains.com/help/idea/yaml.html) +documents alias-to-anchor navigation, anchor usages, and anchor/alias rename. +Use **Go to Declaration or Usages**; the shortcut depends on your key bindings. +These are editor features, not something the docs site adds. If your editor or +extension version lacks them, search for `&name` in the canonical file. The +expanded download below is useful for inspecting all values without jumping. + +### Export expanded YAML + +The protocol overview offers **Download expanded YAML** at +`files/protocol-v3-expanded.yaml`, including on PR previews. The build creates it +from the canonical source; the development server generates it on each request. +Do not commit or edit a second generated specification. + +To inspect or save the same output locally after installing dependencies: + +```bash +npm run --silent export:protocol +npm run --silent export:protocol > /tmp/protocol-v3-expanded.yaml +``` + +The export resolves aliases and merge keys using the `yaml` library's typed +maps, keeping numeric keys as integers and deliberately quoted keys as strings +for SDK generator compatibility. It emits no anchors and removes only +the top-level authoring-only `templates` registry. All other parsed data is +preserved, including sentinels and version overrides. It does not invent runtime +defaults or flatten message-version description inheritance. Comments and +source formatting are not retained. Edit the canonical source and re-export. + ## Protocol sentinel values Numeric field definitions in `public/files/protocol-v3.yaml` can declare raw diff --git a/cspell.yaml b/cspell.yaml index bfd692b18..b2f4af192 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -42,6 +42,7 @@ words: - zcard # Lightbug terms + - gingin # Acronyms, initialisms, technical terms - retryable - nonpositive diff --git a/devices/api/protocol/index.md b/devices/api/protocol/index.md index 59e79373c..77c8bdfc0 100644 --- a/devices/api/protocol/index.md +++ b/devices/api/protocol/index.md @@ -3,6 +3,7 @@ outline: [1,3] --- # Protocol @@ -13,6 +14,12 @@ The protocol is designed to be: - Lightweight to store and transmit - Usable in a variety of settings, without complex or bloated dependencies +## YAML specification + +[Canonical YAML source](/files/protocol-v3.yaml) uses native YAML anchors and merge keys for repeated definitions. + +Download expanded YAML for the complete specification with aliases and merge keys resolved and the authoring-only `templates` registry removed. This export preserves the authored message versions and metadata; it does not apply runtime defaults or copy inherited descriptions into version overrides. Comments and source formatting are not retained. + ## Byte Breakdown diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 1a94dd7cc..769b86638 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -144,6 +144,34 @@ GET, SET and SUBSCRIBE are values of Method header 5, not separate wire structur An interaction describes an exchange, not arbitrary ordered sequences of requests. Applicability can be narrowed with `target` without making fields required. Its stages remain subject to the correlation, suppression and target rules above; defining a response does not guarantee it is sent. +### Reusing YAML fragments + +Use native YAML anchors for repeated usage maps. Keep message-specific fragments at their first use within that message, with descriptive names such as `messageBoxV1Fields`. Only genuinely cross-message header groups belong in the global `templates.headers` catalog, before `messages`. These are authoring helpers, not additional wire headers or rules that apply automatically. + +A complete map can be reused with an alias, for example `fields: *messageBoxV1Fields`. Merge a shared header group when the stage also needs local entries: + +```yaml +templates: + headers: + optionalOkReply: &optionalOkReplyHeaders + 3: {} + 4: {value: 0} + +# Inside a Message Box v2 GET response: +response: + headers: + <<: *optionalOkReplyHeaders + 22: {presence: required, value: 2} +``` + +Multiple maps can be combined with one merge entry, `<<: [*specificHeaders, *baseHeaders]`. Earlier maps win conflicts, and explicitly written local keys override all merged maps. Merging is shallow: replacing `headers` replaces the whole header map, and replacing header `4` replaces that whole usage entry. Merge again at the level being changed, or restate the small entry. Arrays do not concatenate, and `null` does not delete a key. + +Define anchors before their aliases in the same document. For a message-local subset, the first use can define it directly under `<<: &messageBoxSubscriptionHeaders`; keep format-specific header 22 outside that subset. Do not reuse the cached-payload field map for independent uploads, or assume every publication omits the same headers. Keep short method selectors explicit rather than adding an anchor for every one-line value. + +To inspect the complete specification without following aliases, use the [expanded YAML download](./#yaml-specification). + +The site resolves native aliases and merges before validating the expanded interactions. It also validates unused global header templates, so a typo cannot remain hidden until a later use. Consumers using another YAML parser must enable merge-key support. Exporters should preserve the authored source or consume the expanded copy; writing typed data back to YAML may discard anchors and documentation metadata. + ## Subscription replies and later updates A subscription's control reply and its later publications are different events. A control ACK reports the command status; it is not the subscribed data. Later publications can have their own headers, payload and status behavior. diff --git a/package.json b/package.json index 47eef6838..4e958e927 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,8 @@ "build:production": "cross-env DEPLOYMENT_NAME=Production PUBLIC_GOOGLE_ANALYTICS=${PUBLIC_GOOGLE_ANALYTICS} vitepress build", "build:next": "cross-env DEPLOYMENT_NAME=Next PUBLIC_GOOGLE_ANALYTICS=${PUBLIC_GOOGLE_ANALYTICS} vitepress build", "preview": "cross-env PUBLIC_GOOGLE_ANALYTICS=${PUBLIC_GOOGLE_ANALYTICS} vitepress preview", - "test": "jest" + "test": "jest", + "export:protocol": "node utils/expanded-protocol.cjs" }, "dependencies": { "@highlightjs/vue-plugin": "^2.1.0", diff --git a/public/files/protocol-v3.yaml b/public/files/protocol-v3.yaml index ac09ef8b7..b1ac6ce68 100644 --- a/public/files/protocol-v3.yaml +++ b/public/files/protocol-v3.yaml @@ -492,6 +492,18 @@ header: id: encryptionTag description: Encryption tag type: uint32 +# Shared header usage only; message-specific anchors stay with their messages. +templates: + headers: + optionalOkReply: &optionalOkReplyHeaders + 3: {} + 4: { value: 0 } + correlatedOkAck: &correlatedOkAckHeaders + 3: { presence: required } + 4: { presence: required, value: 0 } + optionalCorrelationAck: &optionalCorrelationAckHeaders + 3: {} + 4: { presence: required, value: 0 } messages: 3: name: Event @@ -1268,9 +1280,7 @@ messages: 5: { presence: required, value: 2 } response: description: Successful GET returns GSM state directly. - headers: - 3: {} - 4: { value: 0 } + headers: *optionalOkReplyHeaders fields: 1: { presence: required } 2: @@ -1296,9 +1306,7 @@ messages: milliseconds divided by 60000 and rounded down. Disabling flight mode ignores the duration. response: &gsmControlAck messageId: 5 - headers: - 3: { presence: required } - 4: { presence: required, value: 0 } + headers: *correlatedOkAckHeaders fields: 1: { presence: required, value: 31 } start-search: @@ -1387,9 +1395,7 @@ messages: description: >- Successful GET returns SIM settings directly. APN and credentials are returned only while SIM2 is active. A cached SIM2 ICCID may be returned with either active SIM. - headers: - 3: {} - 4: { value: 0 } + headers: *optionalOkReplyHeaders fields: 1: presence: required @@ -1408,9 +1414,7 @@ messages: 1: { presence: required, value: 0 } response: &simSettingsAck messageId: 5 - headers: - 3: { presence: required } - 4: { presence: required, value: 0 } + headers: *correlatedOkAckHeaders fields: 1: { presence: required, value: 33 } select-sim2: @@ -1581,10 +1585,8 @@ messages: title: Device status (MT34) description: A successful GET returns Device Status directly, without a separate success ACK. Returned fields vary by target and available readings. - headers: - 3: {} - 4: { value: 0 } - fields: + headers: *optionalOkReplyHeaders + fields: &deviceStatusFields 1: {} 2: {} 3: {} @@ -1642,9 +1644,7 @@ messages: messageId: 5 description: A successful setup returns an MT5 acknowledgment with Status 0. This acknowledges the request, not delivery of a status update. - headers: - 3: { presence: required } - 4: { presence: required, value: 0 } + headers: *correlatedOkAckHeaders publication: title: Status update (MT34) description: Later status updates produce Device Status messages, filtered by the subscription interval @@ -1657,18 +1657,7 @@ messages: 4: presence: omitted description: Status updates carry status data, not a command-result envelope. - fields: - 1: {} - 2: {} - 3: {} - 4: {} - 5: {} - 6: {} - 7: {} - 10: {} - 12: {} - 13: {} - 14: {} + fields: *deviceStatusFields stop-device-status-subscription: title: Stop the default status subscription description: Stop the default Device Status subscription (ID 0). This operation does not select a named @@ -1681,9 +1670,7 @@ messages: response: messageId: 5 description: A successful cancellation returns an MT5 acknowledgment with Status 0. - headers: - 3: { presence: required } - 4: { presence: required, value: 0 } + headers: *correlatedOkAckHeaders 35: name: Device IDs id: deviceIds @@ -1734,9 +1721,7 @@ messages: title: Device IDs (MT35) description: The GET response contains the available device identifiers. Not all fields are available on every device type. Cached SIM2 ICCID is a previously read value and may be stale. - headers: - 3: {} - 4: { value: 0 } + headers: *optionalOkReplyHeaders fields: 1: {} 2: {} @@ -2059,9 +2044,7 @@ messages: title: GPS state (MT39) description: A successful GET returns GPS Control directly, with no separate success ACK. An unsuccessful request returns MT5 (ACK) with Status, not this payload. - headers: - 3: {} - 4: { value: 0 } + headers: *optionalOkReplyHeaders fields: 1: presence: required @@ -2095,9 +2078,7 @@ messages: response: messageId: 5 description: Successful SET returns an ACK, not GPS state. Use GET to read the current state afterward. - headers: - 3: {} - 4: { presence: required, value: 0 } + headers: *optionalCorrelationAckHeaders fields: 1: presence: required @@ -3419,20 +3400,15 @@ messages: request: headers: 5: { presence: required, value: 2 } - 22: - presence: required - value: 2 + 22: { presence: required, value: 2 } response: title: Cached payload description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with Status instead. headers: - 3: {} - 4: { value: 0 } - 22: - presence: required - value: 2 - fields: + <<: *optionalOkReplyHeaders + 22: { presence: required, value: 2 } + fields: &messageBoxV2Fields 1: presence: omitted 2: @@ -3452,7 +3428,7 @@ messages: request: headers: 5: { presence: required, value: 2 } - 22: + 22: &legacyMessageBoxSelector description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an explicit 1 also selects version 1. values: @@ -3463,12 +3439,11 @@ messages: description: A successful GET returns this MT58 payload. An unsuccessful request returns MT5 (ACK) with Status instead. headers: - 3: {} - 4: { value: 0 } + <<: *optionalOkReplyHeaders 22: presence: omitted description: Legacy version 1 responses retain their original wire layout and omit Message Version. - fields: + fields: &messageBoxV1Fields 1: presence: required 2: @@ -3497,9 +3472,7 @@ messages: are ignored. headers: 5: { presence: required, value: 1 } - 22: - presence: required - value: 2 + 22: { presence: required, value: 2 } fields: 129: presence: required @@ -3510,10 +3483,8 @@ messages: messageId: 5 description: Successful SET returns an ACK, not the cached bytes. Subscriber publications are separate asynchronous messages and are not this reply. - headers: - 3: {} - 4: { presence: required, value: 0 } - fields: + headers: *optionalCorrelationAckHeaders + fields: &messageBoxAckFields 1: presence: required value: 58 @@ -3544,12 +3515,7 @@ messages: headers: '3': { presence: optional } '4': { presence: required, value: 0 } - fields: - '1': - presence: required - value: 58 - description: ACK Type identifies the original message type (58). No message-specific state is returned - in this ACK. + fields: *messageBoxAckFields errors: &messageBoxSubscribeErrors - code: 4 description: 'A decoded Message Version value above 2; existing selection and @@ -3558,39 +3524,31 @@ messages: messageVersion: 2 request: headers: - 5: { presence: required, value: 3 } - 6: - description: Optional publication interval in milliseconds. If omitted, updates are sent when new data - is available. - 7: - description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. - 16: - description: Minimum publication level. - 17: - description: Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. - 22: - presence: required - value: 2 + <<: &messageBoxSubscriptionHeaders + 5: { presence: required, value: 3 } + 6: + description: Optional publication interval in milliseconds. If omitted, updates are sent when new data + is available. + 7: + description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. + 16: + description: Minimum publication level. + 17: + description: Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. + 22: { presence: required, value: 2 } publication: title: Cached payload update description: Version 2 updates include Message Version 2 and field 2. Field 129 carries the complete cached payload when nonempty; empty payload data is omitted. headers: - 3: - presence: omitted - description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - 17: - description: Identifies nonzero subscription IDs for this publication. - 22: - presence: required - value: 2 - fields: - 1: - presence: omitted - 2: - presence: required - 129: - maxBytes: 1024 + <<: &messageBoxPublicationHeaders + 3: + presence: omitted + description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. + 17: + description: Identifies nonzero subscription IDs for this publication. + 22: { presence: required, value: 2 } + fields: *messageBoxV2Fields subscribe-message-box-v1: title: Subscribe to cached-message updates (legacy v1) description: >- @@ -3606,51 +3564,17 @@ messages: messageVersion: 1 request: headers: - 5: { presence: required, value: 3 } - 6: - description: Optional publication interval in milliseconds. If omitted, updates are sent when new data - is available. - 7: - description: Subscription duration in milliseconds; 0 is indefinite until explicitly unsubscribed. - 16: - description: Minimum publication level. - 17: - description: Subscription ID; omit for the default subscription (0). Use the same ID when unsubscribing. - 22: - description: Omitted, explicitly 0, or malformed-width values resolve to 0 and select version 1; an - explicit 1 also selects version 1. - values: - 0: Version 1 (also the omitted/malformed-width fallback) - 1: Version 1 + <<: *messageBoxSubscriptionHeaders + 22: *legacyMessageBoxSelector publication: title: Legacy cached payload update description: Version 1 updates use the additive checksum and legacy chunks. Empty payload data is omitted. headers: - 3: - presence: omitted - description: This is an asynchronous publication, not a direct reply to the SUBSCRIBE request. - 17: - description: Identifies nonzero subscription IDs for this publication. + <<: *messageBoxPublicationHeaders 22: presence: omitted description: Legacy version 1 responses retain their original wire layout and omit Message Version. - fields: - 1: - presence: required - 2: - presence: omitted - 10: - maxBytes: 255 - 11: - maxBytes: 255 - 12: - maxBytes: 255 - 13: - maxBytes: 255 - 14: - maxBytes: 255 - 129: - presence: omitted + fields: *messageBoxV1Fields stop-message-box-subscription: title: Stop a subscription description: Remove the addressed subscription. Message Version (header 22) is ignored; UNSUBSCRIBE does @@ -3666,15 +3590,8 @@ messages: messageId: 5 description: Successful UNSUBSCRIBE returns a control ACK confirming the unsubscribe request, not a final cached-message publication. - headers: - 3: {} - 4: { presence: required, value: 0 } - fields: - 1: - presence: required - value: 58 - description: ACK Type identifies the original message type (58). No message-specific state is returned - in this ACK. + headers: *optionalCorrelationAckHeaders + fields: *messageBoxAckFields tracking-message-box-upload: title: Tracking-session uploads description: A separate device-to-server context, not a GET response or subscription update. @@ -3690,9 +3607,7 @@ messages: for an empty cache. Independent upload bytes in field 129 do not form part of that cached-message CRC. headers: - 22: - presence: required - value: 2 + 22: { presence: required, value: 2 } fields: 2: description: 'Present when Message Box support is enabled: CRC-16/XMODEM of the cached down-synced diff --git a/utils/ExpandedProtocol.test.ts b/utils/ExpandedProtocol.test.ts new file mode 100644 index 000000000..633d85aaf --- /dev/null +++ b/utils/ExpandedProtocol.test.ts @@ -0,0 +1,190 @@ +/** @jest-environment node */ +import { execFileSync } from 'node:child_process' +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join, resolve } from 'node:path' + +const yaml = require('js-yaml') +const { parseDocument, isAlias, isScalar, visit } = require('yaml') +const { expandProtocolYaml, writeExpandedProtocol, expandedProtocolFilename } = require('./expanded-protocol.cjs') +const expandedProtocolPlugin = require('../.vitepress/plugins/expanded-protocol.cjs') + +const fixture = `version: 3 +templates: + headers: + reply: &replyHeaders + 3: { presence: optional } + 4: { presence: optional, value: 0 } +messages: + 37: + description: Base description stays at the base. + data: + 1: + type: int16 + sentinels: + -32768: { id: unavailable, name: Unavailable } + interactions: + get: + response: &localResponse + headers: + <<: *replyHeaders + 4: { value: 6 } + note: 'Text containing &anchor, *alias and <<: is not YAML syntax.' + subscribe: + response: *localResponse + versions: + 2: + data: {} + metadata: + templates: preserved +` + +describe('expanded protocol YAML', () => { + it('resolves native aliases and shallow merges without adding application inheritance', () => { + const output = expandProtocolYaml(fixture) + const parsed = yaml.load(output) + const { templates, ...expected } = yaml.load(fixture) + expect(parsed).toEqual(expected) + expect(parsed.templates).toBeUndefined() + expect(parsed.messages[37].metadata.templates).toBe('preserved') + expect(parsed.messages[37].interactions.get.response.headers).toEqual({ + 3: { presence: 'optional' }, + 4: { value: 6 }, + }) + expect(parsed.messages[37].interactions.subscribe.response).toEqual(parsed.messages[37].interactions.get.response) + expect(parsed.messages[37].versions[2]).toEqual({ data: {} }) + const document = parseDocument(output) + expect(document.errors).toEqual([]) + visit(document, (_key: unknown, node: any) => { + expect(isAlias(node)).toBe(false) + expect(node?.anchor).toBeUndefined() + if (isScalar(node)) expect(node.value).not.toBe('<<') + }) + }) + + it('keeps every authored value from the complete canonical spec except the registry', () => { + const source = readFileSync(resolve(__dirname, '../public/files/protocol-v3.yaml'), 'utf8') + const { templates, ...expected } = yaml.load(source) + const output = expandProtocolYaml(source) + expect(yaml.load(output)).toEqual(expected) + // JS objects alone cannot distinguish integer map keys from string keys. + const expectedTyped = parseDocument(source, { merge: true, customTags: ['timestamp'] }).toJS({ mapAsMap: true }) + expectedTyped.delete('templates') + expect(parseDocument(output, { customTags: ['timestamp'] }).toJS({ mapAsMap: true })).toEqual(expectedTyped) + // The expansion is deterministic and already-expanded output is unchanged. + expect(expandProtocolYaml(output)).toBe(output) + }) + + it('preserves integer keys required by SDK generators, including merged headers and sentinels', () => { + const parsed = parseDocument(expandProtocolYaml(fixture)).toJS({ mapAsMap: true }) + const messages = parsed.get('messages') + expect([...messages.keys()]).toEqual([37]) + const message = messages.get(37) + expect([...message.get('data').keys()]).toEqual([1]) + expect([...message.get('data').get(1).get('sentinels').keys()]).toEqual([-32768]) + expect([...message.get('versions').keys()]).toEqual([2]) + for (const method of ['get', 'subscribe']) { + const headers = message.get('interactions').get(method).get('response').get('headers') + expect([...headers.keys()].sort()).toEqual([3, 4]) + } + }) + + it('does not turn deliberately quoted scalar keys or values into numbers, dates or booleans', () => { + const source = `version: 3 +integerKeys: + 1: one + -32768: sentinel +stringKeys: + "1": numeric-looking key + "001": leading zero key + "false": boolean-looking key + "2025-10-10": date-looking key +quotedDate: "2025-10-10" +timestamp: 2025-10-10 +quotedNumber: "1e2" +stringYes: yes +` + const output = expandProtocolYaml(source) + const parsed = parseDocument(output, { customTags: ['timestamp'] }).toJS({ mapAsMap: true }) + expect([...parsed.get('integerKeys').keys()]).toEqual([1, -32768]) + expect([...parsed.get('stringKeys').keys()]).toEqual(['1', '001', 'false', '2025-10-10']) + expect(yaml.load(output)).toEqual(yaml.load(source)) + expect(parsed.get('quotedDate')).toBe('2025-10-10') + expect(parsed.get('timestamp')).toEqual(new Date('2025-10-10T00:00:00.000Z')) + }) + + it('rejects invalid YAML and non-mapping documents instead of emitting a partial export', () => { + expect(() => expandProtocolYaml('messages: *missing')).toThrow() + expect(() => expandProtocolYaml('version: 3\nversion: 4')).toThrow() + for (const source of ['', 'null', '[]', 'plain string']) { + expect(() => expandProtocolYaml(source)).toThrow('must contain a mapping') + } + }) + + it('exports clean YAML through the command from any working directory', () => { + const source = readFileSync(resolve(__dirname, '../public/files/protocol-v3.yaml'), 'utf8') + const output = execFileSync(process.execPath, [resolve(__dirname, 'expanded-protocol.cjs')], { + cwd: tmpdir(), encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, + }) + expect(output).toBe(expandProtocolYaml(source)) + }) +}) + +describe('expanded protocol download', () => { + let directory: string + let sourcePath: string + beforeEach(() => { + directory = mkdtempSync(join(tmpdir(), 'expanded-protocol-')) + sourcePath = join(directory, 'source.yaml') + writeFileSync(sourcePath, fixture) + }) + afterEach(() => rmSync(directory, { recursive: true, force: true })) + + function request(base: string, url: string, method = 'GET') { + let handler: any + expandedProtocolPlugin(sourcePath, base).configureServer({ + middlewares: { use(callback: any) { handler = callback } }, + }) + const response = { setHeader: jest.fn(), end: jest.fn() } + const next = jest.fn() + handler({ url, method }, response, next) + return { response, next } + } + + it('writes the same derived file into the build output without modifying the source', () => { + writeExpandedProtocol(join(directory, 'output'), sourcePath) + expect(readFileSync(join(directory, 'output/files', expandedProtocolFilename), 'utf8')).toBe(expandProtocolYaml(fixture)) + expect(readFileSync(sourcePath, 'utf8')).toBe(fixture) + }) + + it.each(['/', '/docs/pr/30/'])('serves fresh YAML with the %s base path in development', base => { + const url = `${base}files/${expandedProtocolFilename}?download=1` + const { response, next } = request(base, url) + expect(next).not.toHaveBeenCalled() + expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/yaml; charset=utf-8') + expect(response.setHeader).toHaveBeenCalledWith('Cache-Control', 'no-cache') + expect(response.end).toHaveBeenCalledWith(expandProtocolYaml(fixture)) + writeFileSync(sourcePath, fixture.replace('version: 3', 'version: 4')) + expect(yaml.load(request(base, url).response.end.mock.calls[0][0]).version).toBe(4) + }) + + it('supports HEAD without a body and leaves other paths and methods alone', () => { + expect(request('/', `/files/${expandedProtocolFilename}`, 'HEAD').response.end).toHaveBeenCalledWith(undefined) + for (const [base, url, method] of [ + ['/', `/files/${expandedProtocolFilename}`, 'POST'], + ['/', '/files/protocol-v3.yaml', 'GET'], + ['/docs/pr/30/', `/files/${expandedProtocolFilename}`, 'GET'], + ]) { + const { response, next } = request(base, url, method) + expect(next).toHaveBeenCalledWith() + expect(response.end).not.toHaveBeenCalled() + } + }) + + it('passes invalid source errors through instead of returning a successful download', () => { + writeFileSync(sourcePath, 'messages: *missing') + const { response, next } = request('/', `/files/${expandedProtocolFilename}`) + expect(next).toHaveBeenCalledWith(expect.any(Error)) + expect(response.end).not.toHaveBeenCalled() + }) +}) diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 7952d53fb..7b549167a 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -1,3 +1,4 @@ +/** @jest-environment-options {"customExportConditions":["node","node-addons"]} */ import { describe, expect, it } from '@jest/globals' import { readFileSync } from 'node:fs' import { resolve } from 'node:path' @@ -883,3 +884,75 @@ describe('canonical documentation errors', () => { expect(errors).toContain('description must be a string') }) }) + +describe('native YAML reuse', () => { + it('keeps shared headers global and repeated message payloads local', () => { + expect(Object.keys(protocol.templates.headers)).toEqual(['optionalOkReply', 'correlatedOkAck', 'optionalCorrelationAck']) + expect(protocol.templates.headers.optionalOkReply).toEqual({ 3: {}, 4: { value: 0 } }) + expect(protocol.templates.headers.correlatedOkAck).toEqual({ 3: { presence: 'required' }, 4: { presence: 'required', value: 0 } }) + expect(protocol.templates.headers.optionalCorrelationAck).toEqual({ 3: {}, 4: { presence: 'required', value: 0 } }) + const status = protocol.messages[34].interactions + expect(status['read-device-status'].response.fields).toBe(status['subscribe-device-status'].publication.fields) + const box = protocol.messages[58].interactions + expect(box['read-message-box'].response.fields).toBe(box['subscribe-message-box'].publication.fields) + expect(box['read-message-box-v1'].response.fields).toBe(box['subscribe-message-box-v1'].publication.fields) + expect(box['replace-message-box'].response.fields).toBe(box['subscribe-message-box'].response.fields) + expect(box['replace-message-box'].response.fields).toBe(box['stop-message-box-subscription'].response.fields) + expect(box['subscribe-message-box'].publication.headers[3].presence).toBe('omitted') + expect(box['subscribe-message-box'].publication.headers[4]).toBeUndefined() + expect(status['subscribe-device-status'].publication.headers[4].presence).toBe('omitted') + expect(validateProtocolInteractions(protocol)).toEqual([]) + }) + + it('expands both YAML parsers identically and does not mutate shared aliases during normalization', () => { + const { parseDocument } = require('yaml') + const source = readFileSync(resolve(__dirname, '../public/files/protocol-v3.yaml'), 'utf8') + const document = parseDocument(source, { merge: true, uniqueKeys: true }) + expect(document.errors).toEqual([]) + expect(document.toJS()).toEqual(protocol) + const sample = yaml.load(source) + const before = clone(sample) + for (const id of [31, 33, 34, 35, 39, 58]) getMessageDocumentation(sample.messages[id], sample) + expect(sample).toEqual(before) + const docs = getMessageDocumentation(sample.messages[34], sample)! + docs.operations[0].response!.fields![1].description = 'Local edit' + docs.operations[0].response!.headers![3].description = 'Local header edit' + expect(sample).toEqual(before) + expect(docs.operations[1].publication!.fields![1].description).not.toBe('Local edit') + }) + + it('keeps message-specific subscription selectors outside shared header fragments', () => { + const box = protocol.messages[58].interactions + const current = box['subscribe-message-box'].request.headers + const legacy = box['subscribe-message-box-v1'].request.headers + for (const id of [5, 6, 7, 16, 17]) expect(current[id]).toEqual(legacy[id]) + expect(current[22]).toEqual({ presence: 'required', value: 2 }) + expect(legacy[22]).toBe(box['read-message-box-v1'].request.headers[22]) + expect(legacy[22].value).toBeUndefined() + expect(legacy[22].values).toHaveProperty('1') + expect(box['tracking-message-box-upload'].publication.fields).not.toEqual(box['read-message-box'].response.fields) + }) + + it.each([ + ['non-object registry', (p: any) => { p.templates = null }], + ['unknown registry section', (p: any) => { p.templates.responses = {} }], + ['non-object header registry', (p: any) => { p.templates.headers = [] }], + ['invalid name', (p: any) => { p.templates.headers['Invalid name'] = {} }], + ['non-object header group', (p: any) => { p.templates.headers.unused = null }], + ['unknown header', (p: any) => { p.templates.headers.unused = { 999: {} } }], + ['null header usage', (p: any) => { p.templates.headers.unused = { 3: null } }], + ['unknown usage property', (p: any) => { p.templates.headers.unused = { 3: { type: 'uint8' } } }], + ['invalid presence', (p: any) => { p.templates.headers.unused = { 3: { presence: '' } } }], + ['invalid description', (p: any) => { p.templates.headers.unused = { 3: { description: false } } }], + ['invalid values shape', (p: any) => { p.templates.headers.unused = { 4: { values: [] } } }], + ['invalid value description', (p: any) => { p.templates.headers.unused = { 4: { values: { 0: null } } } }], + ['unknown value property', (p: any) => { p.templates.headers.unused = { 4: { values: { 0: { type: 'uint8' } } } } }], + ['unknown enum value', (p: any) => { p.templates.headers.unused = { 4: { value: 999 } } }], + ['invalid width', (p: any) => { p.templates.headers.unused = { 3: { maxBytes: -1 } } }], + ['conflicting bounds', (p: any) => { p.templates.headers.unused = { 3: { minBytes: 4, maxBytes: 1 } } }], + ])('rejects %s even when the template is unused', (_name, change) => { + const sample = clone(protocol) + change(sample) + expect(validateProtocolInteractions(sample).some(error => error.startsWith('Protocol template'))).toBe(true) + }) +}) diff --git a/utils/MessageDocumentation.ts b/utils/MessageDocumentation.ts index daab298ad..eca3e84e0 100644 --- a/utils/MessageDocumentation.ts +++ b/utils/MessageDocumentation.ts @@ -366,6 +366,55 @@ export function resolveDocumentationErrors(protocol: any, errors?: { code: numbe }) } +/** Validate expanded usage maps, including templates that have no current consumers. */ +function validateDocumentationUsage( + usage: any, definitions: any, label: string, kind: string, fail: (message: string) => void, strict = false, +) { + const object = (value: any) => !!value && typeof value === 'object' && !Array.isArray(value) + if (usage !== undefined && !object(usage)) { fail(`${label} ${kind} must be a mapping`); return } + for (const [key, field] of Object.entries(usage || {}) as [string, any][]) { + const definition = definitions?.[key] + if (!/^\d+$/.test(key) || !definition) { + fail(`${label} references unknown ${kind} id ${key}`) + continue + } + if (!object(field)) { + fail(`${label} ${kind} ${key} must be an object`) + continue + } + if (strict) { + for (const property of Object.keys(field)) { + if (!['description', 'presence', 'value', 'values', 'minBytes', 'maxBytes'].includes(property)) fail(`${label} ${kind} ${key} has unknown property ${property}`) + } + if (field.description !== undefined && typeof field.description !== 'string') fail(`${label} ${kind} ${key} description must be a string`) + if (field.values !== undefined && !object(field.values)) fail(`${label} ${kind} ${key} values must be a mapping`) + if (object(field.values)) for (const [value, details] of Object.entries(field.values) as [string, any][]) { + if (typeof details === 'string') continue + if (!object(details) || details.description !== undefined && typeof details.description !== 'string') { + fail(`${label} ${kind} ${key} value ${value} description must be a string or description mapping`) + } else for (const property of Object.keys(details)) { + if (property !== 'description') fail(`${label} ${kind} ${key} value ${value} has unknown property ${property}`) + } + } + } + if ((strict ? field.presence !== undefined : field.presence) && !['required', 'optional', 'ignored', 'omitted'].includes(field.presence)) { + fail(`${label} ${kind} ${key} has invalid presence`) + } + if (field.maxBytes !== undefined && (!Number.isInteger(field.maxBytes) || field.maxBytes < 0)) { + fail(`${label} ${kind} ${key} has invalid maxBytes`) + } + if (field.minBytes !== undefined && (!Number.isInteger(field.minBytes) || field.minBytes < 0 || field.maxBytes !== undefined && field.minBytes > field.maxBytes)) { + fail(`${label} ${kind} ${key} has invalid minBytes`) + } + for (const value of [field.value, ...Object.keys(field.values || {}).map(Number)]) { + if (value === undefined) continue + if (!Number.isInteger(value) || (definition.values && !Object.prototype.hasOwnProperty.call(definition.values, value))) { + fail(`${label} ${kind} ${key} references unknown value ${value}`) + } + } + } +} + /** Validate the authoring shape before normalization can hide a typo or bad reference. */ function validateInlineDocumentation(message: any, messageId: number, protocol: any): string[] { const errors: string[] = [] @@ -554,32 +603,7 @@ export function validateMessageDocumentation(protocol: any, messageId: number): if (!contextMessage) fail(`${label} references unknown message ${context.messageId}`) for (const kind of ['headers', 'fields'] as const) { const definitions = kind === 'headers' ? protocol.header : contextMessage?.data - for (const [key, field] of Object.entries(context[kind] || {})) { - const definition = definitions?.[key] - if (!/^\d+$/.test(key) || !definition) { - fail(`${label} references unknown ${kind} id ${key}`) - continue - } - if (!field || typeof field !== 'object') { - fail(`${label} ${kind} ${key} must be an object`) - continue - } - if (field.presence && !['required', 'optional', 'ignored', 'omitted'].includes(field.presence)) { - fail(`${label} ${kind} ${key} has invalid presence`) - } - if (field.maxBytes !== undefined && (!Number.isInteger(field.maxBytes) || field.maxBytes < 0)) { - fail(`${label} ${kind} ${key} has invalid maxBytes`) - } - if (field.minBytes !== undefined && (!Number.isInteger(field.minBytes) || field.minBytes < 0 || field.maxBytes !== undefined && field.minBytes > field.maxBytes)) { - fail(`${label} ${kind} ${key} has invalid minBytes`) - } - for (const value of [field.value, ...Object.keys(field.values || {}).map(Number)]) { - if (value === undefined) continue - if (!Number.isInteger(value) || (definition.values && !Object.prototype.hasOwnProperty.call(definition.values, value))) { - fail(`${label} ${kind} ${key} references unknown value ${value}`) - } - } - } + validateDocumentationUsage(context[kind], definitions, label, kind, fail) } } @@ -624,5 +648,17 @@ export function validateMessageDocumentation(protocol: any, messageId: number): /** Validate inline interactions before publishing the specification and its reference pages. */ export function validateProtocolInteractions(protocol: any): string[] { const errors = protocol.interactions === undefined ? [] : ['Interactions belong inside their message definitions'] + if (protocol.templates !== undefined) { + const object = (value: any) => !!value && typeof value === 'object' && !Array.isArray(value) + if (!object(protocol.templates)) errors.push('Protocol templates must be a mapping') + else { + for (const key of Object.keys(protocol.templates)) if (key !== 'headers') errors.push(`Protocol templates has unknown property ${key}`) + if (!object(protocol.templates.headers)) errors.push('Protocol templates.headers must be a mapping') + else for (const [name, usage] of Object.entries(protocol.templates.headers)) { + if (!/^[a-z][a-zA-Z0-9-]*$/.test(name)) errors.push(`Protocol template ${name} needs a stable name`) + validateDocumentationUsage(usage, protocol.header, `Protocol template ${name}`, 'headers', error => errors.push(error), true) + } + } + } return errors.concat(Object.keys(protocol.messages || {}).flatMap(id => validateMessageDocumentation(protocol, Number(id)))) } diff --git a/utils/expanded-protocol.cjs b/utils/expanded-protocol.cjs new file mode 100644 index 000000000..012491196 --- /dev/null +++ b/utils/expanded-protocol.cjs @@ -0,0 +1,40 @@ +const fs = require('node:fs'); +const path = require('node:path'); +const yaml = require('yaml'); + +const protocolYamlPath = path.resolve(__dirname, '../public/files/protocol-v3.yaml'); +const expandedProtocolFilename = 'protocol-v3-expanded.yaml'; + +// Typed maps retain integer keys required by the SDK generators. Plain JS +// objects lose that distinction and would export numeric keys as strings. +// No defaults or message-version inheritance are applied here. +function expandProtocolYaml(source) { + const document = yaml.parseDocument(source, { merge: true, customTags: ['timestamp'] }); + if (document.errors.length) throw document.errors[0]; + const protocol = document.toJS({ mapAsMap: true }); + if (!(protocol instanceof Map)) { + throw new Error('The protocol YAML must contain a mapping'); + } + protocol.delete('templates'); + return yaml.stringify(protocol, { + aliasDuplicateObjects: false, + lineWidth: 0, + customTags: ['timestamp'], + // Keep date-like and other ambiguous strings quoted for js-yaml and Go. + compat: 'yaml-1.1', + }); +} + +function readExpandedProtocol(sourcePath = protocolYamlPath) { + return expandProtocolYaml(fs.readFileSync(sourcePath, 'utf8')); +} + +function writeExpandedProtocol(outDir, sourcePath = protocolYamlPath) { + const directory = path.join(outDir, 'files'); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync(path.join(directory, expandedProtocolFilename), readExpandedProtocol(sourcePath)); +} + +if (require.main === module) process.stdout.write(readExpandedProtocol()); + +module.exports = { expandProtocolYaml, readExpandedProtocol, writeExpandedProtocol, expandedProtocolFilename }; From 3b8b212f2a6d1bae191888d264fb3526466ddffa Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 18:04:13 +0000 Subject: [PATCH 20/24] Trim brittle documentation tests and assert specific diagnostics --- utils/MessageDocumentation.test.ts | 168 +++++++++++------------------ 1 file changed, 64 insertions(+), 104 deletions(-) diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 7b549167a..bfab8c3b0 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -116,9 +116,6 @@ describe('shared response conventions', () => { expect(protocol.header[4].values[-1]).toMatchObject({ name: 'Processing', id: 'error' }) expect(protocol.header[4].type).toBe('int8') }) - it('removes example-generation filler from message documentation', () => { - for (const id of [39, 58]) expect(JSON.stringify(protocol.messages[id])).not.toContain('Every generated request below') - }) }) describe('optional message documentation', () => { it('leaves legacy messages on their existing renderer', () => { @@ -217,9 +214,6 @@ describe('optional message documentation', () => { } expect(getDocumentationFormat(docs, docs.operations.find(item => item.method === 'UNSUBSCRIBE')!)).toBeUndefined() expect(getMessageDocumentation(protocol.messages[39], protocol)!.formats).toBeUndefined() - const syncParagraphs = docs.notes!.find(note => note.id === 'sync-lifecycle')!.description.trim().split('\n\n') - expect(syncParagraphs).toHaveLength(3) - expect(syncParagraphs.every(paragraph => !paragraph.includes('\n'))).toBe(true) }) it('rejects invalid numeric versions, labels and legacy flags', () => { @@ -279,10 +273,6 @@ describe('wire-version authoring', () => { expect(docs.formats![1].anchorId).toBe('legacy') expect(docs.formats![0].anchorId).toBe('current') expect(docs.formats![0].fields).toEqual({ 2: {}, 129: message.versions[2].fields[129] }) - for (const version of Object.values(message.versions) as any[]) { - expect(version.id).toBeUndefined() - expect(version.messageVersion).toBeUndefined() - } expect(protocol).toEqual(before) }) @@ -291,7 +281,6 @@ describe('wire-version authoring', () => { expect(gps.GET.request).toBeNull() expect(gps.GET.response).toEqual({ 1: null, 2: null }) expect(Object.keys(gps.SET.request)).toEqual(['2', '3']) - expect(gps.SET.request[2].description).toBe('Automatically controls the GPS module.') expect(gps.SET.response).toBeNull() for (const method of Object.values(protocol.messages[58].methods) as any[]) { expect(Object.prototype.hasOwnProperty.call(method || {}, 'request')).toBe(false) @@ -315,15 +304,15 @@ describe('wire-version authoring', () => { }) it('rejects malformed inline contexts before normalization can conceal them', () => { - for (const update of [ - (message: any) => { authoredInteraction(message, 'SET').request.fields[2] = null }, - (message: any) => { authoredInteraction(message, 'SET').request = 'broken' }, - (message: any) => { message.contexts = [] }, - (message: any) => { message.contexts = { tracking: null } }, - ]) { + for (const [diagnostic, update] of [ + ['request fields 2 must be an object', (message: any) => { authoredInteraction(message, 'SET').request.fields[2] = null }], + ['request must be an object', (message: any) => { authoredInteraction(message, 'SET').request = 'broken' }], + ['contexts must be a mapping', (message: any) => { message.contexts = [] }], + ['tracking context needs an exchange or versions', (message: any) => { message.contexts = { tracking: null } }], + ] as const) { const sample = clone(protocol) update(sample.messages[39]) - expect(validateMessageDocumentation(sample, 39).length).toBeGreaterThan(0) + expect(validateMessageDocumentation(sample, 39).join('\n')).toContain(diagnostic) } const sample = clone(protocol) authoredInteraction(sample.messages[58], 'GET').response.fields[2] = null @@ -596,9 +585,6 @@ describe('canonical inline interactions', () => { expect(response.fields?.[1]?.value).toBe(id) } const guide = readFileSync(resolve(__dirname, '../devices/api/protocol/responses.md'), 'utf8') - expect(guide).toContain('GSM Control SET') - expect(guide).toContain('SIM settings SET') - expect(guide).toContain('Device Status SUBSCRIBE/UNSUBSCRIBE') expect(guide).toContain('send no success ACK for an omitted or zero ID') expect(guide).toContain('error ACKs are not suppressed for this reason') expect(guide).toContain('do not establish a universal rule for every MT5 reply') @@ -693,33 +679,25 @@ describe('canonical inline interactions', () => { }) it.each([ - ['authored method', (source: any) => { source.method = 'SET' }], - ['site anchor', (source: any) => { source.anchorId = 'set' }], - ['nested revisions', (source: any) => { source.versions = { 1: {} } }], - ['invalid title', (source: any) => { source.title = 4 }], - ['missing wire version', (source: any) => { delete source.messageVersion }], - ['unknown wire version', (source: any) => { source.messageVersion = 99 }], - ['missing method selector', (source: any) => { delete source.request.headers[5] }], - ['unknown method selector', (source: any) => { source.request.headers[5].value = 99 }], - ['empty exchange', (source: any) => { delete source.request; delete source.response }], - ['unknown field', (source: any) => { source.request.fields[999] = {} }], - ['unknown message', (source: any) => { source.response.messageId = 65534 }], - ['conflicting byte bounds', (source: any) => { source.request.fields[129].minBytes = 1025 }], - ])('rejects %s in a flat interaction', (_label, change) => { + ['unknown property method', (source: any) => { source.method = 'SET' }], + ['unknown property anchorId', (source: any) => { source.anchorId = 'set' }], + ['unknown property versions', (source: any) => { source.versions = { 1: {} } }], + ['title must be a string', (source: any) => { source.title = 4 }], + ['needs an explicit messageVersion', (source: any) => { delete source.messageVersion }], + ['references unknown message version 99', (source: any) => { source.messageVersion = 99 }], + ['request needs a known Method value in header 5', (source: any) => { delete source.request.headers[5] }], + ['request needs a known Method value in header 5', (source: any) => { source.request.headers[5].value = 99 }], + ['needs at least one request, response or publication message', (source: any) => { delete source.request; delete source.response }], + ['references unknown fields id 999', (source: any) => { source.request.fields[999] = {} }], + ['references unknown message 65534', (source: any) => { source.response.messageId = 65534 }], + ['fields 129 has invalid minBytes', (source: any) => { source.request.fields[129].minBytes = 1025 }], + ])('reports %s in a flat interaction', (diagnostic, change) => { const sample = clone(protocol) change(sample.messages[58].interactions['replace-message-box']) - expect(validateMessageDocumentation(sample, 58).length).toBeGreaterThan(0) + expect(validateMessageDocumentation(sample, 58).join('\n')).toContain(diagnostic) }) - it('keeps site aliases and layout out of YAML while preserving published links', () => { - for (const message of Object.values(protocol.messages) as any[]) { - for (const source of Object.values(message.interactions || {}) as any[]) { - expect(source.anchorId).toBeUndefined() - expect(source.method).toBeUndefined() - expect(source.versions).toBeUndefined() - } - for (const note of message.notes || []) expect(note.placement).toBeUndefined() - } + it('preserves published links through title and format-label edits while rejecting site-only metadata', () => { const message = clone(protocol.messages[58]) const before = getMessageDocumentation(message, protocol)! message.versions[2].label = '2027-02' @@ -797,21 +775,21 @@ describe('canonical, version and interaction descriptions', () => { }) it.each([ - ['unknown field', (m: any) => { m.versions[2].fields[999] = { description: 'Unknown' } }], - ['non-numeric field', (m: any) => { m.versions[2].fields.first = { description: 'Unknown' } }], - ['non-object fields', (m: any) => { m.versions[2].fields = [] }], - ['non-object override', (m: any) => { m.versions[2].fields[1] = 'Prose' }], - ['non-string description', (m: any) => { m.versions[2].fields[1].description = 2 }], - ['missing description', (m: any) => { m.versions[2].fields[1] = {} }], - ['type override', (m: any) => { m.versions[2].fields[1].type = 'uint32' }], - ['presence override', (m: any) => { m.versions[2].fields[1].presence = 'required' }], - ['bounds override', (m: any) => { m.versions[2].fields[1].maxBytes = 5 }], - ['excluded version', (m: any) => { m.versions[1].fields = { 2: { description: 'Unavailable' } } }], - ['non-numeric version', (m: any) => { m.versions.latest = m.versions[2] }], - ])('rejects %s metadata', (_label, change) => { + ['2 version field 999 references unknown field', (m: any) => { m.versions[2].fields[999] = { description: 'Unknown' } }], + ['2 version field first references unknown field', (m: any) => { m.versions[2].fields.first = { description: 'Unknown' } }], + ['2 version fields must be a mapping', (m: any) => { m.versions[2].fields = [] }], + ['2 version field 1 must be an object', (m: any) => { m.versions[2].fields[1] = 'Prose' }], + ['2 version field 1 description must be a string', (m: any) => { m.versions[2].fields[1].description = 2 }], + ['2 version field 1 description must be a string', (m: any) => { m.versions[2].fields[1] = {} }], + ['2 version field 1 has unknown property type', (m: any) => { m.versions[2].fields[1].type = 'uint32' }], + ['2 version field 1 has unknown property presence', (m: any) => { m.versions[2].fields[1].presence = 'required' }], + ['2 version field 1 has unknown property maxBytes', (m: any) => { m.versions[2].fields[1].maxBytes = 5 }], + ['1 version field 2 is outside its versions', (m: any) => { m.versions[1].fields = { 2: { description: 'Unavailable' } } }], + ['invalid message version latest', (m: any) => { m.versions.latest = m.versions[2] }], + ])('reports %s in version metadata', (diagnostic, change) => { const sample = fixture() change(sample.messages[99]) - expect(validateMessageDocumentation(sample, 99).length).toBeGreaterThan(0) + expect(validateMessageDocumentation(sample, 99).join('\n')).toContain(diagnostic) }) it('keeps ID-bearing captures and wire definitions when a request omits redundant Message ID metadata', () => { @@ -834,16 +812,11 @@ describe('canonical, version and interaction descriptions', () => { }) describe('shared descriptions in the published specification', () => { - it('uses shared ID guidance and canonical GPS/error prose without redundant interaction entries', () => { - for (const message of Object.values(protocol.messages) as any[]) for (const interaction of Object.values(message.interactions || {}) as any[]) { - expect(interaction.request?.headers?.[1]).not.toEqual({}) - } - expect(protocol.header[1].description).toContain('including when it is a response or publication') + it('resolves canonical GPS field and error descriptions', () => { const gps = interactionView(39, 'read-gps-state') const fields = resolveDocumentationFields(protocol, protocol.messages[39], gps.response!.fields, 'fields') for (const id of [1, 2]) expect(fields.find(field => field.id === id)?.description).toBe(protocol.messages[39].data[id].description) expect(resolveDocumentationErrors(protocol, gps.errors).find(error => error.code === 7)?.description).toBe(protocol.header[4].values[7].description) - expect(interactionView(39, 'configure-gps').request?.fields?.[2]?.description).toContain('Omitting this field sets API-enabled corrections to disabled') }) it('shares Message Box version prose while preserving SET and tracking exceptions', () => { @@ -886,22 +859,19 @@ describe('canonical documentation errors', () => { }) describe('native YAML reuse', () => { - it('keeps shared headers global and repeated message payloads local', () => { - expect(Object.keys(protocol.templates.headers)).toEqual(['optionalOkReply', 'correlatedOkAck', 'optionalCorrelationAck']) - expect(protocol.templates.headers.optionalOkReply).toEqual({ 3: {}, 4: { value: 0 } }) - expect(protocol.templates.headers.correlatedOkAck).toEqual({ 3: { presence: 'required' }, 4: { presence: 'required', value: 0 } }) - expect(protocol.templates.headers.optionalCorrelationAck).toEqual({ 3: {}, 4: { presence: 'required', value: 0 } }) + it('preserves publication exceptions and message-specific subscription selectors', () => { const status = protocol.messages[34].interactions - expect(status['read-device-status'].response.fields).toBe(status['subscribe-device-status'].publication.fields) const box = protocol.messages[58].interactions - expect(box['read-message-box'].response.fields).toBe(box['subscribe-message-box'].publication.fields) - expect(box['read-message-box-v1'].response.fields).toBe(box['subscribe-message-box-v1'].publication.fields) - expect(box['replace-message-box'].response.fields).toBe(box['subscribe-message-box'].response.fields) - expect(box['replace-message-box'].response.fields).toBe(box['stop-message-box-subscription'].response.fields) expect(box['subscribe-message-box'].publication.headers[3].presence).toBe('omitted') expect(box['subscribe-message-box'].publication.headers[4]).toBeUndefined() expect(status['subscribe-device-status'].publication.headers[4].presence).toBe('omitted') - expect(validateProtocolInteractions(protocol)).toEqual([]) + const current = box['subscribe-message-box'].request.headers + const legacy = box['subscribe-message-box-v1'].request.headers + for (const id of [5, 6, 7, 16, 17]) expect(current[id]).toEqual(legacy[id]) + expect(current[22]).toEqual({ presence: 'required', value: 2 }) + expect(legacy[22].value).toBeUndefined() + expect(legacy[22].values).toHaveProperty('1') + expect(box['tracking-message-box-upload'].publication.fields).not.toEqual(box['read-message-box'].response.fields) }) it('expands both YAML parsers identically and does not mutate shared aliases during normalization', () => { @@ -912,6 +882,8 @@ describe('native YAML reuse', () => { expect(document.toJS()).toEqual(protocol) const sample = yaml.load(source) const before = clone(sample) + const status = sample.messages[34].interactions + expect(status['read-device-status'].response.fields).toBe(status['subscribe-device-status'].publication.fields) for (const id of [31, 33, 34, 35, 39, 58]) getMessageDocumentation(sample.messages[id], sample) expect(sample).toEqual(before) const docs = getMessageDocumentation(sample.messages[34], sample)! @@ -921,38 +893,26 @@ describe('native YAML reuse', () => { expect(docs.operations[1].publication!.fields![1].description).not.toBe('Local edit') }) - it('keeps message-specific subscription selectors outside shared header fragments', () => { - const box = protocol.messages[58].interactions - const current = box['subscribe-message-box'].request.headers - const legacy = box['subscribe-message-box-v1'].request.headers - for (const id of [5, 6, 7, 16, 17]) expect(current[id]).toEqual(legacy[id]) - expect(current[22]).toEqual({ presence: 'required', value: 2 }) - expect(legacy[22]).toBe(box['read-message-box-v1'].request.headers[22]) - expect(legacy[22].value).toBeUndefined() - expect(legacy[22].values).toHaveProperty('1') - expect(box['tracking-message-box-upload'].publication.fields).not.toEqual(box['read-message-box'].response.fields) - }) - it.each([ - ['non-object registry', (p: any) => { p.templates = null }], - ['unknown registry section', (p: any) => { p.templates.responses = {} }], - ['non-object header registry', (p: any) => { p.templates.headers = [] }], - ['invalid name', (p: any) => { p.templates.headers['Invalid name'] = {} }], - ['non-object header group', (p: any) => { p.templates.headers.unused = null }], - ['unknown header', (p: any) => { p.templates.headers.unused = { 999: {} } }], - ['null header usage', (p: any) => { p.templates.headers.unused = { 3: null } }], - ['unknown usage property', (p: any) => { p.templates.headers.unused = { 3: { type: 'uint8' } } }], - ['invalid presence', (p: any) => { p.templates.headers.unused = { 3: { presence: '' } } }], - ['invalid description', (p: any) => { p.templates.headers.unused = { 3: { description: false } } }], - ['invalid values shape', (p: any) => { p.templates.headers.unused = { 4: { values: [] } } }], - ['invalid value description', (p: any) => { p.templates.headers.unused = { 4: { values: { 0: null } } } }], - ['unknown value property', (p: any) => { p.templates.headers.unused = { 4: { values: { 0: { type: 'uint8' } } } } }], - ['unknown enum value', (p: any) => { p.templates.headers.unused = { 4: { value: 999 } } }], - ['invalid width', (p: any) => { p.templates.headers.unused = { 3: { maxBytes: -1 } } }], - ['conflicting bounds', (p: any) => { p.templates.headers.unused = { 3: { minBytes: 4, maxBytes: 1 } } }], - ])('rejects %s even when the template is unused', (_name, change) => { + ['Protocol templates must be a mapping', (p: any) => { p.templates = null }], + ['Protocol templates has unknown property responses', (p: any) => { p.templates.responses = {} }], + ['Protocol templates.headers must be a mapping', (p: any) => { p.templates.headers = [] }], + ['Protocol template Invalid name needs a stable name', (p: any) => { p.templates.headers['Invalid name'] = {} }], + ['Protocol template unused headers must be a mapping', (p: any) => { p.templates.headers.unused = null }], + ['Protocol template unused references unknown headers id 999', (p: any) => { p.templates.headers.unused = { 999: {} } }], + ['Protocol template unused headers 3 must be an object', (p: any) => { p.templates.headers.unused = { 3: null } }], + ['Protocol template unused headers 3 has unknown property type', (p: any) => { p.templates.headers.unused = { 3: { type: 'uint8' } } }], + ['Protocol template unused headers 3 has invalid presence', (p: any) => { p.templates.headers.unused = { 3: { presence: '' } } }], + ['Protocol template unused headers 3 description must be a string', (p: any) => { p.templates.headers.unused = { 3: { description: false } } }], + ['Protocol template unused headers 4 values must be a mapping', (p: any) => { p.templates.headers.unused = { 4: { values: [] } } }], + ['Protocol template unused headers 4 value 0 description must be a string or description mapping', (p: any) => { p.templates.headers.unused = { 4: { values: { 0: null } } } }], + ['Protocol template unused headers 4 value 0 has unknown property type', (p: any) => { p.templates.headers.unused = { 4: { values: { 0: { type: 'uint8' } } } } }], + ['Protocol template unused headers 4 references unknown value 999', (p: any) => { p.templates.headers.unused = { 4: { value: 999 } } }], + ['Protocol template unused headers 3 has invalid maxBytes', (p: any) => { p.templates.headers.unused = { 3: { maxBytes: -1 } } }], + ['Protocol template unused headers 3 has invalid minBytes', (p: any) => { p.templates.headers.unused = { 3: { minBytes: 4, maxBytes: 1 } } }], + ])('reports %s even when the template is unused', (diagnostic, change) => { const sample = clone(protocol) change(sample) - expect(validateProtocolInteractions(sample).some(error => error.startsWith('Protocol template'))).toBe(true) + expect(validateProtocolInteractions(sample).join('\n')).toContain(diagnostic) }) }) From 9ec28aa837ce99cf2ecaac49981763c41d988ddb Mon Sep 17 00:00:00 2001 From: addshore Date: Wed, 11 Nov 2026 18:07:54 +0000 Subject: [PATCH 21/24] Preserve resolved response header constraints in tests --- utils/MessageDocumentation.test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index bfab8c3b0..8186a9cbd 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -103,11 +103,14 @@ describe('shared response conventions', () => { expect(commonResponseHeaderIds({ headers: { '3': { presence: 'omitted' }, '4': { presence: 'required', value: 4 } } })).toEqual([]) expect(commonResponseHeaderIds({ headers: { '3': { presence: 'optional', description: 'A message-specific correlation rule.' }, '4': { presence: 'required', value: 0, maxBytes: 1 } } })).toEqual([]) }) - it('keeps MT58 version/payload rules and explicit publication correlation distinct', () => { + it('preserves response header requirements and MT58 version/payload rules', () => { const message = getMessageDocumentation(protocol.messages[58], protocol)! const get = getOperationVariant(message.operations.find(operation => operation.method === 'GET')!, '2') const subscribe = getOperationVariant(message.operations.find(operation => operation.method === 'SUBSCRIBE')!, '2') expect(commonResponseHeaderIds(get.response!)).toEqual(['3', '4']) + expect(get.response?.headers).toMatchObject({ 3: { presence: 'optional' }, 4: { presence: 'optional', value: 0 } }) + expect(interactionView(31, 'control-flight-mode').response?.headers).toMatchObject({ 3: { presence: 'required' }, 4: { presence: 'required', value: 0 } }) + expect(interactionView(58, 'replace-message-box').response?.headers).toMatchObject({ 3: { presence: 'optional' }, 4: { presence: 'required', value: 0 } }) expect(get.response?.headers?.['22']).toMatchObject({ presence: 'required', value: 2 }) expect(get.response?.fields?.['129']).toMatchObject({ presence: 'optional', maxBytes: 1024 }) expect(subscribe.publication?.headers?.['3'].presence).toBe('omitted') From 9ec31eeaa3898230300f8ea7f8e306efbdebf67d Mon Sep 17 00:00:00 2001 From: addshore Date: Thu, 12 Nov 2026 10:21:36 +0000 Subject: [PATCH 22/24] Refactor responses documentation for clarity and accuracy --- devices/api/protocol/responses.md | 158 ++++-------------------------- 1 file changed, 19 insertions(+), 139 deletions(-) diff --git a/devices/api/protocol/responses.md b/devices/api/protocol/responses.md index 769b86638..642f57c81 100644 --- a/devices/api/protocol/responses.md +++ b/devices/api/protocol/responses.md @@ -4,29 +4,23 @@ outline: [2,3] # Responses and acknowledgments -A request and its reply are separate frames, with separate headers and data fields. The operation's message page defines the reply type, payload and errors. This page explains the shared conventions; it does not mean every request receives the same kind of reply. - -Use the operation's required request headers. An omitted [Method (header 5)](./headers#5-method) is not a universal GET default; GPS Control and Message Box require an explicit method. +A request and its reply are separate frames, with separate headers and data fields. +The operation's message page defines the reply type, payload and errors. +This page explains the shared conventions; it does not mean every request receives the same kind of reply. ## Message IDs -[Message ID (header 1)](./headers#1-message-id) is a shared optional header for requests, responses and publications. Individual implementations, transports or client services can impose additional requirements. Send helpers may add an ID automatically; that is not a requirement to serialize one in every frame. - -- On a request, use a nonzero ID when acknowledgment or reply correlation is needed. The operation's reply rules still determine what is sent. -- On a response, an optional Message ID identifies the response itself. It is independent of [Response to (header 3)](./headers#3-response-to), which identifies the original request. Correlate using Response to, not the response's own ID. A response can contain both, either, or neither as permitted by its send path. -- Publications can also have their own IDs. An ID does not by itself make a publication a reply to a request. +[Message ID (header 1)](./headers#1-message-id) is a shared optional header for requests, responses, publications and message tracing. +Individual implementations, transports or client services can impose additional requirements. +Send helpers may add an ID automatically; that is not a requirement to serialize one in every frame. -The interaction YAML need not repeat an empty `1: {}` in every header list. It inherits this shared optional-ID convention; a local header-1 entry describes an actual requirement or exception. Omitting that entry is not an assertion that the wire frame lacks an ID. Separate ID-less interactions are unnecessary when only the shared acknowledgment or correlation rules differ. +- On a request, use a nonzero ID when acknowledgment or reply correlation is needed. +- On a response, an optional Message ID identifies the response itself. It is independent of [Response to (header 3)](./headers#3-response-to), which identifies the original request. ## Correlating a reply -Include a nonzero [Message ID (header 1)](./headers#1-message-id) when you need to match replies to requests. A correlated reply carries that ID in [Response to (header 3)](./headers#3-response-to), not as its own Message ID. - -For GPS Control GET and Message Box GET, a successful typed reply includes Response to and Status `0` only when the request has a nonzero Message ID. With an omitted or zero ID, both reply headers are omitted; the typed payload can still be returned. - -Device Status GET also returns its typed payload directly; Response to and Status may be omitted when the request has no nonzero Message ID. - -Response to can also identify a subscription in some message types. Do not assume every unsolicited update carries it: for example, Message Box publications use their subscription context rather than replying to the SUBSCRIBE request. +Include a nonzero [Message ID (header 1)](./headers#1-message-id) when you need to match replies to requests. +A correlated reply carries that ID in [Response to (header 3)](./headers#3-response-to). ## Typed responses and ACKs @@ -35,142 +29,28 @@ Replies can take these forms: - A typed response containing the requested data or result. Its message type is defined by the operation and need not always match the request type. - An [ACK (MT5)](../messages/5-ack), which reports the command result without implying that a message-specific data payload was returned. -An operation can send an interim ACK and a later typed result. Some targets also send a transport ACK alongside a typed response. An immediate typed response can replace a separate success ACK. [GPS Control GET](../messages/39-gps-control#message-39-operation-get) and [Message Box GET](../messages/58-message-box#message-58-operation-get) return their own typed payloads. Their SET operations use ACKs instead. +An operation can send an interim ACK and a later typed result. Some targets also send a transport ACK alongside a typed response. An immediate typed response can replace a separate success ACK. -An ACK can identify the original request through Response to and/or its **ACK Type data field (field 1)**. ACK Type is the original message **type**, not the request's Message ID. See the [MT5 packet format](../messages/5-ack#header) for its full schema. +An ACK can identify the original request through Response to and/or its **ACK Type data field (field 1)**. +ACK Type is the original message **type**, not the request's Message ID. +See the [MT5 packet format](../messages/5-ack#header) for its full schema. ### When an ACK is sent -Whether an ACK is sent depends on the operation and target. A missing or zero Message ID does not guarantee silence: typed replies and error replies may still be sent. Follow the message page's documented behavior. - -Do not turn success-ACK suppression into a universal no-ID rule. OPEN/CLOSE handling and transport-specific send paths can have different acknowledgment behavior. - -The following operation-specific conditions belong to this shared response reference, linked from each operation's response section: - -- [GSM Control SET](../messages/31-gsm-control#message-31-operation-control-flight-mode) (including network search), [SIM settings SET](../messages/33-sim-settings#message-33-operation-select-sim1) (both SIM choices), and [Device Status SUBSCRIBE/UNSUBSCRIBE](../messages/34-device-status#message-34-operation-subscribe) send a success MT5 ACK only when the request includes a nonzero Message ID. They send no success ACK for an omitted or zero ID. -- For a request with a nonzero Message ID, [GPS Control SET](../messages/39-gps-control#message-39-operation-set) and [Message Box SET](../messages/58-message-box#message-58-operation-set) return a success ACK rather than the message-specific payload. -- [Message Box SUBSCRIBE/UNSUBSCRIBE](../messages/58-message-box#message-58-operation-subscribe) suppress success ACKs for an omitted or zero Message ID; error ACKs are not suppressed for this reason. - -These conditions do not establish a universal rule for every MT5 reply. +Whether an ACK is sent depends on the operation and target, but generally speaking any message with an ID should be acked. +A missing or zero Message ID does not guarantee silence: typed replies and error replies may still be sent. +Follow the message page's documented behavior. ## Status and errors -[Status (header 4)](./headers#4-status) belongs to the reply's **header**, not its data fields: +[Status (header 4)](./headers#4-status) indicates a general reply status. - Omitted Status means OK. - `0` means OK. - Positive values indicate a non-OK result; some are retryable rather than terminal. The operation page explains the relevant causes. - `-1` means Processing, with further responses expected. A nonpositive value does not necessarily mean the operation has finished. -An unsuccessful command can use a different reply type from a successful one. The operation reference identifies that distinction. Do not assume every status-bearing frame is MT5: asynchronous subscription status messages can use the subscribed message type. - -A correlated reply is not necessarily a final result. If an operation promises a typed payload, a generic ACK is not that payload. Follow the operation's expected reply type and status. - -## Message format versions - -[Message Version (header 22)](./headers#22-message-version) identifies a **message's payload format**. It is separate from the outer protocol version, which remains V3. - -A request may select a format, and a response or publication may identify the format it carries. The message page defines supported values, defaults, required presence and invalid-value behavior. Header 22 is not an unconditional echo of the request and is not required on every reply. - -For example, current-format Message Box GET responses and publications carry header 22 with value `2`, but its MT5 control ACKs and terminal subscription status messages do not. Legacy Message Box responses omit it. [Message Box's format sections](../messages/58-message-box#message-58-format-current) describe those differences; the dates used as documentation format names do not replace numeric values on the wire. - - - -## Authoring interactions - -Usage definitions live inline at `messages[messageId].interactions`. Each stable key describes an exchange through `request`, direct successful `response` (including ACK where applicable), and/or later or unsolicited `publication` stages. Existing SDK consumers still use the retained method maps. - -```yaml -messages: - 58: - # Existing data fields and wire-version definitions remain here. - interactions: - replace-message-box: - title: Replace the cached message - messageVersion: 2 - request: - headers: - 5: {presence: required, value: 1} - 22: {presence: required, value: 2} - fields: - 129: {presence: required, maxBytes: 1024} - response: - messageId: 5 -``` - -`replace-message-box` is the stable key; its title can change without renaming the interaction. The request's Method header value `1` means SET, using the shared header enum. There is no second authored method label or interaction-revision layer. Documentation links and layout are maintained by the site code, not the protocol YAML. - -`messageVersion: 2` references the containing message's existing wire format. It does not insert header 22; each stage's headers describe what is sent. Unversioned controls omit `messageVersion`, even if other interactions on the same message use versioned payloads. Message Box's current `read-message-box` and legacy `read-message-box-v1` are separate interactions, as are `subscribe-message-box` and `subscribe-message-box-v1`. Keep their keys stable; do not silently change an existing key to refer to a different wire format. - -Stages inherit the containing message type unless they specify `messageId`, so the response above uses MT5. Field names, types, units, enums and descriptions come from that message's `data` and the shared `header` definitions. The uint8 type already gives header 22 its one-byte width; variable-size payload bounds such as `maxBytes: 1024` remain meaningful. Keep explicit selector behavior: legacy Message Box GET/SUBSCRIBE accepts omitted, zero or malformed-width selectors as version 1, and legacy responses omit header 22. - -Payload descriptions inherit in this order: the canonical `data[fieldId].description`, an optional `versions[messageVersion].fields[fieldId].description`, then an explicit interaction-stage description. For example, a wire version can describe its cached-payload meaning once: - -```yaml -versions: - 2: - label: "2026-10" - fields: - 129: - description: Complete cached payload. Empty payload data is omitted when returned or published. -``` - -Both the version's field reference and its interactions inherit this text. An interaction can still override it when SET clears the cache or an upload carries independent bytes. Version overrides change descriptions only: they do not change field types, presence, limits, or participation. They apply only to that message's fields, never to a different response type such as MT5. Unversioned interactions use the canonical description. Migrated interactions do not inherit descriptions from the legacy SDK method maps. - -A publication-only interaction needs no method or request. This shortened example describes the existing tracking upload: - -```yaml -messages: - 58: - interactions: - tracking-message-box-upload: - title: Tracking-session uploads - messageVersion: 2 - publication: - headers: - 22: {presence: required, value: 2} - fields: - 129: - description: Independent Transmit Now upload data. -``` - -Request mappings list expected inputs, optional by default; mark required inputs explicitly. Message ID follows the shared rule above and does not need a repeated empty entry. Leave unrelated inputs out, and keep important ignored or rejected input behavior in concise descriptions. An unlisted input is not a statement that firmware ignores, rejects or accepts it. Response and publication mappings can still mark omitted fields where wire-format or correlation differences matter. Write field descriptions only where the meaning differs. - -An error entry needs only its status `code` to inherit the name and general description from header 4. Add `description` only for an operation-specific cause, without repeating the status name. For example, `{code: 7}` inherits Not Supported; `{code: 4, description: "A decoded Message Version value above 2."}` explains a particular Invalid Parameter case. These entries describe applicable errors, not a list of every status a transport might report. - -Documentation method lists are derived from request header 5, with validation requiring a known selector for each request. An absent selector is not inferred as GET. Existing method-keyed SDK request/response maps remain unchanged, with validation requiring their method names to match the interactions for migrated messages. Multiple interactions may use one method, and publication-only interactions add none. Removing or regenerating the SDK maps is a separate migration. - -GET, SET and SUBSCRIBE are values of Method header 5, not separate wire structures. An explicit selector in a documented interaction does not establish that every message requires it: LED controls, for example, can default to SET when Method is omitted. A message- or operation-specific header limit belongs with that use, rather than changing the shared header definition for all messages. - -An interaction describes an exchange, not arbitrary ordered sequences of requests. Applicability can be narrowed with `target` without making fields required. Its stages remain subject to the correlation, suppression and target rules above; defining a response does not guarantee it is sent. - -### Reusing YAML fragments - -Use native YAML anchors for repeated usage maps. Keep message-specific fragments at their first use within that message, with descriptive names such as `messageBoxV1Fields`. Only genuinely cross-message header groups belong in the global `templates.headers` catalog, before `messages`. These are authoring helpers, not additional wire headers or rules that apply automatically. - -A complete map can be reused with an alias, for example `fields: *messageBoxV1Fields`. Merge a shared header group when the stage also needs local entries: - -```yaml -templates: - headers: - optionalOkReply: &optionalOkReplyHeaders - 3: {} - 4: {value: 0} - -# Inside a Message Box v2 GET response: -response: - headers: - <<: *optionalOkReplyHeaders - 22: {presence: required, value: 2} -``` - -Multiple maps can be combined with one merge entry, `<<: [*specificHeaders, *baseHeaders]`. Earlier maps win conflicts, and explicitly written local keys override all merged maps. Merging is shallow: replacing `headers` replaces the whole header map, and replacing header `4` replaces that whole usage entry. Merge again at the level being changed, or restate the small entry. Arrays do not concatenate, and `null` does not delete a key. - -Define anchors before their aliases in the same document. For a message-local subset, the first use can define it directly under `<<: &messageBoxSubscriptionHeaders`; keep format-specific header 22 outside that subset. Do not reuse the cached-payload field map for independent uploads, or assume every publication omits the same headers. Keep short method selectors explicit rather than adding an anchor for every one-line value. - -To inspect the complete specification without following aliases, use the [expanded YAML download](./#yaml-specification). - -The site resolves native aliases and merges before validating the expanded interactions. It also validates unused global header templates, so a typo cannot remain hidden until a later use. Consumers using another YAML parser must enable merge-key support. Exporters should preserve the authored source or consume the expanded copy; writing typed data back to YAML may discard anchors and documentation metadata. +An unsuccessful command can use a different reply type from a successful one. ## Subscription replies and later updates From d379e75cfea43d3748e9f470b3a03cecab7b463d Mon Sep 17 00:00:00 2001 From: addshore Date: Thu, 12 Nov 2026 10:22:42 +0000 Subject: [PATCH 23/24] Delete YAML specification from protocol index --- devices/api/protocol/index.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/devices/api/protocol/index.md b/devices/api/protocol/index.md index 77c8bdfc0..593c2bf38 100644 --- a/devices/api/protocol/index.md +++ b/devices/api/protocol/index.md @@ -14,13 +14,6 @@ The protocol is designed to be: - Lightweight to store and transmit - Usable in a variety of settings, without complex or bloated dependencies -## YAML specification - -[Canonical YAML source](/files/protocol-v3.yaml) uses native YAML anchors and merge keys for repeated definitions. - -Download expanded YAML for the complete specification with aliases and merge keys resolved and the authoring-only `templates` registry removed. This export preserves the authored message versions and metadata; it does not apply runtime defaults or copy inherited descriptions into version overrides. Comments and source formatting are not retained. - - ## Byte Breakdown In a byte stream, you may receive a series of messages. From dbe5b15b00401108acffa980ab2c3f7aeff104d2 Mon Sep 17 00:00:00 2001 From: addshore Date: Thu, 12 Nov 2026 10:28:28 +0000 Subject: [PATCH 24/24] test: remove assertions for removed protocol prose and examples --- utils/MessageDocumentation.test.ts | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/utils/MessageDocumentation.test.ts b/utils/MessageDocumentation.test.ts index 8186a9cbd..144094ddc 100644 --- a/utils/MessageDocumentation.test.ts +++ b/utils/MessageDocumentation.test.ts @@ -556,29 +556,7 @@ describe('canonical inline interactions', () => { expect(interactionView(33, 'select-sim2').request?.fields?.[2]?.minBytes).toBe(1) }) - it('validates both published authoring examples against the existing wire definitions', () => { - const guide = readFileSync(resolve(__dirname, '../devices/api/protocol/responses.md'), 'utf8') - const snippets = [...guide.matchAll(/```yaml\n([\s\S]*?)```/g)].map(match => yaml.load(match[1])) - const examples = snippets.filter(snippet => snippet.messages).map(snippet => snippet.messages[58]) - const versionExample = snippets.find(snippet => snippet.versions) - expect(versionExample).toBeDefined() - const versionSample = clone(protocol) - versionSample.messages[58].versions[2] = versionExample.versions[2] - expect(validateMessageDocumentation(versionSample, 58)).toEqual([]) - expect(examples).toHaveLength(2) - for (const example of examples) { - const sample = clone(protocol) - const methods = Object.fromEntries(getDocumentationMethods(example, protocol).map(method => [method, null])) - sample.messages[58] = { ...sample.messages[58], ...example, methods } - expect(validateMessageDocumentation(sample, 58)).toEqual([]) - for (const source of Object.values(example.interactions) as any[]) { - expect(source.versions).toBeUndefined() - expect(source.messageVersion).toBe(2) - } - } - }) - - it('keeps ACK schemas local and operation-specific suppression in the linked response reference', () => { + it('keeps ACK schemas local to each operation', () => { for (const [id, names] of [ [31, ['control-flight-mode', 'start-search']], [33, ['select-sim1', 'select-sim2']], @@ -587,10 +565,6 @@ describe('canonical inline interactions', () => { expect(response.messageId).toBe(5) expect(response.fields?.[1]?.value).toBe(id) } - const guide = readFileSync(resolve(__dirname, '../devices/api/protocol/responses.md'), 'utf8') - expect(guide).toContain('send no success ACK for an omitted or zero ID') - expect(guide).toContain('error ACKs are not suppressed for this reason') - expect(guide).toContain('do not establish a universal rule for every MT5 reply') }) it('uses inline interactions as the only documentation source without mutating wire definitions', () => {