Skip to content
22 changes: 17 additions & 5 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -426,11 +426,23 @@ own `Version{READ}` about 1 ms behind it, and the answer to the announce

### 4.3 Keepalive and disconnect

Cortex Control sends `KeepAlive{action: UPDATE}` about once per second. The
library sends every 5 seconds; the unit tolerated 20-second idle gaps in the
capture, so the interval is not critical. On quit, Cortex Control sends
`Connection{connected: false}`, and so does this library, as the first step of
teardown.
Cortex Control 4.0.1 sends `KeepAlive{action: UPDATE}` about once per second:
944 keepalives across three complete captured sessions all carried action
`UPDATE` and no `request_id`. Each session opened with exactly 14 keepalives
carrying payload `08 01`, then 14.2 seconds after the first one added
`is_online: true` (`08 01 18 01`) and held it: 44 carried the short form and
900 the long one, and the short form returned only twice, both in session 1.
None of the three 4.0.1 captures contained `10 00 18 01`. The library keeps the
measured opening shape. Cortex Control 4.1.0 was observed on 2026-09-11, with
the connected unit reporting CorOS 4.1.0, using that different shape (explicit
request id zero, `is_online: true`, action absent). The old 4.0.1-compatible
shape has not been shown to fail on that CorOS version, so no wire change is
made from that observation.

The library sends every 5 seconds, and the unit tolerated 20-second
idle gaps in the capture without dropping the session, so the exact interval is
not critical. On quit, Cortex Control and this library send
`Connection{connected: false}` as the first step of teardown.

Abandoning a session without the goodbye leaks nothing observable. Measured: 12
sessions opened and abandoned, then the seed push still arrived, subscriptions
Expand Down
13 changes: 11 additions & 2 deletions tests/test_transport.py
Original file line number Diff line number Diff line change
Expand Up @@ -248,7 +248,9 @@ def close(self):


def test_keepalive_is_sent_periodically():
# With a tiny interval, the keepalive thread should emit KeepAlive writes.
# With a tiny interval, the keepalive thread should emit the exact CorOS
# 4.0.1 Cortex Control opening payload: 14 of these open each of the three
# captured sessions before Cortex Control switches to `08 01 18 01`.
fake = FakeHid()
t = transport.Transport(fake, keepalive_interval=0.02)
t.start()
Expand All @@ -257,10 +259,17 @@ def saw_keepalive():
for report in list(fake.writes):
frame = framing.decode_reports([report])
if registry.class_for(frame.message_type) is pa.KeepAliveMessage:
return True
message = pa.KeepAliveMessage()
message.ParseFromString(frame.payload)
return message, frame.payload
return False

assert _wait_until(saw_keepalive, timeout=REQUEST_TIMEOUT)
message, payload = saw_keepalive()
assert payload == bytes.fromhex("08 01")
assert message.action == pa.MessageAction.UPDATE
assert not message.HasField("request_id")
assert not message.is_online
Comment thread
tony-xmelon marked this conversation as resolved.
Resolved
finally:
t.stop()

Expand Down
Loading