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, as worded by the manual: the port "permits remote monitoring of ventilator functions and capabilities, including: switches, controls, alarms, and pressure signals. 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.

Assumed (inferred, not stated by the manual)

• That the ventilator transmits unsolicited. The manual's wording above is compatible with a stream, but the DOS CAL.EXE "resets Vent754" when it starts and reports Vent754 COMMUNICATION SETUP ERROR!! if it gets no answer (754M §1.3.3 / §1.4.1), so the unit may only talk when polled. The toolkit therefore treats a silent port as a possible poll/response link: the connect wizard offers a harmless poll check, learn recognises the OEM program's periodic poll (exact or with one or two changing bytes) and masks its replies out of the stream statistics, and pm-reset --skip-stream-check judges the release by its reply.

How analyze recovers framing

1. Gap framing. Bytes are timestamped as they arrive (reader polls with a 50 ms timeout and reads everything pending). A chunk's timestamp is when its last byte arrived, so the idle gap before chunk B is (t_B - len_B × byte time) - t_A; gaps longer than 3 character times, never less than 20 ms (USB adapters flush every 16 ms), split frames. Pieces of one frame delivered as separate USB chunks therefore stay together. 1b. Structural refinement. Two frames sent back to back have no idle gap and arrive merged. Once a class has a validated checksum, any merged burst that starts with (or decomposes into) validated frames is cut at the checksum boundaries and re-classified, up to three passes. 1c. Variable first byte. If a frame length shows four or more different first bytes with no dominant one, the first byte is data (sequence counter or type nibble) and the whole length is one class, labelled any/lenN.
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 line terminators (a CR LF pair counts once). Text lines are classified by their leading character, not their length, since printf-style numbers change the width; the drafted protocol carries a regular expression with the varying tokens captured. Counters: a byte that steps up by one or two almost every frame is a sequence counter and is never chosen as the pressure field.

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.