protocol.rs

/// IPI STAY FLY – HID frame builder and checksum helpers.
///
/// All frames are 16 bytes. Byte 0 is the global checksum:
///   byte[0] = (0x4D - sum(byte[2..=15])) & 0xFF
/// Byte 6 is the local mini-checksum for most config commands:
///   byte[6] = 0x57 - byte[4] - byte[5]
/// Byte 15 is a tail checksum for config commands:
///   byte[15] = 0xF1 - byte[3] - byte[4]

pub const FRAME_LEN: usize = 16;

pub fn checksum(frame: &mut [u8; FRAME_LEN]) {
    let sum: u16 = frame[2..].iter().map(|&b| b as u16).sum();
    frame[0] = ((0x4Du16.wrapping_sub(sum)) & 0xFF) as u8;
}

pub fn mini_checksum(frame: &mut [u8; FRAME_LEN]) {
    frame[6] = 0x57u8.wrapping_sub(frame[4]).wrapping_sub(frame[5]);
}

pub fn tail_checksum(frame: &mut [u8; FRAME_LEN]) {
    frame[15] = 0xF1u8.wrapping_sub(frame[3]).wrapping_sub(frame[4]);
}

pub fn build(mut f: [u8; FRAME_LEN]) -> [u8; FRAME_LEN] {
    mini_checksum(&mut f);
    tail_checksum(&mut f);
    checksum(&mut f);
    f
}

// ── Commands ────────────────────────────────────────────────────────────────

pub fn cmd_status() -> [u8; FRAME_LEN] {
    [0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x4a]
}

pub fn cmd_battery() -> [u8; FRAME_LEN] {
    [0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x49]
}

pub fn cmd_select_stage(stage: u8) -> [u8; FRAME_LEN] {
    // stage 0-3
    let mut f = [0u8; FRAME_LEN];
    f[2] = 0x00;
    f[3] = 0x04;
    f[4] = 0x02;
    f[5] = stage & 0x03;
    build(f)
}

/// DPI stage slot addresses in config memory: 0x0C, 0x10, 0x14, 0x18.
/// Confirmed by the block reads in `cmd_read_settings` (stage N is read back
/// from 0x0C + 4*N) and the captured stage-4 write at address 0x18.
pub fn dpi_stage_addr(stage: u8) -> u8 {
    0x0C + 4 * (stage & 0x03)
}

pub fn cmd_set_dpi(stage: u8, dpi: u16) -> [u8; FRAME_LEN] {
    // dpi = 50..=42000, step 50. Bytes 5 and 6 both carry the low byte of
    // (dpi/50)-1; byte 7 carries the high bits (0 for DPI <= 12800 — values
    // above that are extrapolated from the encoding and not yet captured).
    //
    // The frame is the same block-write shape as cmd_button: byte[3] = slot
    // address, byte[4] = 0x04 (length), byte[8] = inner checksum
    // (0x55 - byte[5] - byte[6] - byte[7]). The captured stage-4 / 5600 DPI
    // frame (07 00 00 18 04 6f 6f 00 77 ...) satisfies both rules:
    // 0x55 - 0x6f - 0x6f - 0x00 = 0x77.
    let raw = (dpi / 50).saturating_sub(1);
    let lo = (raw & 0xFF) as u8;
    let hi = (raw >> 8) as u8;
    let mut f = [0u8; FRAME_LEN];
    f[3] = dpi_stage_addr(stage);
    f[4] = 0x04;
    f[5] = lo;
    f[6] = lo;
    f[7] = hi;
    f[8] = 0x55u8.wrapping_sub(lo).wrapping_sub(lo).wrapping_sub(hi);
    tail_checksum(&mut f);
    checksum(&mut f);
    f
}

/// Assign an action to a physical button slot (block write at `0x07`).
///
/// Captured remap of the forward side button to Left Click:
///   `07 00 00 70 04 01 01 00 53 00 00 00 00 00 00 7d`
///
/// Layout: byte[3] = slot address, byte[4] = 0x04 (length),
/// byte[5] = action category, byte[6] = action code, byte[7] = modifier (0),
/// byte[8] = action checksum `(0x55 - cat - code - mod)`. The global checksum
/// (byte 0) and tail checksum (byte 15) follow the usual rules. The mini
/// checksum at byte 6 is NOT applied here — byte 6 carries the action code.
pub fn cmd_button(slot: u8, category: u8, code: u8, modifier: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = slot;
    f[4] = 0x04;
    f[5] = category;
    f[6] = code;
    f[7] = modifier;
    f[8] = 0x55u8
        .wrapping_sub(category)
        .wrapping_sub(code)
        .wrapping_sub(modifier);
    tail_checksum(&mut f);
    checksum(&mut f);
    f
}

