From 2bd831fa2b8cb657317ee9612c1d2393b852f1f0 Mon Sep 17 00:00:00 2001
From: Haobo Gu <haobogu@outlook.com>
Date: Fri, 7 Aug 2026 17:08:51 +0800
Subject: [PATCH 1/2] test(rynk): freeze every row in the frame snapshot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`wire_frames.snap` dropped every row behind a feature so that any `rynk`
feature set would render the same file — which left `GetBleStatus`,
`SwitchBleProfile`, `ClearBleProfile`, `GetBatteryStatus`,
`GetPeripheralStatus` and `BatteryStatusChange` with no frozen bytes at all.

Gate the test on `host` instead, the feature superset, so the file is
generated once and holds every row. Regenerate with `--features host`.

`GetLayout` was missing for a different reason — never listed, though it is
neither gated nor bulk — so freeze it and its `LayoutChunk` payload too. The
frame helper follows the test behind `host`, and the battery row in
`wire_values.snap` now reuses the shared exemplar rather than rebuilding an
identical value, so neither is dead weight on a `rynk`-only build.

Also states the two compatibility rules the reference left open: appending a
`RynkError` variant is a `minor` bump (an old host can't decode the new tag
and reports a generic failure), and `0.x` is pre-release, so the protocol
stays at `0.1` while it is unpublished.
---
 .../main/docs/development/rynk_protocol.md    |   2 +
 .../protocol/rynk/snapshots/wire_frames.snap  | 155 ++++++++++--------
 .../protocol/rynk/snapshots/wire_values.snap  |   4 +-
 rmk-types/src/protocol/rynk/tests.rs          | 101 ++++++++++--
 4 files changed, 177 insertions(+), 85 deletions(-)

diff --git a/docs/docs/main/docs/development/rynk_protocol.md b/docs/docs/main/docs/development/rynk_protocol.md
index 4f765947a..3705c8603 100644
--- a/docs/docs/main/docs/development/rynk_protocol.md
+++ b/docs/docs/main/docs/development/rynk_protocol.md
@@ -89,4 +89,6 @@ Topics are best-effort pushes; the `Get*` endpoints above mirror their payloads
 
 - `GetVersion` (`0x0001`) and its `Result<ProtocolVersion, RynkError>` reply are frozen across all versions.
 - Within a major version, adding a CMD or topic is a `minor` bump: old firmware answers `UnknownCmd`, old hosts ignore unknown topics.
+- Appending a `RynkError` variant is also a `minor` bump: an old host fails to decode the new tag and must surface it as a generic failure.
 - Reshaping an existing request/response — including appending a field — is a `major` bump.
+- `0.x` is pre-release and not covered by the rules above: while the protocol is unpublished it stays at `0.1`, whole command segments included.
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap b/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap
index ff7ed6bdf..6d3213605 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_frames.snap
@@ -4,76 +4,89 @@
 # payload, COBS-encoded with a trailing 0x00 delimiter — one per protocol message; the
 # label names the decoded payload (`()` = empty). A diff means the header, a CMD number,
 # or a message frame changed. If intentional, bump ProtocolVersion::CURRENT and regenerate:
-#   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk wire_frames
+#   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features host wire_frames
 # Format: <label>  <hex bytes>
 
