Protocol notes: what is known, how the toolkit discovers the rest

Known from the OEM manual

• Physical: DB9F on the AC supply module, pins 2 (vent TX), 3 (vent RX), 5 (GND). MAX232 levels.
• Link: 2400 or 1200 baud, 8N1, no handshake (OEM calibration software requirement).
• Behaviour: unsolicited stream. "Switch, control, and alarm information is monitored and updated every second. Pressure signals are updated every 100-milliseconds." "Control signals allow servicing personnel to perform factory-level device calibrations."
• OEM program behaviour (754M manual §14): on start it "resets" the COM ports, the RT-200 and "Vent754" (so there is an initialisation exchange); F5 toggles a Hold state in which the LCD shows FACTORY CALIBRATION and the unit stops cycling; F3 initialises EEPROM and resets the RTC; data points are sent to the ventilator ("Last Data Sent to Vent754" field); EEPROM protection changes need a physical pushbutton; releasing Hold reboots the unit.
• Not known: framing, checksum, command bytes. Impact only released them in writing on request.

How analyze recovers framing

1. Gap framing. Bytes are timestamped as they arrive (reader polls with a 50 ms timeout and reads everything pending). Gaps longer than 3 character times (12.5 ms at 2400 baud, floor 8 ms to tolerate USB latency) split frames. The 100 ms pressure cadence leaves ~75 ms of silence between frames, so this is robust.
2. Classes. Frames are grouped by (first byte, length). The median interval of each class is matched against the manual's 100 ms / 1 s periods to label pressure and status.
3. Fields. Byte positions that never change within a class are structure (sync, type, length); positions that change are data. In the pressure class the position with the largest variance is the pressure value (shown as the P? sparkline in monitor).
4. Checksum. For each class, 18 common algorithms (8-bit sum, two's/one's complement sum, XOR, CRC-8, 16-bit sums, CRC-16 CCITT/XMODEM/MODBUS/ARC in both byte orders, ASCII-hex sums) are tested over three payload start offsets and three trailer lengths. Anything matching ≥90 % of frames is reported, simplest first.
5. ASCII protocols are detected by printable ratio and re-split on CR/LF; sample lines are shown.

If the stream is ASCII (some 1990s Impact firmware printed text for a serial printer) the fields are usually self-describing; if binary, correlate varying bytes with the LCD (change rate, VT, mode; squeeze the test lung) and name them in the draft protocol JSON.

Capture file format

JSON Lines. Header record, then {"t": seconds, "d": direction, "x": hex} and {"t": …, "d": "mark", "note": "…"}. Directions: rx/tx (single port), pc/vent (bridge), tap. Timestamps are monotonic seconds from the start of the capture. The format is deliberately trivial so captures can be analysed with jq, a spreadsheet, or Wireshark-style tools later.

Command file format

See eagle754/data/commands_template.json. Each command is a list of steps {tx, delay_before_s, rx, rx_window_s}; expect_stream_stop records whether the ventilator's periodic stream ceased after the command. pm-reset compares replies leniently (exact, prefix, or same length with ≤25 % differing bytes) because replies may embed counters or time.

Learning from an OEM session

learn groups PC→vent bytes into bursts (gap > 50 ms), classifies bursts repeated ≥5 times at a steady interval as polls, attributes the rest to the most recent marker within 30 s, and stores the vent's reply within 1 s and the stream state over the following 2.5 s. Markers f5, f3, rtc, reset, start, connect are mapped to the canonical names.

Probing heuristics

A candidate is interesting when, relative to the baseline rate, it produces 1.5× + 4 extra bytes, a frame class not seen in the baseline, or stops the stream. Spacing of 0.6 s and a 0.6 s window keep the 256-byte sweep under four minutes. The probe never sends multi-byte sequences unless asked (--set esc, --set ascii-cr, --set pairs-upper, --set file:).

The simulator is not the protocol

eagle754 sim implements an invented protocol with the right cadences so the pipeline can be tested. Never confuse its 1B 48 / 1B 52 bytes with real Eagle 754 commands; pm-reset refuses to run with the unlearned template for that reason.

Contributing a confirmed protocol

Add protocols/eagle754_fw<version>_commands.json and protocols/eagle754_fw<version>_analysis.json (from analyze --json), state the firmware version from USER PROGRAMS, and remove serial numbers. When a confirmed file exists the toolkit will ship it as the default and pm-reset becomes a one-command fix.