/// Mouse-button action category.
pub const ACTION_MOUSE: u8 = 0x01;

/// Keyboard-key action category (category `0x05` in the button-slot write).
pub const ACTION_KEYBOARD: u8 = 0x05;

/// Macro-buffer block-write address used to stage a single key-press/release
/// sequence before the button slot is pointed at category `ACTION_KEYBOARD`.
const MACRO_BUFFER_ADDR: u8 = 0x20;

/// Build the macro-buffer write that stages a single keyboard key (press then
/// release of `keycode`, no modifiers).
///
/// Captured remap of the right button to keyboard `a` (0x04):
///   `07 00 01 20 08 02 81 04 00 41 04 00 89 00 00 c8`
///
/// Layout: byte[2]=0x01 (macro marker), byte[3]=0x20 (buffer addr),
/// byte[4]=0x08 (data length), byte[5]=0x02 (event count: down+up),
/// byte[6]=0x81/byte[9]=0x41 (key-down / key-up event tags),
/// byte[7]/byte[10]=keycode, byte[8]/byte[11]=0x00 (inter-event delay),
/// byte[12]=inner checksum `0x55 - sum(byte[5..=11])`, byte[15]=tail checksum
/// `0xF1 - byte[2] - byte[3] - byte[4]`, byte[0]=global checksum.
pub fn cmd_keyboard_macro(keycode: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[2] = 0x01;
    f[3] = MACRO_BUFFER_ADDR;
    f[4] = 0x08;
    f[5] = 0x02; // two events: key down, key up
    f[6] = 0x81; // key-down event tag
    f[7] = keycode;
    f[8] = 0x00; // delay
    f[9] = 0x41; // key-up event tag
    f[10] = keycode;
    f[11] = 0x00; // delay
    let inner: u8 = f[5..=11].iter().fold(0u8, |a, &b| a.wrapping_add(b));
    f[12] = 0x55u8.wrapping_sub(inner);
    // Tail rule generalised to include byte[2] (0 for ordinary config frames).
    f[15] = 0xF1u8.wrapping_sub(f[2]).wrapping_sub(f[3]).wrapping_sub(f[4]);
    checksum(&mut f);
    f
}

/// The two frames that remap a physical button slot to a single keyboard key:
/// first the macro-buffer stage, then the button-slot write pointing the slot
/// at category `ACTION_KEYBOARD` with the keycode in the modifier byte.
pub fn cmd_button_keyboard(slot: u8, keycode: u8) -> [[u8; FRAME_LEN]; 2] {
    [
        cmd_keyboard_macro(keycode),
        cmd_button(slot, ACTION_KEYBOARD, 0x00, keycode),
    ]
}

// Mouse-button action codes (category `ACTION_MOUSE`). Confirmed from captures:
// these are a standard HID button bitmask.
pub const MOUSE_LEFT: u8 = 0x01;
pub const MOUSE_RIGHT: u8 = 0x02;
pub const MOUSE_MIDDLE: u8 = 0x04;
pub const MOUSE_BACK: u8 = 0x08; // side button 4
pub const MOUSE_FORWARD: u8 = 0x10; // side button 5

// Physical button slot addresses, confirmed from per-button remap + factory
// reset captures. The reset restored each slot to its default action code.
pub const SLOT_LEFT: u8 = 0x60; // default Left  (0x01)
pub const SLOT_RIGHT: u8 = 0x64; // default Right (0x02)
pub const SLOT_MIDDLE: u8 = 0x68; // default Middle (0x04)
pub const SLOT_SIDE_BACK: u8 = 0x6c; // default Back  (0x08)
pub const SLOT_SIDE_FORWARD: u8 = 0x70; // default Forward (0x10)

/// Default (slot, action code) assignments, as restored by the factory reset.
pub const BUTTON_DEFAULTS: [(u8, u8); 5] = [
    (SLOT_LEFT, MOUSE_LEFT),
    (SLOT_RIGHT, MOUSE_RIGHT),
    (SLOT_MIDDLE, MOUSE_MIDDLE),
    (SLOT_SIDE_BACK, MOUSE_BACK),
    (SLOT_SIDE_FORWARD, MOUSE_FORWARD),
];

/// Mouse action codes that the app is allowed to assign to a button.
pub const MOUSE_ACTIONS: [u8; 5] = [
    MOUSE_LEFT,
    MOUSE_RIGHT,
    MOUSE_MIDDLE,
    MOUSE_BACK,
    MOUSE_FORWARD,
];