-BootloaderJump reply Ok(())                                             02 04 02 01 01 00
-BootloaderJump request ()                                               02 04 02 01 00
-ConnectionChange topic ConnectionStatus{Configured,{1,Adv},Ble}         03 03 80 03 02 01 02 01 00
-GetBehaviorConfig reply Ok(BehaviorConfig{50,500,200,20})               04 01 06 01 07 32 f4 03 c8 01 14 00
-GetBehaviorConfig request ()                                            04 01 06 01 00
-GetCapabilities reply Ok(DeviceCapabilities{1..16})                     02 02 02 01 0c 01 02 03 04 05 06 07 08 09 0a 01 03 01 0b 07 0c 0d 0e 0f 10 01 00
-GetCapabilities request ()                                              02 02 02 01 00
-GetCombo reply Ok(Combo{[Single(A)],Morse(1),L2})                       04 01 03 01 04 01 02 01 06 04 05 01 01 02 00
-GetCombo request 3                                                      05 01 03 01 03 00
-GetConnectionStatus reply Ok(ConnectionStatus{Configured,{1,Adv},Ble})  04 02 07 01 03 02 01 02 01 00
-GetConnectionStatus request ()                                          04 02 07 01 00
-GetConnectionType reply Ok(Ble)                                         04 01 07 01 02 01 00
-GetConnectionType request ()                                            04 01 07 01 00
-GetCurrentLayer reply Ok(1)                                             04 01 08 01 02 01 00
-GetCurrentLayer request ()                                              04 01 08 01 00
-GetDefaultLayer reply Ok(2)                                             04 03 01 01 02 02 00
-GetDefaultLayer request ()                                              04 03 01 01 00
-GetDeviceInfo reply Ok(DeviceInfo{1.2.3,4,5,RMK,..})                    02 0a 02 01 21 01 02 03 04 05 03 52 4d 4b 0c 52 4d 4b 20 4b 65 79 62 6f 61 72 64 09 72 79 6e 6b 3a 30 30 30 31 00
-GetDeviceInfo request ()                                                02 0a 02 01 00
-GetEncoderAction reply Ok(EncoderAction{Morse(3),No})                   04 05 01 01 03 05 03 01 00
-GetEncoderAction request GetEncoderRequest{1,2}                         06 05 01 01 01 02 00
-GetFork reply Ok(Fork{Single(A),No,Morse(2)})                           04 01 05 01 03 02 01 02 04 06 05 02 01 02 01 01 01 03 02 01 00
-GetFork request 2                                                       05 01 05 01 02 00
-GetKeyAction reply Ok(Morse(7))                                         04 01 01 01 03 05 07 00
-GetKeyAction request KeyPosition{0,5,13}                                04 01 01 01 03 05 0d 00
-GetLedIndicator reply Ok(LedIndicator(Num|Scroll))                      04 07 08 01 02 05 00
-GetLedIndicator request ()                                              04 07 08 01 00
-GetLockStatus reply Ok(LockStatus{true,false,2,[(1,2),(3,4)]})          02 06 02 01 02 01 07 02 02 01 02 03 04 00
-GetLockStatus request ()                                                02 06 02 01 00
-GetMacro reply Ok(MacroData{[0x01,0x02,0x03]})                          04 01 02 01 05 03 01 02 03 00
-GetMacro request GetMacroRequest{256}                                   06 01 02 01 80 02 00
-GetMatrixState reply Ok(MatrixState{[0x05,0x00,0x20]})                  04 02 08 01 03 03 05 02 20 00
-GetMatrixState request ()                                               04 02 08 01 00
-GetMorse reply Ok(Morse{TAP->Key(A)})                                   04 01 04 01 01 04 01 02 01 02 04 00
-GetMorse request 0                                                      04 01 04 01 01 00
-GetSleepState reply Ok(true)                                            04 06 08 01 02 01 00
-GetSleepState request ()                                                04 06 08 01 00
-GetVersion reply Ok(CURRENT)                                            02 01 02 01 01 02 01 00
-GetVersion request ()                                                   02 01 02 01 00
-GetWpm reply Ok(42)                                                     04 05 08 01 02 2a 00
-GetWpm request ()                                                       04 05 08 01 00
-LayerChange topic 3                                                     03 01 80 02 03 00
-LedIndicatorChange topic LedIndicator(Num|Scroll)                       03 05 80 02 05 00
-Lock reply Ok(())                                                       02 08 02 01 01 00
-Lock request ()                                                         02 08 02 01 00
-Reboot reply Ok(())                                                     02 03 02 01 01 00
-Reboot request ()                                                       02 03 02 01 00
-SetBehaviorConfig reply Ok(())                                          04 02 06 01 01 00
-SetBehaviorConfig request BehaviorConfig{50,500,200,20}                 0a 02 06 01 32 f4 03 c8 01 14 00
-SetCombo reply Ok(())                                                   04 02 03 01 01 00
-SetCombo request SetComboRequest{3,combo}                               08 02 03 01 03 01 02 01 06 04 05 01 01 02 00
-SetDefaultLayer reply Ok(())                                            04 04 01 01 01 00
-SetDefaultLayer request 2                                               05 04 01 01 02 00
-SetEncoderAction reply Ok(())                                           04 06 01 01 01 00
-SetEncoderAction request SetEncoderRequest{1,2,{Morse(3),No}}           08 06 01 01 01 02 05 03 01 00
-SetFork reply Ok(())                                                    04 02 05 01 01 00
-SetFork request SetForkRequest{2,fork}                                  07 02 05 01 02 02 01 02 04 06 05 02 01 02 01 01 01 03 02 01 00
-SetKeyAction reply Err(Invalid)                                         06 02 01 01 01 05 00
-SetKeyAction reply Ok(())                                               04 02 01 01 01 00
-SetKeyAction request SetKeyRequest{{0,5,13},Morse(7)}                   04 02 01 01 05 05 0d 05 07 00
-SetMacro reply Ok(())                                                   04 02 02 01 01 00
-SetMacro request SetMacroRequest{2,[0x01,0x02,0x03]}                    09 02 02 01 02 03 01 02 03 00
-SetMorse reply Ok(())                                                   04 02 04 01 01 00
-SetMorse request SetMorseRequest{0,morse}                               04 02 04 01 01 04 01 02 01 02 04 00
-SleepState topic true                                                   03 04 80 02 01 00
-StorageReset reply Ok(())                                               02 05 02 01 01 00
-StorageReset request StorageResetMode::Full                             02 05 02 01 01 00
-UnlockPoll reply Ok(LockStatus{true,false,2,[(1,2),(3,4)]})             02 07 02 01 02 01 07 02 02 01 02 03 04 00
-UnlockPoll request ()                                                   02 07 02 01 00
-WpmUpdate topic 42                                                      03 02 80 02 2a 00
+BatteryStatusChange topic Available{Discharging,85}                             03 06 80 05 01 01 01 55 00
+BootloaderJump reply Ok(())                                                     02 04 02 01 01 00
+BootloaderJump request ()                                                       02 04 02 01 00
+ClearBleProfile reply Ok(())                                                    04 05 07 01 01 00
+ClearBleProfile request 1                                                       05 05 07 01 01 00
+ConnectionChange topic ConnectionStatus{Configured,{1,Adv},Ble}                 03 03 80 03 02 01 02 01 00
+GetBatteryStatus reply Ok(Available{Discharging,85})                            04 03 08 01 05 01 01 01 55 00
+GetBatteryStatus request ()                                                     04 03 08 01 00
+GetBehaviorConfig reply Ok(BehaviorConfig{50,500,200,20})                       04 01 06 01 07 32 f4 03 c8 01 14 00
+GetBehaviorConfig request ()                                                    04 01 06 01 00
+GetBleStatus reply Ok(BleStatus{1,Advertising})                                 04 03 07 01 02 01 01 00
+GetBleStatus request ()                                                         04 03 07 01 00
+GetCapabilities reply Ok(DeviceCapabilities{1..16})                             02 02 02 01 0c 01 02 03 04 05 06 07 08 09 0a 01 03 01 0b 07 0c 0d 0e 0f 10 01 00
+GetCapabilities request ()                                                      02 02 02 01 00
+GetCombo reply Ok(Combo{[Single(A)],Morse(1),L2})                               04 01 03 01 04 01 02 01 06 04 05 01 01 02 00
+GetCombo request 3                                                              05 01 03 01 03 00
+GetConnectionStatus reply Ok(ConnectionStatus{Configured,{1,Adv},Ble})          04 02 07 01 03 02 01 02 01 00
+GetConnectionStatus request ()                                                  04 02 07 01 00
+GetConnectionType reply Ok(Ble)                                                 04 01 07 01 02 01 00
+GetConnectionType request ()                                                    04 01 07 01 00
+GetCurrentLayer reply Ok(1)                                                     04 01 08 01 02 01 00
+GetCurrentLayer request ()                                                      04 01 08 01 00
+GetDefaultLayer reply Ok(2)                                                     04 03 01 01 02 02 00
+GetDefaultLayer request ()                                                      04 03 01 01 00
+GetDeviceInfo reply Ok(DeviceInfo{1.2.3,4,5,RMK,..})                            02 0a 02 01 21 01 02 03 04 05 03 52 4d 4b 0c 52 4d 4b 20 4b 65 79 62 6f 61 72 64 09 72 79 6e 6b 3a 30 30 30 31 00
+GetDeviceInfo request ()                                                        02 0a 02 01 00
+GetEncoderAction reply Ok(EncoderAction{Morse(3),No})                           04 05 01 01 03 05 03 01 00
+GetEncoderAction request GetEncoderRequest{1,2}                                 06 05 01 01 01 02 00
+GetFork reply Ok(Fork{Single(A),No,Morse(2)})                                   04 01 05 01 03 02 01 02 04 06 05 02 01 02 01 01 01 03 02 01 00
+GetFork request 2                                                               05 01 05 01 02 00
+GetKeyAction reply Ok(Morse(7))                                                 04 01 01 01 03 05 07 00
+GetKeyAction request KeyPosition{0,5,13}                                        04 01 01 01 03 05 0d 00
+GetLayout reply Ok(LayoutChunk{300,[0x0a,0x0b,0x0c]})                           02 09 02 01 07 ac 02 03 0a 0b 0c 00
+GetLayout request 256                                                           02 09 04 01 80 02 00
+GetLedIndicator reply Ok(LedIndicator(Num|Scroll))                              04 07 08 01 02 05 00
+GetLedIndicator request ()                                                      04 07 08 01 00
+GetLockStatus reply Ok(LockStatus{true,false,2,[(1,2),(3,4)]})                  02 06 02 01 02 01 07 02 02 01 02 03 04 00
+GetLockStatus request ()                                                        02 06 02 01 00
+GetMacro reply Ok(MacroData{[0x01,0x02,0x03]})                                  04 01 02 01 05 03 01 02 03 00
+GetMacro request GetMacroRequest{256}                                           06 01 02 01 80 02 00
+GetMatrixState reply Ok(MatrixState{[0x05,0x00,0x20]})                          04 02 08 01 03 03 05 02 20 00
+GetMatrixState request ()                                                       04 02 08 01 00
+GetMorse reply Ok(Morse{TAP->Key(A)})                                           04 01 04 01 01 04 01 02 01 02 04 00
+GetMorse request 0                                                              04 01 04 01 01 00
+GetPeripheralStatus reply Ok(PeripheralStatus{true,Available{Discharging,85}})  04 04 08 01 06 01 01 01 01 55 00
+GetPeripheralStatus request 1                                                   05 04 08 01 01 00
+GetSleepState reply Ok(true)                                                    04 06 08 01 02 01 00
+GetSleepState request ()                                                        04 06 08 01 00
+GetVersion reply Ok(CURRENT)                                                    02 01 02 01 01 02 01 00
+GetVersion request ()                                                           02 01 02 01 00
+GetWpm reply Ok(42)                                                             04 05 08 01 02 2a 00
+GetWpm request ()                                                               04 05 08 01 00
+LayerChange topic 3                                                             03 01 80 02 03 00
+LedIndicatorChange topic LedIndicator(Num|Scroll)                               03 05 80 02 05 00
+Lock reply Ok(())                                                               02 08 02 01 01 00
+Lock request ()                                                                 02 08 02 01 00
+Reboot reply Ok(())                                                             02 03 02 01 01 00
+Reboot request ()                                                               02 03 02 01 00
+SetBehaviorConfig reply Ok(())                                                  04 02 06 01 01 00
+SetBehaviorConfig request BehaviorConfig{50,500,200,20}                         0a 02 06 01 32 f4 03 c8 01 14 00
+SetCombo reply Ok(())                                                           04 02 03 01 01 00
+SetCombo request SetComboRequest{3,combo}                                       08 02 03 01 03 01 02 01 06 04 05 01 01 02 00
+SetDefaultLayer reply Ok(())                                                    04 04 01 01 01 00
+SetDefaultLayer request 2                                                       05 04 01 01 02 00
+SetEncoderAction reply Ok(())                                                   04 06 01 01 01 00
+SetEncoderAction request SetEncoderRequest{1,2,{Morse(3),No}}                   08 06 01 01 01 02 05 03 01 00
+SetFork reply Ok(())                                                            04 02 05 01 01 00
+SetFork request SetForkRequest{2,fork}                                          07 02 05 01 02 02 01 02 04 06 05 02 01 02 01 01 01 03 02 01 00
+SetKeyAction reply Err(Invalid)                                                 06 02 01 01 01 05 00
+SetKeyAction reply Ok(())                                                       04 02 01 01 01 00
+SetKeyAction request SetKeyRequest{{0,5,13},Morse(7)}                           04 02 01 01 05 05 0d 05 07 00
+SetMacro reply Ok(())                                                           04 02 02 01 01 00
+SetMacro request SetMacroRequest{2,[0x01,0x02,0x03]}                            09 02 02 01 02 03 01 02 03 00
+SetMorse reply Ok(())                                                           04 02 04 01 01 00
+SetMorse request SetMorseRequest{0,morse}                                       04 02 04 01 01 04 01 02 01 02 04 00
+SleepState topic true                                                           03 04 80 02 01 00
+StorageReset reply Ok(())                                                       02 05 02 01 01 00
+StorageReset request StorageResetMode::Full                                     02 05 02 01 01 00
+SwitchBleProfile reply Ok(())                                                   04 04 07 01 01 00
+SwitchBleProfile request 1                                                      05 04 07 01 01 00
+UnlockPoll reply Ok(LockStatus{true,false,2,[(1,2),(3,4)]})                     02 07 02 01 02 01 07 02 02 01 02 03 04 00
+UnlockPoll request ()                                                           02 07 02 01 00
+WpmUpdate topic 42                                                              03 02 80 02 2a 00
diff --git a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
index 073c10d80..ee3109456 100644
--- a/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
+++ b/rmk-types/src/protocol/rynk/snapshots/wire_values.snap
@@ -3,7 +3,7 @@
 # Each entry is the postcard byte encoding of one wire-type exemplar. A diff
 # here means a type's payload encoding changed (field reorder, variant
 # renumber, …). If intentional, bump ProtocolVersion::CURRENT and regenerate:
