@springfield/ham-radio-utils 3.2.6 → 4.0.0

package/dist/schemas/radio-protocol-schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Radio Protocol DSL Schema",
-  "description": "Schema for defining radio communication protocols in a declarative JSON format",
+  "description": "Schema for defining radio communication protocols as send/expect exchanges",
   "type": "object",
   "required": [
     "id",
@@ -169,7 +169,7 @@
               },
               "endAddress": {
                 "type": "integer",
-                "description": "Ending address (inclusive) of the memory segment",
+                "description": "Inclusive ending address of the memory segment",
                 "minimum": 0
               }
             }
@@ -194,358 +194,192 @@
   },
   "definitions": {
     "protocolStep": {
-      "type": "object",
-      "description": "A single protocol step",
+      "description": "A single protocol step: an exchange, a chunked read, or a chunked write",
       "oneOf": [
         {
-          "type": "object",
-          "required": [
-            "sendReceive"
-          ],
-          "properties": {
-            "sendReceive": {
-              "$ref": "#/definitions/sendReceiveStep"
-            }
-          }
+          "$ref": "#/definitions/readStep"
         },
         {
-          "type": "object",
-          "required": [
-            "send"
-          ],
-          "properties": {
-            "send": {
-              "$ref": "#/definitions/sendStep"
-            }
-          }
+          "$ref": "#/definitions/writeStep"
         },
         {
-          "type": "object",
-          "required": [
-            "receive"
-          ],
-          "properties": {
-            "receive": {
-              "$ref": "#/definitions/receiveStep"
-            }
-          }
+          "$ref": "#/definitions/exchangeStep"
+        }
+      ]
+    },
+    "byteToken": {
+      "description": "A send/expect token: a byte, hex string (0x50), ASCII opcode (S), or placeholder ($address)",
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 255
         },
         {
-          "type": "object",
-          "required": [
-            "readSegment"
-          ],
-          "properties": {
-            "readSegment": {
-              "$ref": "#/definitions/readSegmentStep"
-            }
-          }
+          "type": "string",
+          "minLength": 1
+        }
+      ]
+    },
+    "sendData": {
+      "type": "array",
+      "description": "Bytes and placeholders to send",
+      "items": {
+        "$ref": "#/definitions/byteToken"
+      }
+    },
+    "expect": {
+      "description": "Expected serial reply: exact byte(s), opaque length, or a framed pattern",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/byteToken"
         },
         {
-          "type": "object",
-          "required": [
-            "writeSegment"
-          ],
-          "properties": {
-            "writeSegment": {
-              "$ref": "#/definitions/writeSegmentStep"
-            }
-          }
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/byteToken"
+          },
+          "minItems": 1
         },
         {
           "type": "object",
           "required": [
-            "setVariable"
+            "bytes"
           ],
+          "additionalProperties": false,
           "properties": {
-            "setVariable": {
-              "$ref": "#/definitions/setVariableStep"
+            "bytes": {
+              "type": "integer",
+              "description": "Accept any content of this many bytes",
+              "minimum": 1
             }
           }
         }
       ]
     },