pub fn is_valid_button_slot(slot: u8) -> bool {
    BUTTON_DEFAULTS.iter().any(|&(s, _)| s == slot)
}

pub fn is_valid_mouse_action(code: u8) -> bool {
    MOUSE_ACTIONS.contains(&code)
}

/// Frames that restore every physical button to its default mouse action.
pub fn cmd_buttons_restore_defaults() -> [[u8; FRAME_LEN]; 5] {
    let mut frames = [[0u8; FRAME_LEN]; 5];
    for (i, &(slot, code)) in BUTTON_DEFAULTS.iter().enumerate() {
        frames[i] = cmd_button(slot, ACTION_MOUSE, code, 0x00);
    }
    frames
}

#[derive(serde::Deserialize, serde::Serialize, Clone, Copy, Debug)]
#[serde(rename_all = "camelCase")]
pub enum DpiLedMode {
    #[serde(rename = "Off")]
    Off,
    #[serde(rename = "Solid")]
    Solid,
    #[serde(rename = "Breathing")]
    Breathing,
}

/// Set frame (0x4C) — only sent for Solid and Breathing, not Off.
pub fn cmd_dpi_led_mode(mode: DpiLedMode) -> Option<[u8; FRAME_LEN]> {
    let value = match mode {
        DpiLedMode::Off => return None,
        DpiLedMode::Solid => 0x01,
        DpiLedMode::Breathing => 0x02,
    };
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0x4C;
    f[4] = 0x02;
    f[5] = value;
    Some(build(f))
}

/// Apply frame (0x52) — always sent; 0x01 = LED active (any mode), 0x00 = Off.
pub fn cmd_dpi_led_apply(mode: DpiLedMode) -> [u8; FRAME_LEN] {
    let value = match mode {
        DpiLedMode::Off => 0x00,
        DpiLedMode::Solid | DpiLedMode::Breathing => 0x01,
    };
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0x52;
    f[4] = 0x02;
    f[5] = value;
    build(f)
}

pub fn is_verified_dpi_led_mode(_mode: DpiLedMode) -> bool {
    true
}

/// Brightness for the DPI LED. Slider 0-10 maps to raw 0-255 (n * 255 / 10).
pub fn cmd_dpi_led_brightness(raw: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0x4E;
    f[4] = 0x02;
    f[5] = raw;
    build(f)
}

pub fn brightness_to_raw(level: u8) -> u8 {
    ((level.min(10) as u16 * 255) / 10) as u8
}

/// Inverse of `brightness_to_raw`: raw 0-255 back to the 0-10 slider level.
pub fn raw_to_brightness(raw: u8) -> u8 {
    (((raw as u16) * 10 + 127) / 255) as u8
}

/// Breathing speed. ENCAP=0x50, raw value 1-5 (verified: 2,3,4,5 from captures).
pub fn cmd_breathing_speed(speed: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0x50;
    f[4] = 0x02;
    f[5] = speed.clamp(1, 5);
    build(f)
}

#[derive(serde::Deserialize, serde::Serialize, Clone, Copy, Debug)]
#[serde(rename_all = "camelCase")]
pub enum PollingRate {
    #[serde(rename = "Hz125")]
    Hz125,
    #[serde(rename = "Hz250")]
    Hz250,
    #[serde(rename = "Hz500")]
    Hz500,
    #[serde(rename = "Hz1000")]
    Hz1000,
    #[serde(rename = "Hz2000")]
    Hz2000,
    #[serde(rename = "Hz4000")]
    Hz4000,
    #[serde(rename = "Hz8000")]
    Hz8000,
}

pub fn is_verified_polling_rate(rate: PollingRate) -> bool {
    matches!(
        rate,
        PollingRate::Hz125
            | PollingRate::Hz250
            | PollingRate::Hz500
            | PollingRate::Hz1000
            | PollingRate::Hz2000
            | PollingRate::Hz4000
            | PollingRate::Hz8000
    )
}

fn polling_rate_value(rate: PollingRate) -> u8 {
    match rate {
        PollingRate::Hz125  => 0x08,
        PollingRate::Hz250  => 0x04,
        PollingRate::Hz500  => 0x02,
        PollingRate::Hz1000 => 0x01,
        PollingRate::Hz2000 => 0x10,
        PollingRate::Hz4000 => 0x20,
        PollingRate::Hz8000 => 0x40,
    }
}

pub fn cmd_polling_rate(rate: PollingRate) -> [u8; FRAME_LEN] {
    cmd_polling_rate_with_encap(rate, 0x00)
}

pub fn cmd_polling_rate_apply(rate: PollingRate) -> [u8; FRAME_LEN] {
    cmd_polling_rate_with_encap(rate, 0xB9)
}