-#   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk wire_values
+#   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features host wire_values
 # Format: <label>  <hex bytes>
 
 Action::DefaultLayer(5)                   08 05
@@ -56,6 +56,7 @@ KeyCode::Consumer(VolumeIncrement)        01 12
 KeyCode::Hid(A)                           00 04
 KeyCode::SystemControl(Sleep)             02 02
 KeyPosition{layer:0,row:5,col:13}         00 05 0d
+LayoutChunk{300,[0x0a,0x0b,0x0c]}         ac 02 03 0a 0b 0c
 LedIndicator(Num|Scroll)                  05
 LockStatus{true,false,2,[(1,2),(3,4)]}    01 00 02 02 01 02 03 04
 MacroData{[0x01,0x02,0x03]}               03 01 02 03
@@ -68,6 +69,7 @@ ProtocolVersion::CURRENT                  00 01
 ProtocolVersion{1,0}                      01 00
 Result<(),RynkError>::Err(StorageFault)   01 02
 Result<(),RynkError>::Ok                  00
+RynkError::Busy                           08
 RynkError::Internal                       03
 RynkError::Invalid                        05
 RynkError::Locked                         07
diff --git a/rmk-types/src/protocol/rynk/tests.rs b/rmk-types/src/protocol/rynk/tests.rs
index e532712b9..3f36f713b 100644
--- a/rmk-types/src/protocol/rynk/tests.rs
+++ b/rmk-types/src/protocol/rynk/tests.rs
@@ -113,7 +113,7 @@ mod snapshot {
             "# {title} — DO NOT edit by hand.\n\
              # File: {rel_path}\n\
              {blurb}\n\
-             #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk {test_filter}\n\
+             #   UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features host {test_filter}\n\
              # Format: <label>  <hex bytes>\n\
              \n",
         ));
