Binary Status

Binary status polling in Koheron V1 firmware.
Firmware V1 documentation ยท V1.0-rc54-2d701ce

Koheron products currently ship with firmware V0.x by default. Firmware V1 is under active development and is not publicly available yet.

Contact us if you would like early access or want to evaluate V1 firmware on your device.

V1 firmware can provide compact binary status updates for host software that needs lower overhead than repeated ASCII status commands. Binary status is available only on products that include the binary status commands.

Commands

Command Description
% Return a size-prefixed complete active snapshot or a delta relative to a supplied CRC.
fmt% Print the active field list and format characters.
fmtlist Print the complete supported binary status field list.
stmsk Read or set the active binary status mask.
logerr Return the last error snapshot as a full unmasked binary status frame, when implemented.

Host workflow

  1. Read fmtlist to discover the complete field order and format characters.
  2. Read stmsk to discover the active fields.
  3. Send % for a complete active snapshot.
  4. Retain the snapshot and its CRC, then send %ABCD for subsequent updates, where ABCD is the returned CRC as four hexadecimal characters.
  5. Repeat discovery and request a complete snapshot after changing stmsk.

fmt% describes the active status fields used by the % protocol. Its final crc16 H entry is not represented by a changed-mask bit: % sends the state CRC separately after the changed values.

Dedicated compact protocol

Terminate either request with CR or LF:

%
%ABCD

The CRC is optional, exactly four case-insensitive hexadecimal characters, without 0x. No CRC requests a full response. A matching retained CRC permits a delta; an unknown CRC produces a full response. Malformed requests are discarded without a response. Overflow or recovery of a compact % request is also silent and emits no prompt.

Unlike ordinary CLI commands, % is a dedicated binary transaction. Its input is not echoed, and its response has no leading CR or LF, trailing CR or LF, prompt, or terminator after the state CRC. Ordinary CLI commands retain their textual echo and framing.

Offset Size Description
0 1 Payload length in bytes, excluding this byte
1 8 Changed-field mask, little-endian
9 N Changed field values
9 + N 2 State CRC, little-endian 
payload_length = 8 + changed_values_size + 2
frame_length   = 1 + payload_length

The changed mask is always 64 bits. Its bit positions use the global field indices reported by fmtlist, and only fields enabled by stmsk may be set. Changed values use their documented binary types and are serialized little-endian in ascending global field-index order. fmt% lists the active fields and their types but does not renumber changed-mask bits. The final CRC is a binary state CRC, not textual hexadecimal.

The state CRC uses CRC-16/CCITT-FALSE with polynomial 0x1021 and initial value 0xffff. It covers the little-endian active mask followed by every active field's exact bytes in order. It does not cover the changed mask or the final crc16 format member. Exact byte comparison, including floating-point representation, determines changes.

When the supplied CRC is current, the response has a zero changed mask. When it matches the retained baseline, the response contains only changed fields. An unknown CRC produces a complete snapshot. A successful stmsk change invalidates the retained baseline.

A host must read one length byte, validate it, read exactly that many more bytes, and treat the frame as complete immediately. After validating and decoding it, issue the next request without waiting for a prompt. Keep one request in flight. Retain a complete cache and commit a delta only after validating the complete-state CRC. Broadcast % requests receive no response; a directly addressed request for the device returns one compact frame, and requests addressed elsewhere return nothing.

Examples

A zero-value delta has payload_length = 10, frame_length = 11, and changed_mask = 0x0000000000000000.

For a 64-bit tms at bit 3, a tms-only delta has payload_length = 18, frame_length = 19, and changed_mask = 0x0000000000000008:

payload=18 frame=19 mask=0x0000000000000008 crc=0xCC66 tms=127927

For example, if bit 0 is a one-byte value and bit 3 is the eight-byte tms, changing both produces mask 0x0000000000000009. The bit-0 value precedes tms; the changed-values size is 9 bytes, so the payload is 19 bytes and the complete frame is 20 bytes.

Migration: Binary status and the compact % protocol are new in V1. V0.x applications have no binary-status format to reuse; implement V1 field discovery and decoding in the host software.

Host polling guidance

A host polling client should discover fields with fmtlist, read stmsk, validate every complete-state CRC, and resynchronize after protocol errors. These ordinary text discovery commands use the V1 > prompt; compact % responses have no prompt. Configure the host connection for the device's serial port, baud rate, and timeout, and follow the framing rules above when reading each binary response.

logerr provides an independent diagnostic snapshot. Decode it using the complete layout printed by fmtlist.