fn cmd_polling_rate_with_encap(rate: PollingRate, encap: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = encap;
    f[4] = 0x02;
    f[5] = polling_rate_value(rate);
    build(f)
}

#[derive(serde::Deserialize, serde::Serialize, Clone, Copy, Debug)]
#[serde(rename_all = "camelCase")]
pub enum Lod {
    #[serde(rename = "Mm07")]
    Mm07,
    #[serde(rename = "Mm1")]
    Mm1,
    #[serde(rename = "Mm2")]
    Mm2,
}

pub fn is_verified_lod(lod: Lod) -> bool {
    matches!(lod, Lod::Mm07 | Lod::Mm1 | Lod::Mm2)
}

pub fn cmd_lod(lod: Lod) -> [u8; FRAME_LEN] {
    let val: u8 = match lod {
        Lod::Mm07 => 0x03,
        Lod::Mm1  => 0x01,
        Lod::Mm2  => 0x02,
    };
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0x0A;
    f[4] = 0x02;
    f[5] = val;
    build(f)
}

pub fn cmd_linear_correction(enabled: bool) -> [u8; FRAME_LEN] {
    // Captured on-frame: 07 00 00 af 02 01 54 00 ... 40.
    // Off is the same toggle shape with byte[5]=0.
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xAF;
    f[4] = 0x02;
    f[5] = u8::from(enabled);
    build(f)
}

pub fn cmd_waveform_control(enabled: bool) -> [u8; FRAME_LEN] {
    // Captured on-frame: 07 00 00 b1 02 01 54 00 ... 3e.
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xB1;
    f[4] = 0x02;
    f[5] = u8::from(enabled);
    build(f)
}

pub fn cmd_motion_sync(enabled: bool) -> [u8; FRAME_LEN] {
    // Captured on-frame: 07 00 00 ab 02 01 54 00 ... 44.
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xAB;
    f[4] = 0x02;
    f[5] = u8::from(enabled);
    build(f)
}

/// Work mode. ENCAP=0xB9. 0=low power, 1=high performance (ultra/2 not yet captured).
pub fn cmd_work_mode(mode: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xB9;
    f[4] = 0x02;
    f[5] = mode;
    build(f)
}

/// Key debounce time in ms. ENCAP=0xA9. Raw value = ms (verified: 0,5,6,7,8,20).
pub fn cmd_debounce(ms: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xA9;
    f[4] = 0x02;
    f[5] = ms;
    build(f)
}

/// Full-power / rage mode toggle. ENCAP=0xB5. 0=off, 1=on.
pub fn cmd_working_mode(mode: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xB5;
    f[4] = 0x02;
    f[5] = mode;
    build(f)
}

/// Rage-time duration. ENCAP=0xB7. Raw seconds value.
/// Verified values: 1, 3, 6, 12, 18, 36, 60, 90.
pub fn cmd_rage_time(seconds: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xB7;
    f[4] = 0x02;
    f[5] = seconds;
    build(f)
}

/// Long-distance mode (block-write style).
/// ON:  16 00 00 00 0a 01 00 00 00 00 00 00 00 00 00 2c
/// OFF: 16 00 00 00 0a 00 00 00 00 00 00 00 00 00 00 2d
pub fn cmd_long_distance(enabled: bool) -> [u8; FRAME_LEN] {
    let v = u8::from(enabled);
    let mut f = [0u8; FRAME_LEN];
    f[3]  = 0x00;
    f[4]  = 0x0A;
    f[5]  = v;
    f[15] = 0x2Du8.wrapping_sub(v);
    checksum(&mut f);
    f
}

/// 20K FPS sensor scan rate. ENCAP=0xE1.
pub fn cmd_fps20k(enabled: bool) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xE1;
    f[4] = 0x02;
    f[5] = u8::from(enabled);
    build(f)
}

/// Sleep timer. ENCAP=0xAD, raw value (verified: 7, 8, 100 from captures).
pub fn cmd_sleep(value: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xAD;
    f[4] = 0x02;
    f[5] = value;
    build(f)
}

// ── Block write ────────────────────────────────────────────────────────────

/// Receiver LED (battery indicator on the USB dongle).
/// mode 1 = Hz indicator, mode 2 = battery level, mode 3 = warning only
/// (all three verified by capture; mode 0/off has no capture).
/// byte[15] = 0x33 - mode  keeps sum(bytes[2..16]) = 0x39 so byte[0] = 0x14.
pub fn cmd_receiver_led(mode: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3]  = 0x00;
    f[4]  = 0x0A;
    f[5]  = mode;
    f[6]  = 0x00;
    f[7]  = 0xFF;
    f[8]  = 0x00;
    f[9]  = 0xFF;
    f[10] = 0xFF;
    f[11] = 0x00;
    f[12] = 0xFF;
    f[13] = 0x00;
    f[14] = 0x00;
    f[15] = 0x33u8.wrapping_sub(mode);
    checksum(&mut f);
    f
}