-    "sendReceiveStep": {
+    "exchangeStep": {
       "type": "object",
-      "description": "Send data and receive response",
-      "required": [
-        "send",
-        "receive"
+      "description": "Send bytes and/or wait for a reply",
+      "anyOf": [
+        {
+          "required": [
+            "send"
+          ]
+        },
+        {
+          "required": [
+            "expect"
+          ]
+        }
       ],
+      "additionalProperties": false,
       "properties": {
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the step"
+        },
         "send": {
           "$ref": "#/definitions/sendData"
         },
-        "receive": {
-          "$ref": "#/definitions/receiveConfig"
+        "expect": {
+          "$ref": "#/definitions/expect"
         },
         "timeout": {
           "type": "integer",
           "description": "Timeout in milliseconds",
           "minimum": 1,
           "default": 5000
-        },
-        "description": {
-          "type": "string",
-          "description": "Human-readable description of the step"
         }
       }
     },
-    "sendStep": {
+    "readStep": {
       "type": "object",
-      "description": "Send data only",
+      "description": "Chunked memory read",
       "required": [
-        "data"
+        "read"
       ],
+      "additionalProperties": false,
       "properties": {
-        "data": {
-          "$ref": "#/definitions/sendData"
-        },
         "description": {
           "type": "string",
           "description": "Human-readable description of the step"
-        }
-      }
-    },
-    "receiveStep": {
-      "type": "object",
-      "description": "Receive data only",
-      "required": [
-        "type",
-        "length"
-      ],
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": [
-            "exact",
-            "variable",
-            "pattern",
-            "any"
-          ],
-          "description": "Type of receive operation"
-        },
-        "value": {
-          "type": "integer",
-          "description": "Expected value for exact match",
-          "minimum": 0,
-          "maximum": 255
-        },
-        "length": {
-          "type": "integer",
-          "description": "Expected length in bytes",
-          "minimum": 1
         },
-        "pattern": {
-          "type": "array",
-          "description": "Pattern for structured responses",
-          "items": {
-            "oneOf": [
-              {
-                "type": "string",
-                "description": "Literal value (1 byte)"
-              },
-              {
-                "type": "number",
-                "description": "Literal value (1 byte)"
+        "read": {
+          "type": "object",
+          "required": [
+            "segments",
+            "send",
+            "expect"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "segments": {
+              "type": "array",
+              "description": "Memory segment names to read",
+              "items": {
+                "type": "string"
               },
-              {
-                "type": "object",
-                "required": [
-                  "field",
-                  "size"
-                ],
-                "properties": {
-                  "field": {
-                    "type": "string",
-                    "description": "Field name for extracted data"
-                  },
-                  "size": {
-                    "type": "integer",
-                    "description": "Size in bytes (0 for variable length)",
-                    "minimum": 0
-                  }
-                }
-              }
-            ]
-          }
-        },
-        "description": {
-          "type": "string",
-          "description": "Human-readable description of the step"
-        }
-      }
-    },
-    "readSegmentStep": {
-      "type": "object",
-      "description": "Read memory segments",
-      "required": [
-        "segments",
-        "startChunk",
-        "endChunk"
-      ],
-      "properties": {
-        "segments": {
-          "type": "array",
-          "description": "List of segment names to read",
-          "items": {
-            "type": "string"
+              "minItems": 1
+            },
+            "send": {
+              "$ref": "#/definitions/sendData"
+            },
+            "expect": {
+              "$ref": "#/definitions/expect"
+            },
+            "ack": {
+              "$ref": "#/definitions/exchangeStep",
+              "description": "Optional exchange after each chunk"
+            },
+            "timeout": {
+              "type": "integer",
+              "description": "Timeout in milliseconds for each chunk exchange",
+              "minimum": 1
+            }
           }
-        },
-        "startChunk": {
-          "$ref": "#/definitions/sendReceiveStep",
-          "description": "Protocol for starting a chunk read"
-        },
-        "endChunk": {
-          "$ref": "#/definitions/sendReceiveStep",
-          "description": "Protocol for ending a chunk read"
-        },
-        "description": {
-          "type": "string",
-          "description": "Human-readable description of the step"
         }
       }
     },
-    "writeSegmentStep": {
+    "writeStep": {
       "type": "object",
-      "description": "Write memory segments",
+      "description": "Chunked memory write",
       "required": [
-        "segments",
-        "send",
-        "data",
-        "receive"
+        "write"
       ],
+      "additionalProperties": false,
       "properties": {
-        "segments": {
-          "type": "array",
-          "description": "List of segment names to write",
-          "items": {
-            "type": "string"
-          }
-        },
-        "send": {
-          "$ref": "#/definitions/sendData",
-          "description": "Data to send for write command"
-        },
-        "data": {
-          "type": "string",
-          "description": "Expression for segment data to write"
-        },
-        "receive": {
-          "$ref": "#/definitions/receiveConfig",
-          "description": "Expected response for write command"
-        },
         "description": {
           "type": "string",
           "description": "Human-readable description of the step"
-        }
-      }
-    },
-    "setVariableStep": {
-      "type": "object",
-      "description": "Set a variable value",
-      "required": [
-        "name",
-        "value"
-      ],
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "Variable name"
         },
-        "value": {
-          "oneOf": [
-            {
-              "type": "string",
-              "description": "Expression or literal value"
-            },
-            {
-              "type": "number",
-              "description": "Numeric value"
-            }
-          ],
-          "description": "Value to assign to the variable"
-        }
-      }
-    },
-    "sendData": {
-      "type": "array",
-      "description": "Array of data to send",
-      "items": {
-        "oneOf": [
-          {
-            "type": "string",
-            "description": "String literal or expression"
-          },
-          {
-            "type": "number",
-            "description": "Numeric literal or expression",
-            "minimum": 0,
-            "maximum": 255
-          }
-        ]
-      }
-    },
-    "receiveConfig": {
-      "type": "object",
-      "description": "Configuration for receiving data",
-      "required": [
-        "type"
-      ],
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": [
-            "exact",
-            "variable",
-            "pattern",
-            "any"
+        "write": {
+          "type": "object",
+          "required": [
+            "segments",
+            "send",
+            "expect"
           ],
-          "description": "Type of receive operation"
-        },
-        "value": {
-          "type": "integer",
-          "description": "Expected value for exact match",
-          "minimum": 0,
-          "maximum": 255
-        },
-        "length": {
-          "type": "integer",
-          "description": "Expected length in bytes",
-          "minimum": 1
-        },
-        "pattern": {
-          "type": "array",
-          "description": "Pattern for structured responses",
-          "items": {
-            "oneOf": [
-              {
-                "type": "string",
-                "description": "Literal value (1 byte)"
-              },
-              {
-                "type": "number",
-                "description": "Literal value (1 byte)"
+          "additionalProperties": false,
+          "properties": {
+            "segments": {
+              "type": "array",
+              "description": "Memory segment names to write",
+              "items": {
+                "type": "string"
               },
-              {
-                "type": "object",
-                "required": [
-                  "field",
-                  "size"
-                ],
-                "properties": {
-                  "field": {
-                    "type": "string",
-                    "description": "Field name for extracted data"
-                  },
-                  "size": {
-                    "type": "integer",
-                    "description": "Size in bytes (0 for variable length)",
-                    "minimum": 0
-                  }
-                }
-              }
-            ]
+              "minItems": 1
+            },
+            "send": {
+              "$ref": "#/definitions/sendData"
+            },
+            "expect": {
+              "$ref": "#/definitions/expect"
+            },
+            "timeout": {
+              "type": "integer",
+              "description": "Timeout in milliseconds for each chunk exchange",
+              "minimum": 1
+            }
           }
         }
       }

package/dist/utils/ui-logger.d.ts

@@ -5,20 +5,6 @@ import type { ILogLayer } from 'loglayer';
  * This module provides a specialized logger for capturing command-level information
  * that can be easily parsed and displayed in a UI. It captures details about
  * commands, data sent, data expected, and data received in a structured format.
- *
- * Purpose:
- * - Captures command-level information for UI display
- * - Provides structured JSON logging for easy parsing
- * - Tracks command execution details including timing
- * - Supports protocol debugging in UI environments
- * - Maintains separation from debug logging
- *
- * Design Rationale:
- * - Single log entry per command provides clean UI display
- * - JSON structure enables easy parsing and filtering
- * - Command-level granularity is appropriate for UI debugging
- * - Structured data supports rich UI representations
- * - Separate from debug logging avoids UI noise
  */
 interface ProtocolContext {
     variables?: Map<string, unknown>;

package/dist/utils/ui-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui-logger.d.ts","sourceRoot":"","sources":["../../src/utils/ui-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,UAAU,eAAe;IACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA0BrD;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,iBAAiB,CAA6B;IAEtD,YAAY,MAAM,EAAE,SAAS,EAE5B;IAGD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAmBjG;IAGD,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAwChI;IAGD,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAiC9I;IAED,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,eAAe;CAoBxB"}
+{"version":3,"file":"ui-logger.d.ts","sourceRoot":"","sources":["../../src/utils/ui-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;GAMG;AAEH,UAAU,eAAe;IACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKrD;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,iBAAiB,CAA6B;IAEtD,YAAY,MAAM,EAAE,SAAS,EAE5B;IAGD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAmBjG;IAGD,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAoChI;IAGD,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CA+B9I;IAED,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,eAAe;CAgBxB"}

package/dist/utils/ui-logger.js

@@ -1,20 +1,4 @@
-/**
- * Type guards for protocol step properties
- */
 const hasDescription = (obj) => typeof obj === 'object' && obj !== null && 'description' in obj && typeof obj.description === 'string';
-const hasReceive = (obj) => typeof obj === 'object' && obj !== null && 'receive' in obj;
-const hasEndChunk = (obj) => typeof obj === 'object' &&
-    obj !== null &&
-    'endChunk' in obj &&
-    typeof obj.endChunk === 'object' &&
-    obj.endChunk !== null &&
-    'receive' in obj.endChunk;
-const hasStartChunk = (obj) => typeof obj === 'object' &&
-    obj !== null &&
-    'startChunk' in obj &&
-    typeof obj.startChunk === 'object' &&
-    obj.startChunk !== null &&
-    'receive' in obj.startChunk;
 /**
  * UI Logger for capturing command-level information for UI display
  */
@@ -51,13 +35,10 @@ export class UILogger {
         const duration = endTime - startTime;
         const commandType = this.getCommandType(step);
         const description = this.getStepDescription(step);
-        // Extract sent and received data from context
         const dataSent = context.variables && context.variables.get('lastSentData');
         const dataReceived = context.variables && context.variables.get('lastReceivedData');
         const dataExpected = this.getExpectedData(step);
-        // For readSegment, also extract chunk logs if present
-        const dataChunks = commandType === 'readSegment' && context.variables && context.variables.get('lastReadSegmentChunks');
-        // Convert dataSent and dataReceived to byte array format if they exist
+        const dataChunks = commandType === 'read' && context.variables && context.variables.get('lastReadSegmentChunks');
         // eslint-disable-next-line unicorn/prefer-spread
         const dataSentArray = dataSent && Array.from(dataSent);
         // eslint-disable-next-line unicorn/prefer-spread
@@ -88,10 +69,8 @@ export class UILogger {
         const duration = endTime - startTime;
         const commandType = this.getCommandType(step);
         const description = this.getStepDescription(step);
-        // Extract sent data from context
         const dataSent = context.variables && context.variables.get('lastSentData');
         const dataExpected = this.getExpectedData(step);
-        // Convert dataSent to byte array format if it exists
         // eslint-disable-next-line unicorn/prefer-spread
         const dataSentArray = dataSent && Array.from(dataSent);
         this.logger
@@ -112,61 +91,36 @@ export class UILogger {
             .info('Command failed');
     }
     getCommandType(step) {
-        if ('sendReceive' in step) {
-            return 'sendReceive';
-        }
-        if ('send' in step) {
-            return 'send';
-        }
-        if ('receive' in step) {
-            return 'receive';
-        }
-        if ('readSegment' in step) {
-            return 'readSegment';
+        if ('read' in step) {
+            return 'read';
         }
-        if ('writeSegment' in step) {
-            return 'writeSegment';
+        if ('write' in step) {
+            return 'write';
         }
-        if ('setVariable' in step) {
-            return 'setVariable';
+        if ('send' in step || 'expect' in step) {
+            return 'exchange';
         }
         return 'unknown';
     }
     getStepDescription(step) {
-        if ('sendReceive' in step && hasDescription(step.sendReceive)) {
-            return step.sendReceive.description;
-        }
-        if ('send' in step && hasDescription(step.send)) {
-            return step.send.description;
-        }
-        if ('receive' in step && hasDescription(step.receive)) {
-            return step.receive.description;
-        }
-        if ('readSegment' in step && hasDescription(step.readSegment)) {
-            return step.readSegment.description;
-        }
-        if ('writeSegment' in step && hasDescription(step.writeSegment)) {
-            return step.writeSegment.description;
+        if (hasDescription(step)) {
+            return step.description;
         }
         return 'No description';
     }
     getExpectedData(step) {
-        if ('sendReceive' in step && hasReceive(step.sendReceive)) {
-            return step.sendReceive.receive;
+        if ('read' in step && typeof step.read === 'object' && step.read !== null && 'expect' in step.read) {
+            const read = step.read;
+            return {
+                expect: read.expect,
+                ack: read.ack?.expect,
+            };
         }
-        if ('receive' in step) {
-            return step.receive;
+        if ('write' in step && typeof step.write === 'object' && step.write !== null && 'expect' in step.write) {
+            return step.write.expect;
         }
-        if ('readSegment' in step) {
-            // For readSegment, return both start and end chunk receive patterns
-            const { readSegment } = step;
-            if (hasEndChunk(readSegment) && hasStartChunk(readSegment)) {
-                return {
-                    endChunk: readSegment.endChunk.receive,
-                    startChunk: readSegment.startChunk.receive,
-                    type: 'readSegment',
-                };
-            }
+        if ('expect' in step) {
+            return step.expect;
         }
         return {};
     }