@@ -178,6 +178,7 @@ fn round_trip_rynk_error_and_result() {
     round_trip(&RynkError::Invalid);
     round_trip(&RynkError::UnknownCmd);
     round_trip(&RynkError::Locked);
+    round_trip(&RynkError::Busy);
     let ok: Result<(), RynkError> = Ok(());
     let err: Result<(), RynkError> = Err(RynkError::StorageFault);
     let _ = round_trip(&ok);
@@ -190,6 +191,8 @@ fn encode<T: serde::Serialize>(val: &T) -> alloc::vec::Vec<u8> {
     bytes.to_vec()
 }
 
+/// Frames are frozen only on `host`; see [`wire_frames_locked`].
+#[cfg(feature = "host")]
 fn encode_frame<T: serde::Serialize>(cmd: Cmd, seq: u8, val: &T) -> alloc::vec::Vec<u8> {
     let mut buf = [0u8; 256];
     let n = super::message::encode_frame(&mut buf, RynkHeader { cmd, seq }, val).expect("frame");
@@ -212,6 +215,8 @@ struct Exemplars {
     morse: Morse,
     macro_data: MacroData,
     encoder: EncoderAction,
+    battery: BatteryStatus,
+    layout: LayoutChunk,
 }
 
 fn exemplars() -> Exemplars {
@@ -303,6 +308,14 @@ fn exemplars() -> Exemplars {
     macro_bytes.extend_from_slice(&[0x01, 0x02, 0x03]).unwrap();
     let macro_data = MacroData { data: macro_bytes };
     let encoder = EncoderAction::new(KeyAction::Morse(3), KeyAction::No);
+    // A page shorter than the chunk size, with a `total_len` that outgrows it and
+    // takes two varint bytes, so swapping the two fields flips the bytes.
+    let mut layout_bytes: heapless::Vec<u8, RYNK_BLE_CHUNK_SIZE> = heapless::Vec::new();
+    layout_bytes.extend_from_slice(&[0x0a, 0x0b, 0x0c]).unwrap();
+    let layout = LayoutChunk {
+        total_len: 300,
+        bytes: layout_bytes,
+    };
 
     Exemplars {
         matrix,
@@ -316,6 +329,11 @@ fn exemplars() -> Exemplars {
         morse,
         macro_data,
         encoder,
+        battery: BatteryStatus::Available {
+            charge_state: ChargeState::Discharging,
+            level: Some(85),
+        },
+        layout,
     }
 }
 
@@ -365,6 +383,7 @@ fn wire_values_locked() {
         ("RynkError::StorageFault", encode(&RynkError::StorageFault)),
         ("RynkError::Unimplemented", encode(&RynkError::Unimplemented)),
         ("RynkError::UnknownCmd", encode(&RynkError::UnknownCmd)),
+        ("RynkError::Busy", encode(&RynkError::Busy)),
         // --- KeyAction: every variant tag (positional) ---
         ("KeyAction::No", encode(&KeyAction::No)),
         ("KeyAction::Transparent", encode(&KeyAction::Transparent)),
@@ -470,13 +489,7 @@ fn wire_values_locked() {
         ("ProtocolVersion::CURRENT", encode(&ProtocolVersion::CURRENT)),
         ("LockStatus{true,false,2,[(1,2),(3,4)]}", encode(&lock_status),),
         ("BatteryStatus::Unavailable", encode(&BatteryStatus::Unavailable)),
-        (
-            "BatteryStatus::Available{Discharging,85}",
-            encode(&BatteryStatus::Available {
-                charge_state: ChargeState::Discharging,
-                level: Some(85)
-            }),
-        ),
+        ("BatteryStatus::Available{Discharging,85}", encode(&ex.battery)),
         ("ChargeState::Charging", encode(&ChargeState::Charging)),
         ("ChargeState::Discharging", encode(&ChargeState::Discharging)),
         ("ChargeState::Unknown", encode(&ChargeState::Unknown)),
@@ -496,6 +509,7 @@ fn wire_values_locked() {
         ("UsbState::Suspended", encode(&UsbState::Suspended)),
         ("StorageResetMode::Full", encode(&StorageResetMode::Full)),
         ("StorageResetMode::LayoutOnly", encode(&StorageResetMode::LayoutOnly)),
+        ("LayoutChunk{300,[0x0a,0x0b,0x0c]}", encode(&ex.layout)),
         // --- Request payloads: pin field order of the Get/Set structs ---
         (
             "SetKeyRequest{{0,5,13},Morse(7)}",
@@ -575,10 +589,15 @@ fn wire_values_locked() {
 ///
 /// Requests and replies use SEQ 1 (a reply echoes its request's SEQ); topics
 /// always use SEQ 0. The `GetVersion` probe and reply are frozen across all
-/// majors. Feature-gated commands (`bulk`, `_ble`, split) are excluded so
-/// every `rynk` feature set yields the same file. Payloads reuse the shared
-/// [`exemplars`], so a frame and its bare-payload entry in
-/// `wire_values.snap` stay in lockstep.
+/// majors. Payloads reuse the shared [`exemplars`], so a frame and its
+/// bare-payload entry in `wire_values.snap` stay in lockstep.
+///
+/// Gated on `host`, the feature superset (`_ble` + `split` + `steno`): the file
+/// then holds every gated row exactly once instead of dropping the rows a
+/// lesser feature set can't name. Only `bulk` stays out —
+/// its payload types differ between host and firmware. Regenerate with
+/// `UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features host`.
+#[cfg(feature = "host")]
 #[test]
 fn wire_frames_locked() {
     let ex = exemplars();
@@ -665,6 +684,11 @@ fn wire_frames_locked() {
             "Lock reply Ok(())",
             encode_frame(Cmd::Lock, SEQ, &Ok::<(), RynkError>(()))
         ),
+        ("GetLayout request 256", encode_frame(Cmd::GetLayout, SEQ, &256u32)),
+        (
+            "GetLayout reply Ok(LayoutChunk{300,[0x0a,0x0b,0x0c]})",
+            encode_frame(Cmd::GetLayout, SEQ, &Ok::<LayoutChunk, RynkError>(ex.layout.clone())),
+        ),
         ("GetDeviceInfo request ()", encode_frame(Cmd::GetDeviceInfo, SEQ, &())),
         (
             "GetDeviceInfo reply Ok(DeviceInfo{1.2.3,4,5,RMK,..})",
@@ -911,6 +935,51 @@ fn wire_frames_locked() {
             "GetLedIndicator reply Ok(LedIndicator(Num|Scroll))",
             encode_frame(Cmd::GetLedIndicator, SEQ, &Ok::<LedIndicator, RynkError>(led)),
         ),
+        // Connection / status rows behind `_ble` and `split`.
+        ("GetBleStatus request ()", encode_frame(Cmd::GetBleStatus, SEQ, &())),
+        (
+            "GetBleStatus reply Ok(BleStatus{1,Advertising})",
+            encode_frame(Cmd::GetBleStatus, SEQ, &Ok::<BleStatus, RynkError>(ex.connection.ble)),
+        ),
+        (
+            "SwitchBleProfile request 1",
+            encode_frame(Cmd::SwitchBleProfile, SEQ, &1u8)
+        ),
+        (
+            "SwitchBleProfile reply Ok(())",
+            encode_frame(Cmd::SwitchBleProfile, SEQ, &Ok::<(), RynkError>(())),
+        ),
+        (
+            "ClearBleProfile request 1",
+            encode_frame(Cmd::ClearBleProfile, SEQ, &1u8)
+        ),
+        (
+            "ClearBleProfile reply Ok(())",
+            encode_frame(Cmd::ClearBleProfile, SEQ, &Ok::<(), RynkError>(())),
+        ),
+        (
+            "GetBatteryStatus request ()",
+            encode_frame(Cmd::GetBatteryStatus, SEQ, &())
+        ),
+        (
+            "GetBatteryStatus reply Ok(Available{Discharging,85})",
+            encode_frame(Cmd::GetBatteryStatus, SEQ, &Ok::<BatteryStatus, RynkError>(ex.battery)),
+        ),
+        (
+            "GetPeripheralStatus request 1",
+            encode_frame(Cmd::GetPeripheralStatus, SEQ, &1u8)
+        ),
+        (
+            "GetPeripheralStatus reply Ok(PeripheralStatus{true,Available{Discharging,85}})",
+            encode_frame(
+                Cmd::GetPeripheralStatus,
+                SEQ,
+                &Ok::<PeripheralStatus, RynkError>(PeripheralStatus {
+                    connected: true,
+                    battery: ex.battery,
+                }),
+            ),
+        ),
         // Topics (0x80xx, server→host push, SEQ 0).
         ("LayerChange topic 3", encode_frame(Cmd::LayerChange, 0, &3u8)),
         ("WpmUpdate topic 42", encode_frame(Cmd::WpmUpdate, 0, &42u16)),
@@ -923,6 +992,10 @@ fn wire_frames_locked() {
             "LedIndicatorChange topic LedIndicator(Num|Scroll)",
             encode_frame(Cmd::LedIndicatorChange, 0, &led)
         ),
+        (
+            "BatteryStatusChange topic Available{Discharging,85}",
+            encode_frame(Cmd::BatteryStatusChange, 0, &ex.battery)
+        ),
     ];
     let view: alloc::vec::Vec<(&str, &[u8])> = entries.iter().map(|(l, b)| (*l, b.as_slice())).collect();
 
@@ -1088,7 +1161,9 @@ mod protocol_reference {
              ## Compatibility\n\n\
              - `GetVersion` (`0x0001`) and its `Result<ProtocolVersion, RynkError>` reply are frozen across all versions.\n\
              - Within a major version, adding a CMD or topic is a `minor` bump: old firmware answers `UnknownCmd`, old hosts ignore unknown topics.\n\
-             - Reshaping an existing request/response — including appending a field — is a `major` bump.\n",
+             - Appending a `RynkError` variant is also a `minor` bump: an old host fails to decode the new tag and must surface it as a generic failure.\n\
+             - Reshaping an existing request/response — including appending a field — is a `major` bump.\n\
+             - `0.x` is pre-release and not covered by the rules above: while the protocol is unpublished it stays at `0.1`, whole command segments included.\n",
             header = "<!-- GENERATED — do not edit. Rendered from the `endpoints!`/`topics!` tables in\n     rmk-types/src/protocol/rynk/command.rs. Regenerate with:\n     UPDATE_SNAPSHOTS=1 cargo test -p rmk-types --features rynk protocol_reference -->",
             major = v.major,
             minor = v.minor,

From 35fc0dc2e594f60320c5df3c8b52577ff12d8737 Mon Sep 17 00:00:00 2001
From: Haobo Gu <haobogu@outlook.com>
Date: Fri, 7 Aug 2026 17:08:51 +0800
Subject: [PATCH 2/2] =?UTF-8?q?feat(rynk):=20dongle=20groundwork=20?=
 =?UTF-8?q?=E2=80=94=20advertising=20constants,=20header=20peek,=20pairing?=
 =?UTF-8?q?=20window?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Groundwork for a dongle that relays one bonded keyboard to a USB host. The
Rynk command table is unchanged and `0x09xx` stays unallocated: a relay
answers no command of its own, and a host needs nothing from it beyond the
one thing it alone knows — whether the keyboard behind it is reachable.

That much a relay says with `NotReady`, whose existing definition is exactly
this case ("device is not currently in a state to satisfy the request"). It
answers on the request's own CMD and SEQ, so the first command of any
handshake already carries the answer, and a host that has never heard of
relays keeps working through one instead of waiting forever.

- `decode_header` reads a frame's CMD and SEQ out of the COBS prefix without
  touching the frame, which is all a relay needs to answer an undeliverable
  request; every other frame crosses unparsed.
- `RMK_ADV_COMPANY_ID` names the manufacturer id both the split peripheral
  and the dongle-seeking advertisement already share; `DONGLE_SEEKING_ADV_KIND`
  distinguishes the latter, followed by the Rynk protocol major. Both sit
  outside the `rynk` module, since a split peripheral advertises without it.
- `dongle_pairing_window_secs` configures how long a dongle accepts a
  keyboard after power-on, and dongle builds reserve one `led_indicator`
  subscriber for the keyboard link.

Signed-off-by: Haobo Gu <haobogu@outlook.com>
---
 .../default_config/subscriber_default.toml    |  9 +++
 rmk-config/src/lib.rs                         |  5 ++
 rmk-config/src/resolved/build_constants.rs    |  2 +
 rmk-types/build.rs                            |  9 +++
 rmk-types/src/ble.rs                          | 11 ++-
 rmk-types/src/protocol/rynk/command.rs        |  2 +
 rmk-types/src/protocol/rynk/message.rs        | 74 +++++++++++++++++++
 rmk/src/split/ble/peripheral.rs               |  2 +-
 8 files changed, 112 insertions(+), 2 deletions(-)

diff --git a/rmk-config/src/default_config/subscriber_default.toml b/rmk-config/src/default_config/subscriber_default.toml
index 4c6824616..067051f21 100644
--- a/rmk-config/src/default_config/subscriber_default.toml
+++ b/rmk-config/src/default_config/subscriber_default.toml
@@ -82,6 +82,15 @@ events = [
     { name = "led_indicator" },
 ]
 
+# --- Dongle firmware internal subscribers ---
+
+[[subscriber]]
+features = ["dongle"]
+events = [
+    # dongle/link.rs: LedIndicatorEvent::subscriber() on the one keyboard link.
+    { name = "led_indicator" },
+]
+
 # --- Split-gated internal subscribers ---
 
 [[subscriber]]
diff --git a/rmk-config/src/lib.rs b/rmk-config/src/lib.rs
index d858da563..1ede16ffc 100644
--- a/rmk-config/src/lib.rs
+++ b/rmk-config/src/lib.rs
@@ -309,6 +309,10 @@ pub(crate) struct RmkConstantsConfig {
     /// Default 488 fills exactly two BLE notifications.
     #[serde_inline_default(488)]
     pub rynk_buffer_size: usize,
+    /// Length of one dongle pairing scan in seconds; an unpaired dongle repeats
+    /// it until a keyboard shows up (dongle firmware only)
+    #[serde_inline_default(30)]
+    pub dongle_pairing_window_secs: u32,
 }
 
 fn check_combo_max_num<'de, D>(deserializer: D) -> Result<usize, D::Error>
@@ -400,6 +404,7 @@ impl Default for RmkConstantsConfig {
             protocol_macro_chunk_size: 64,
             auto_mouse_layer_max_num: None,
             rynk_buffer_size: 488,
+            dongle_pairing_window_secs: 30,
         }
     }
 }
diff --git a/rmk-config/src/resolved/build_constants.rs b/rmk-config/src/resolved/build_constants.rs
index 7c4ef3f54..d6f8e0c11 100644
--- a/rmk-config/src/resolved/build_constants.rs
+++ b/rmk-config/src/resolved/build_constants.rs
@@ -51,6 +51,7 @@ pub struct BuildConstants {
     pub auto_mouse_layer_max_num: usize,
     /// Rynk RX/TX buffer size (bytes).
     pub rynk_buffer_size: usize,
+    pub dongle_pairing_window_secs: u32,
     pub events: Vec<EventChannel>,
     pub passkey: Option<Passkey>,
 }
@@ -199,6 +200,7 @@ impl crate::KeyboardTomlConfig {
             protocol_macro_chunk_size: rmk.protocol_macro_chunk_size,
             auto_mouse_layer_max_num,
             rynk_buffer_size: rmk.rynk_buffer_size,
+            dongle_pairing_window_secs: rmk.dongle_pairing_window_secs,
             events,
             passkey,
         })
diff --git a/rmk-types/build.rs b/rmk-types/build.rs
index 697166c32..11f19c218 100644
--- a/rmk-types/build.rs
+++ b/rmk-types/build.rs
@@ -146,6 +146,15 @@ fn generate_constants(bc: &BuildConstants, config: &KeyboardTomlConfig) -> Strin
         lines.push(format!("pub const LAYOUT_BLOB: &[u8] = b\"{}\";", blob.escape_ascii()));
     }
 
+    // How long one dongle pairing scan lasts. It bonds exactly one keyboard, so
+    // there is nothing else about the relay to size.
+    if env::var("CARGO_FEATURE_DONGLE").is_ok() {
+        lines.push(format!(
+            "pub const DONGLE_PAIRING_WINDOW_SECS: u32 = {};",
+            bc.dongle_pairing_window_secs
+        ));
+    }
+
     // Event channels
     for ev in &bc.events {
         let upper = ev.name.to_uppercase();
diff --git a/rmk-types/src/ble.rs b/rmk-types/src/ble.rs
index e38658147..455ee0c01 100644
--- a/rmk-types/src/ble.rs
+++ b/rmk-types/src/ble.rs
@@ -1,8 +1,17 @@
-//! BLE status types.
+//! BLE status types and advertising constants.
 
 use postcard::experimental::max_size::MaxSize;
 use serde::{Deserialize, Serialize};
 
+/// Company identifier in RMK's manufacturer-specific advertising data.
+pub const RMK_ADV_COMPANY_ID: u16 = 0x5253;
+
+/// First manufacturer-specific-data byte of a keyboard's dongle-seeking
+/// advertisement, followed by the Rynk protocol major version. Every RMK
+/// advertisement kind shares [`RMK_ADV_COMPANY_ID`], so this must not collide
+/// with the split-peripheral payload, whose first byte is a small peripheral id.
+pub const DONGLE_SEEKING_ADV_KIND: u8 = 0xD0;
+
 /// BLE state (what the BLE subsystem is currently doing).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, MaxSize)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
diff --git a/rmk-types/src/protocol/rynk/command.rs b/rmk-types/src/protocol/rynk/command.rs
index 270ed34aa..533fbce7c 100644
--- a/rmk-types/src/protocol/rynk/command.rs
+++ b/rmk-types/src/protocol/rynk/command.rs
@@ -337,6 +337,8 @@ endpoints! {
     GetSleepState = 0x0806: () => bool;
     /// Latest HID LED bitmap, sourced from the `LedIndicatorChange` topic snapshot.
     GetLedIndicator = 0x0807: () => LedIndicator;
+
+    // 0x09xx is reserved for a relay to answer for itself; nothing needs it yet.
 }
 
 // Define topics: `Name = value: Payload;`
diff --git a/rmk-types/src/protocol/rynk/message.rs b/rmk-types/src/protocol/rynk/message.rs
index 2868b5879..ce5d1f406 100644
--- a/rmk-types/src/protocol/rynk/message.rs
+++ b/rmk-types/src/protocol/rynk/message.rs
@@ -39,6 +39,30 @@ impl RynkHeader {
         }
     }
 
+    /// Decode the Rynk header out of a COBS-encoded frame, leaving the frame bytes untouched.
+    ///
+    /// This is mainly used in the dongle to check the command.
+    pub fn peek(encoded: &[u8]) -> Option<Self> {
+        let mut out = [0u8; RYNK_HEADER_SIZE];
+        let mut n = 0;
+        let mut state = cobs::DecoderState::Idle;
+        for &byte in encoded {
+            match state.feed(byte).ok()? {
+                cobs::DecodeResult::NoData => {}
+                // The frame's delimiter arrived before a full header was decoded.
+                cobs::DecodeResult::DataComplete => return None,
+                cobs::DecodeResult::DataContinue(b) => {
+                    out[n] = b;
+                    n += 1;
+                    if n == RYNK_HEADER_SIZE {
+                        return Some(Self::parse(&out));
+                    }
+                }
+            }
+        }
+        None
+    }
+
     pub const fn to_bytes(&self) -> [u8; RYNK_HEADER_SIZE] {
         let cmd_bytes = self.cmd.to_le_bytes();
         [cmd_bytes[0], cmd_bytes[1], self.seq]
@@ -290,6 +314,56 @@ mod tests {
         );
     }
 
+    #[test]
+    fn decode_header_reads_the_prefix_without_touching_the_frame() {
+        // Headers with and without interior zeros, with and without payload —
+        // the header must decode from the COBS prefix and the frame bytes stay put.
+        for (cmd, seq, payload) in [
+            (Cmd::GetVersion, 0x42u8, &[1u8, 2, 3, 4][..]), // cmd_hi = 0x00
+            (Cmd::from_raw(0x0901), 0x00, &[][..]),         // seq = 0x00, empty payload
+            (Cmd::from_raw(0x7FFF), 0xFF, &[0u8, 0][..]),   // no zeros in the header
+        ] {
+            let mut buf = [0u8; 64];
+            let n = encode_frame(&mut buf, RynkHeader { cmd, seq }, &payload).unwrap();
+            let copy = buf;
+            let header = RynkHeader::peek(&buf[..n]).expect("header decodes");
+            assert_eq!(header.cmd, cmd);
+            assert_eq!(header.seq, seq);
+            assert_eq!(buf, copy, "input frame must not be modified");
+            // Also without the trailing delimiter, as a raw splitter may hand it over.
+            let header = RynkHeader::peek(&buf[..n - 1]).unwrap();
+            assert_eq!(header.cmd, cmd);
+        }
+    }
+
+    #[test]
+    fn decode_header_survives_a_254_byte_first_group() {
+        // An all-nonzero frame longer than 254 bytes makes the first COBS group
+        // 0xFF-coded; the header must not gain a phantom zero at the group edge.
+        let payload = [0x41u8; 300];
+        let mut buf = [0u8; 400];
+        let header = RynkHeader {
+            cmd: Cmd::from_raw(0x0101),
+            seq: 7,
+        };
+        let n = encode_frame(&mut buf, header, &payload.as_slice()).unwrap();
+        let decoded = RynkHeader::peek(&buf[..n]).unwrap();
+        assert_eq!(decoded.cmd.raw(), 0x0101);
+        assert_eq!(decoded.seq, 7);
+    }
+
+    #[test]
+    fn decode_header_rejects_truncated_or_empty_input() {
+        assert!(RynkHeader::peek(&[]).is_none());
+        // A bare delimiter or a frame cut before 3 decoded bytes.
+        assert!(RynkHeader::peek(&[0x00]).is_none());
+        assert!(RynkHeader::peek(&[0x02, 0xAA]).is_none());
+        assert!(
+            RynkHeader::peek(&[0x03, 0xAA, 0xBB]).is_none(),
+            "only 2 decoded bytes + EOF"
+        );
+    }
+
     #[test]
     fn frame_never_contains_the_delimiter() {
         // cmd 0x0004 has a zero byte; the encoded frame must not carry a bare 0x00
diff --git a/rmk/src/split/ble/peripheral.rs b/rmk/src/split/ble/peripheral.rs
index 4ab48af76..5751bc372 100644
--- a/rmk/src/split/ble/peripheral.rs
+++ b/rmk/src/split/ble/peripheral.rs
@@ -250,7 +250,7 @@ fn get_peri_advertiser<'a, C: Controller>(
                         ],
                     ]),
                     AdStructure::ManufacturerSpecificData {
-                        company_identifier: 0xe118,
+                        company_identifier: rmk_types::ble::RMK_ADV_COMPANY_ID,
                         payload: &[id as u8],
                     },
                 ],