// ── Block read ─────────────────────────────────────────────────────────────

/// Build a 10-byte block-read frame for the given start address.
/// The device responds with 10 bytes of config memory starting at `addr`.
pub fn cmd_block_read(addr: u8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = addr;
    f[4] = 0x0A;
    // tail: 0x3B - addr keeps global checksum at 0x08
    f[15] = 0x3Bu8.wrapping_sub(addr);
    // global checksum: sum(f[2..]) = addr + 0x0A + (0x3B - addr) = 0x45; 0x4D-0x45=0x08
    f[0] = 0x08;
    f
}

/// Angle snapping enable/disable. ENCAP=0xBF. 0=off, 1=on.
pub fn cmd_angle_enable(enabled: bool) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xBF;
    f[4] = 0x02;
    f[5] = u8::from(enabled);
    build(f)
}

/// Angle snapping value. ENCAP=0xBD. Range: -45..=+45.
/// Positive values stored as-is; negative as two's-complement u8 (e.g. -10 → 0xF6).
pub fn cmd_angle(angle: i8) -> [u8; FRAME_LEN] {
    let mut f = [0u8; FRAME_LEN];
    f[3] = 0xBD;
    f[4] = 0x02;
    f[5] = angle as u8;
    build(f)
}

/// Factory reset. Hardcoded frame verified from capture.
pub fn cmd_factory_reset() -> [u8; FRAME_LEN] {
    [0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x44]
}

/// Scalar read that returns the currently active DPI stage index (0-3).
/// Currently unused at runtime (the stage is read from config block 0x00),
/// but kept because the frame is capture-verified.
#[allow(dead_code)]
pub fn cmd_read_dpi_stage() -> [u8; FRAME_LEN] {
    // byte[15] = 0x3B; checksum = 0x4D - 0x3B = 0x12
    let mut f = [0u8; FRAME_LEN];
    f[15] = 0x3B;
    f[0] = 0x12;
    f
}

