From 7d278277e4bf3ce3af914514bff33014266beafe Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Fri, 11 Sep 2026 13:08:50 +0300 Subject: [PATCH 1/4] Match Cortex keepalive sentinel wire --- pyquadcortex/protocol/transport.py | 5 ++++- tests/test_transport.py | 13 +++++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index d06f317f..2410563b 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -793,7 +793,10 @@ def _keepalive_loop(self): self._stop_event.wait() return try: - self.send(pa.KeepAliveMessage(action=pa.MessageAction.UPDATE)) + # Cortex Control sends the protobuf-default CREATE action with + # an explicit request-id zero sentinel. Zero is deliberately + # not drawn from the normal request counter. + self.send(pa.KeepAliveMessage(request_id=0, is_online=True)) except DeviceLostError: self._stop_event.wait() return diff --git a/tests/test_transport.py b/tests/test_transport.py index 39c006b3..73b28644 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -248,7 +248,8 @@ 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 Cortex Control's + # exact sentinel payload: default CREATE, explicit request_id=0, online. fake = FakeHid() t = transport.Transport(fake, keepalive_interval=0.02) t.start() @@ -257,10 +258,18 @@ 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("10 00 18 01") + assert message.action == pa.MessageAction.CREATE + assert message.HasField("request_id") + assert message.request_id == 0 + assert message.is_online is True finally: t.stop() From b4d4cebe1954ff6105f5f25b60f7e1837f908192 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Fri, 11 Sep 2026 21:55:13 +0300 Subject: [PATCH 2/4] Preserve the measured 4.0.1 keepalive --- docs/protocol.md | 16 ++++++++++++---- pyquadcortex/protocol/transport.py | 5 +---- tests/test_transport.py | 13 ++++++------- 3 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index cbe3b806..62cefd44 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -541,10 +541,18 @@ the first `device.firmware` read still asks the unit once. ### 4.3 Keepalive and disconnect -Cortex Control sends `KeepAlive{action: UPDATE}` about once per second. The -library defaults to every 5 seconds, and the device tolerated 20-second idle -gaps in the capture without dropping the session, so the exact interval is not -critical. On quit, Cortex Control sends `Connection{connected: false}`. This library now does the +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`. Early in each session it used payload `08 01`; after +roughly two minutes it usually added `is_online: true` (`08 01 18 01`). The +library keeps the measured opening shape. Cortex Control 4.1.0 was observed on +2026-09-11 using a different shape, `10 00 18 01` (explicit request id zero, +`is_online: true`, action absent); the old 4.0.1-compatible shape has not been +shown to fail on that firmware, so no wire change is made from that observation. + +The library defaults to every 5 seconds, and the device tolerated 20-second +idle gaps in the capture without dropping the session, so the exact interval is +not critical. On quit, Cortex Control sends `Connection{connected: false}`. This library now does the same, as the first step of teardown - the send needs a live transport, so it has to precede stopping it and closing the handle. diff --git a/pyquadcortex/protocol/transport.py b/pyquadcortex/protocol/transport.py index 2410563b..d06f317f 100644 --- a/pyquadcortex/protocol/transport.py +++ b/pyquadcortex/protocol/transport.py @@ -793,10 +793,7 @@ def _keepalive_loop(self): self._stop_event.wait() return try: - # Cortex Control sends the protobuf-default CREATE action with - # an explicit request-id zero sentinel. Zero is deliberately - # not drawn from the normal request counter. - self.send(pa.KeepAliveMessage(request_id=0, is_online=True)) + self.send(pa.KeepAliveMessage(action=pa.MessageAction.UPDATE)) except DeviceLostError: self._stop_event.wait() return diff --git a/tests/test_transport.py b/tests/test_transport.py index 73b28644..8975fcd4 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -248,8 +248,8 @@ def close(self): def test_keepalive_is_sent_periodically(): - # With a tiny interval, the keepalive thread should emit Cortex Control's - # exact sentinel payload: default CREATE, explicit request_id=0, online. + # With a tiny interval, the keepalive thread should emit the exact CorOS + # 4.0.1 Cortex Control payload captured 944 times across three sessions. fake = FakeHid() t = transport.Transport(fake, keepalive_interval=0.02) t.start() @@ -265,11 +265,10 @@ def saw_keepalive(): assert _wait_until(saw_keepalive, timeout=REQUEST_TIMEOUT) message, payload = saw_keepalive() - assert payload == bytes.fromhex("10 00 18 01") - assert message.action == pa.MessageAction.CREATE - assert message.HasField("request_id") - assert message.request_id == 0 - assert message.is_online is True + assert payload == bytes.fromhex("08 01") + assert message.action == pa.MessageAction.UPDATE + assert not message.HasField("request_id") + assert not message.is_online finally: t.stop() From 764b4125aadadb831543d4bb651a8f9b178e31d3 Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Tue, 22 Sep 2026 10:50:25 +0300 Subject: [PATCH 3/4] Correct captured keepalive counts --- docs/protocol.md | 20 ++++++++++++-------- tests/test_transport.py | 3 ++- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/protocol.md b/docs/protocol.md index dd97e254..e196d540 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -428,14 +428,18 @@ own `Version{READ}` about 1 ms behind it, and the answer to the announce 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`. Early in each session it used payload `08 01`; after -roughly two minutes it usually added `is_online: true` (`08 01 18 01`). The -library keeps the measured opening shape. Cortex Control 4.1.0 was observed on -2026-09-11 using a different shape, `10 00 18 01` (explicit request id zero, -`is_online: true`, action absent); the old 4.0.1-compatible shape has not been -shown to fail on that firmware, so no wire change is made from that observation. - -The library sends every 5 seconds, and the device tolerated 20-second +`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. diff --git a/tests/test_transport.py b/tests/test_transport.py index 36d023d7..44b9eb85 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -249,7 +249,8 @@ def close(self): def test_keepalive_is_sent_periodically(): # With a tiny interval, the keepalive thread should emit the exact CorOS - # 4.0.1 Cortex Control payload captured 944 times across three sessions. + # 4.0.1 Cortex Control opening payload, captured 44 times across three + # sessions before Cortex Control switches to `08 01 18 01`. fake = FakeHid() t = transport.Transport(fake, keepalive_interval=0.02) t.start() From 958a51028a5b574cc931a52905d5fdba338d54fe Mon Sep 17 00:00:00 2001 From: Antoni Ivanov <262547018+tony-xmelon@users.noreply.github.com> Date: Wed, 23 Sep 2026 00:14:32 +0300 Subject: [PATCH 4/4] Clarify captured keepalive session counts --- tests/test_transport.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_transport.py b/tests/test_transport.py index 44b9eb85..70837270 100644 --- a/tests/test_transport.py +++ b/tests/test_transport.py @@ -249,8 +249,8 @@ def close(self): def test_keepalive_is_sent_periodically(): # With a tiny interval, the keepalive thread should emit the exact CorOS - # 4.0.1 Cortex Control opening payload, captured 44 times across three - # sessions before Cortex Control switches to `08 01 18 01`. + # 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()