// ── Unit tests ──────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    fn hex(s: &str) -> [u8; FRAME_LEN] {
        let bytes: Vec<u8> = s
            .split_whitespace()
            .map(|h| u8::from_str_radix(h, 16).unwrap())
            .collect();
        bytes.try_into().expect("frame must be 16 bytes")
    }

    #[test]
    fn test_select_stage_1() {
        assert_eq!(cmd_select_stage(0), hex("07 00 00 04 02 00 55 00 00 00 00 00 00 00 00 eb"));
    }

    #[test]
    fn test_status_poll() {
        assert_eq!(cmd_status(), hex("03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 4a"));
    }

    #[test]
    fn test_button_side_to_left_click() {
        // Captured: side button slot 0x70 reassigned to Left Click.
        assert_eq!(
            cmd_button(SLOT_SIDE_FORWARD, ACTION_MOUSE, MOUSE_LEFT, 0x00),
            hex("07 00 00 70 04 01 01 00 53 00 00 00 00 00 00 7d")
        );
    }

    #[test]
    fn test_button_default_assignments() {
        // Captured factory-reset writes restoring each slot's default action.
        assert_eq!(
            cmd_button(SLOT_RIGHT, ACTION_MOUSE, MOUSE_RIGHT, 0x00),
            hex("07 00 00 64 04 01 02 00 52 00 00 00 00 00 00 89")
        );
        assert_eq!(
            cmd_button(SLOT_MIDDLE, ACTION_MOUSE, MOUSE_MIDDLE, 0x00),
            hex("07 00 00 68 04 01 04 00 50 00 00 00 00 00 00 85")
        );
        assert_eq!(
            cmd_button(SLOT_SIDE_BACK, ACTION_MOUSE, MOUSE_BACK, 0x00),
            hex("07 00 00 6c 04 01 08 00 4c 00 00 00 00 00 00 81")
        );
        assert_eq!(
            cmd_button(SLOT_SIDE_FORWARD, ACTION_MOUSE, MOUSE_FORWARD, 0x00),
            hex("07 00 00 70 04 01 10 00 44 00 00 00 00 00 00 7d")
        );
    }

    #[test]
    fn test_button_right_slot_to_keyboard_a() {
        // Captured: right button slot 0x64 remapped to keyboard 'a' (0x04).
        // The official software sends the macro-buffer stage then the slot write.
        let frames = cmd_button_keyboard(SLOT_RIGHT, 0x04);
        assert_eq!(
            frames[0],
            hex("07 00 01 20 08 02 81 04 00 41 04 00 89 00 00 c8")
        );
        assert_eq!(
            frames[1],
            hex("07 00 00 64 04 05 00 04 4c 00 00 00 00 00 00 89")
        );
    }

    #[test]
    fn test_button_left_slot_to_left_click() {
        // Captured: left button slot 0x60 set to Left Click.
        assert_eq!(
            cmd_button(SLOT_LEFT, ACTION_MOUSE, MOUSE_LEFT, 0x00),
            hex("07 00 00 60 04 01 01 00 53 00 00 00 00 00 00 8d")
        );
    }

    #[test]
    fn test_battery_query() {
        assert_eq!(cmd_battery(), hex("04 00 00 00 00 00 00 00 00 00 00 00 00 00 00 49"));
    }

    #[test]
    fn test_select_stage_2() {
        assert_eq!(cmd_select_stage(1), hex("07 00 00 04 02 01 54 00 00 00 00 00 00 00 00 eb"));
    }

    #[test]
    fn test_select_stage_3() {
        assert_eq!(cmd_select_stage(2), hex("07 00 00 04 02 02 53 00 00 00 00 00 00 00 00 eb"));
    }

    #[test]
    fn test_select_stage_4() {
        assert_eq!(cmd_select_stage(3), hex("07 00 00 04 02 03 52 00 00 00 00 00 00 00 00 eb"));
    }

    #[test]
    fn test_polling_250() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz250), hex("07 00 00 00 02 04 51 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_dpi_led_off_apply() {
        assert_eq!(cmd_dpi_led_apply(DpiLedMode::Off), hex("07 00 00 52 02 00 55 00 00 00 00 00 00 00 00 9d"));
    }

    #[test]
    fn test_dpi_led_solid() {
        assert_eq!(cmd_dpi_led_mode(DpiLedMode::Solid), Some(hex("07 00 00 4c 02 01 54 00 00 00 00 00 00 00 00 a3")));
    }

    #[test]
    fn test_dpi_led_solid_apply() {
        assert_eq!(cmd_dpi_led_apply(DpiLedMode::Solid), hex("07 00 00 52 02 01 54 00 00 00 00 00 00 00 00 9d"));
    }

    #[test]
    fn test_dpi_led_breathing() {
        assert_eq!(cmd_dpi_led_mode(DpiLedMode::Breathing), Some(hex("07 00 00 4c 02 02 53 00 00 00 00 00 00 00 00 a3")));
    }

    #[test]
    fn test_dpi_led_breathing_apply() {
        // Apply frame always sends 0x01 (enabled) regardless of Solid vs Breathing
        assert_eq!(cmd_dpi_led_apply(DpiLedMode::Breathing), hex("07 00 00 52 02 01 54 00 00 00 00 00 00 00 00 9d"));
    }

    #[test]
    fn test_dpi_led_off_no_set_frame() {
        assert_eq!(cmd_dpi_led_mode(DpiLedMode::Off), None);
    }

    #[test]
    fn test_polling_125() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz125), hex("07 00 00 00 02 08 4d 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_polling_125_apply() {
        assert_eq!(cmd_polling_rate_apply(PollingRate::Hz125), hex("07 00 00 b9 02 08 4d 00 00 00 00 00 00 00 00 36"));
    }

    #[test]
    fn test_polling_500() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz500), hex("07 00 00 00 02 02 53 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_polling_500_apply() {
        assert_eq!(cmd_polling_rate_apply(PollingRate::Hz500), hex("07 00 00 b9 02 02 53 00 00 00 00 00 00 00 00 36"));
    }

    #[test]
    fn test_polling_1000() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz1000), hex("07 00 00 00 02 01 54 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_polling_1000_apply() {
        assert_eq!(cmd_polling_rate_apply(PollingRate::Hz1000), hex("07 00 00 b9 02 01 54 00 00 00 00 00 00 00 00 36"));
    }

    #[test]
    fn test_polling_2000() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz2000), hex("07 00 00 00 02 10 45 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_polling_2000_apply() {
        assert_eq!(cmd_polling_rate_apply(PollingRate::Hz2000), hex("07 00 00 b9 02 10 45 00 00 00 00 00 00 00 00 36"));
    }

    #[test]
    fn test_polling_4000() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz4000), hex("07 00 00 00 02 20 35 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_polling_4000_apply() {
        assert_eq!(cmd_polling_rate_apply(PollingRate::Hz4000), hex("07 00 00 b9 02 20 35 00 00 00 00 00 00 00 00 36"));
    }

    #[test]
    fn test_polling_8000() {
        assert_eq!(cmd_polling_rate(PollingRate::Hz8000), hex("07 00 00 00 02 40 15 00 00 00 00 00 00 00 00 ef"));
    }

    #[test]
    fn test_lod_07() {
        assert_eq!(cmd_lod(Lod::Mm07), hex("07 00 00 0a 02 03 52 00 00 00 00 00 00 00 00 e5"));
    }

    #[test]
    fn test_lod_1mm() {
        assert_eq!(cmd_lod(Lod::Mm1), hex("07 00 00 0a 02 01 54 00 00 00 00 00 00 00 00 e5"));
    }

    #[test]
    fn test_lod_2mm() {
        assert_eq!(cmd_lod(Lod::Mm2), hex("07 00 00 0a 02 02 53 00 00 00 00 00 00 00 00 e5"));
    }

    #[test]
    fn test_linear_correction_on() {
        assert_eq!(cmd_linear_correction(true), hex("07 00 00 af 02 01 54 00 00 00 00 00 00 00 00 40"));
    }

    #[test]
    fn test_linear_correction_off() {
        assert_eq!(cmd_linear_correction(false), hex("07 00 00 af 02 00 55 00 00 00 00 00 00 00 00 40"));
    }

    #[test]
    fn test_waveform_control_on() {
        assert_eq!(cmd_waveform_control(true), hex("07 00 00 b1 02 01 54 00 00 00 00 00 00 00 00 3e"));
    }

    #[test]
    fn test_waveform_control_off() {
        assert_eq!(cmd_waveform_control(false), hex("07 00 00 b1 02 00 55 00 00 00 00 00 00 00 00 3e"));
    }

    #[test]
    fn test_motion_sync_on() {
        assert_eq!(cmd_motion_sync(true), hex("07 00 00 ab 02 01 54 00 00 00 00 00 00 00 00 44"));
    }

    #[test]
    fn test_motion_sync_off() {
        assert_eq!(cmd_motion_sync(false), hex("07 00 00 ab 02 00 55 00 00 00 00 00 00 00 00 44"));
    }

    #[test]
    fn test_work_mode_low()  { assert_eq!(cmd_work_mode(0), hex("07 00 00 b9 02 00 55 00 00 00 00 00 00 00 00 36")); }
    #[test]
    fn test_work_mode_high() { assert_eq!(cmd_work_mode(1), hex("07 00 00 b9 02 01 54 00 00 00 00 00 00 00 00 36")); }

    #[test]
    fn test_debounce_8ms()  { assert_eq!(cmd_debounce(8),  hex("07 00 00 a9 02 08 4d 00 00 00 00 00 00 00 00 46")); }
    #[test]
    fn test_debounce_20ms() { assert_eq!(cmd_debounce(20), hex("07 00 00 a9 02 14 41 00 00 00 00 00 00 00 00 46")); }
    #[test]
    fn test_debounce_0ms()  { assert_eq!(cmd_debounce(0),  hex("07 00 00 a9 02 00 55 00 00 00 00 00 00 00 00 46")); }

    #[test]
    fn test_working_mode_off() {
        assert_eq!(cmd_working_mode(0), hex("07 00 00 b5 02 00 55 00 00 00 00 00 00 00 00 3a"));
    }

    #[test]
    fn test_working_mode_on() {
        assert_eq!(cmd_working_mode(1), hex("07 00 00 b5 02 01 54 00 00 00 00 00 00 00 00 3a"));
    }

    #[test]
    fn test_rage_time_1s()  { assert_eq!(cmd_rage_time(1),  hex("07 00 00 b7 02 01 54 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_3s()  { assert_eq!(cmd_rage_time(3),  hex("07 00 00 b7 02 03 52 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_6s()  { assert_eq!(cmd_rage_time(6),  hex("07 00 00 b7 02 06 4f 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_12s() { assert_eq!(cmd_rage_time(12), hex("07 00 00 b7 02 0c 49 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_18s() { assert_eq!(cmd_rage_time(18), hex("07 00 00 b7 02 12 43 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_36s() { assert_eq!(cmd_rage_time(36), hex("07 00 00 b7 02 24 31 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_60s() { assert_eq!(cmd_rage_time(60), hex("07 00 00 b7 02 3c 19 00 00 00 00 00 00 00 00 38")); }
    #[test]
    fn test_rage_time_90s() { assert_eq!(cmd_rage_time(90), hex("07 00 00 b7 02 5a fb 00 00 00 00 00 00 00 00 38")); }

    #[test]
    fn test_long_distance_on() {
        assert_eq!(cmd_long_distance(true),  hex("16 00 00 00 0a 01 00 00 00 00 00 00 00 00 00 2c"));
    }

    #[test]
    fn test_long_distance_off() {
        assert_eq!(cmd_long_distance(false), hex("16 00 00 00 0a 00 00 00 00 00 00 00 00 00 00 2d"));
    }

    #[test]
    fn test_fps20k_on() {
        assert_eq!(cmd_fps20k(true),  hex("07 00 00 e1 02 01 54 00 00 00 00 00 00 00 00 0e"));
    }

    #[test]
    fn test_fps20k_off() {
        assert_eq!(cmd_fps20k(false), hex("07 00 00 e1 02 00 55 00 00 00 00 00 00 00 00 0e"));
    }

    #[test]
    fn test_receiver_led_hz() {
        assert_eq!(cmd_receiver_led(1), hex("14 00 00 00 0a 01 00 ff 00 ff ff 00 ff 00 00 32"));
    }

    #[test]
    fn test_receiver_led_battery() {
        assert_eq!(cmd_receiver_led(2), hex("14 00 00 00 0a 02 00 ff 00 ff ff 00 ff 00 00 31"));
    }

    #[test]
    fn test_receiver_led_warning_only() {
        assert_eq!(cmd_receiver_led(3), hex("14 00 00 00 0a 03 00 ff 00 ff ff 00 ff 00 00 30"));
    }

    #[test]
    fn test_block_read_addr_00() {
        assert_eq!(cmd_block_read(0x00), hex("08 00 00 00 0a 00 00 00 00 00 00 00 00 00 00 3b"));
    }

    #[test]
    fn test_block_read_addr_0a() {
        assert_eq!(cmd_block_read(0x0A), hex("08 00 00 0a 0a 00 00 00 00 00 00 00 00 00 00 31"));
    }

    #[test]
    fn test_block_read_addr_14() {
        assert_eq!(cmd_block_read(0x14), hex("08 00 00 14 0a 00 00 00 00 00 00 00 00 00 00 27"));
    }

    #[test]
    fn test_block_read_addr_aa() {
        assert_eq!(cmd_block_read(0xAA), hex("08 00 00 aa 0a 00 00 00 00 00 00 00 00 00 00 91"));
    }

    #[test]
    fn test_read_dpi_stage() {
        assert_eq!(cmd_read_dpi_stage(), hex("12 00 00 00 00 00 00 00 00 00 00 00 00 00 00 3b"));
    }

    #[test]
    fn test_set_dpi_5600_stage4() {
        assert_eq!(cmd_set_dpi(3, 5600), hex("07 00 00 18 04 6f 6f 00 77 00 00 00 00 00 00 d5"));
    }

    #[test]
    fn test_set_dpi_stage_addresses() {
        assert_eq!(dpi_stage_addr(0), 0x0C);
        assert_eq!(dpi_stage_addr(1), 0x10);
        assert_eq!(dpi_stage_addr(2), 0x14);
        assert_eq!(dpi_stage_addr(3), 0x18);
        // Each stage write targets its own slot address.
        assert_eq!(cmd_set_dpi(0, 5600)[3], 0x0C);
        assert_eq!(cmd_set_dpi(1, 5600)[3], 0x10);
        assert_eq!(cmd_set_dpi(2, 5600)[3], 0x14);
    }

    #[test]
    fn test_set_dpi_inner_checksum() {
        // 400 DPI: raw = 400/50 - 1 = 7. Inner checksum 0x55 - 7 - 7 = 0x47.
        let f = cmd_set_dpi(0, 400);
        assert_eq!(f[5], 0x07);
        assert_eq!(f[6], 0x07);
        assert_eq!(f[7], 0x00);
        assert_eq!(f[8], 0x47);
        // 800 DPI: raw = 15. 0x55 - 15 - 15 = 0x37.
        let f = cmd_set_dpi(1, 800);
        assert_eq!(f[5], 0x0F);
        assert_eq!(f[8], 0x37);
    }

    #[test]
    fn test_set_dpi_high_range_uses_high_byte() {
        // 42000 DPI: raw = 839 = 0x0347 -> lo 0x47, hi 0x03 (extrapolated).
        let f = cmd_set_dpi(3, 42000);
        assert_eq!(f[5], 0x47);
        assert_eq!(f[6], 0x47);
        assert_eq!(f[7], 0x03);
        assert_eq!(
            f[8],
            0x55u8.wrapping_sub(0x47).wrapping_sub(0x47).wrapping_sub(0x03)
        );
    }
}