From f3d82ce511f7b7977aa2e6cf75426a5aeddf0813 Mon Sep 17 00:00:00 2001 From: Centralfire2112 <113206164+Centralfire2112@users.noreply.github.com> Date: Wed, 11 Nov 2026 19:38:40 +0200 Subject: [PATCH 1/6] Scyrox: support the wired V8 (0xf5f6) and name the V6 by MID - Add the V8 on its cable, 0x3554:0xf5f6, to the Scyrox catalog with the same 3950 / legacy-layout settings as its 8K dongle. - Send the vendor's 0x01 handshake once per connection on the V8 entries and name the mouse by MID (V8: 1/10/11, V6: 2/12/13), since the vendor configurator gives both models the same product ids and controls. - Verified on a wired V8 (firmware v2.20): full readStatus and a 1000 -> 2000 -> 1000 Hz polling-rate round trip. V6 is untested. --- docs/scyrox-v8-testing.md | 33 ++++++++++- src/drivers/lamzu-atlantis/client.test.ts | 30 ++++++++++ src/drivers/lamzu-atlantis/hid.test.ts | 4 +- src/drivers/lamzu-atlantis/hid.ts | 10 +++- src/drivers/scyrox/hid.test.ts | 68 +++++++++++++++-------- src/drivers/scyrox/hid.ts | 38 ++++++++++++- src/scyrox/index.ts | 63 ++++++++++++++++++++- 7 files changed, 217 insertions(+), 29 deletions(-) diff --git a/docs/scyrox-v8-testing.md b/docs/scyrox-v8-testing.md index 93e27fe2..2c90ac5d 100644 --- a/docs/scyrox-v8-testing.md +++ b/docs/scyrox-v8-testing.md @@ -28,6 +28,35 @@ UI strings), including a screenshot of it connected to the same mouse. (byte 6: `01` awake, `00` asleep). While it reads `00`, every other command goes unanswered. +## Wired V8 (0xf5f6) + +- Device: "SCYROX V8", VID/PID `0x3554:0xf5f6`, release `0x0220`, mouse + firmware v2.20. Same collection layout as the dongle: `0xff02:2` with + report 8 on interface 1, plus `0xff05`, `0xff03`, `0x000c:1`, `0x0001:0x80` + and `0xff04:2`; interface 0 a keyboard, interface 2 the mouse. +- `ScyroxHidClient.readStatus` through node-hid on Windows: "Scyrox V8", + one stage at 1,600 DPI, 1,000 Hz, battery 45% / 3,829 mV charging, + profile 1, debounce 0 ms, sleep 300 s, motion sync and angle snapping on, + ripple off, performance off, 20K on, firmware "Mouse v2.20". +- Polling rate round trip: 1,000 → 2,000 Hz (read back 2,000), then + 2,000 → 1,000 Hz (read back 1,000). +- Handshake (command `0x01`): a bare request fails with status 1; the + configurator's payload (four random bytes, four zeros) is answered with + payload `84 bf 7a f2 3e 01 02`: CID `0x3e`, MID `0x01` (V8), type `0x02` + (wired 1K). + +## V6 identification + +The configurator (S-center 3.1.0, `cfg.json`) lists only five Scyrox +product ids: wired `0xF5F6` and `0xF515`, wireless `0xF5F4`, `0xF5F7` and +`0xF517`. It tells models apart by the handshake's MID, not by product id, +and gives the V8 (MID 1, 10, 11) and the V6 (MID 2, 12, 13) the same 3950 +sensor, 30,000 DPI ceiling and controls. `ScyroxHidClient` therefore sends +the handshake once per connection on the V8 entries and names the mouse +"Scyrox V6" for a V6 MID; a refused or unanswered handshake keeps the +catalog's "Scyrox V8". No V6 has been connected yet, and `0xF5F4` (sensor +unknown) is not claimed. + ## Protocol family The V8 speaks the same CompX report-8 flash protocol as the V8S, and every @@ -115,8 +144,8 @@ differences, which the catalog follows: was, as a round trip ending on the rate read first. - The sleep reading: the flash held 180 (30 minutes), while the configurator screenshot showed "1min", likely its default before the device read. -- Whether the V6 enumerates with the same dongle id. It would read the same - fields (same sensor, same ceiling) but be named "Scyrox V8". +- A V6 on hardware: its product ids, and the MID-based name. +- What `0xF5F4` is. The configurator lists it as a wireless mouse id. - The 4,000 and 8,000 Hz bytes on the V8: the configurator offers them, but neither has been read from this mouse. diff --git a/src/drivers/lamzu-atlantis/client.test.ts b/src/drivers/lamzu-atlantis/client.test.ts index 2a345899..93d02a4f 100644 --- a/src/drivers/lamzu-atlantis/client.test.ts +++ b/src/drivers/lamzu-atlantis/client.test.ts @@ -51,6 +51,8 @@ class FakeAtlantis extends EventTarget { opens = 0; /** Set to drop replies, so a caller's timeout path can be exercised. */ mute = false; + /** A Scyrox MID to answer the 0x01 handshake with; null refuses it. */ + handshakeMid: number | null = null; /** Adds a leading byte to the input DataView, as a real event can. */ offsetReplies = false; /** Replies queued while held, released by releaseReplies(). */ @@ -135,6 +137,10 @@ class FakeAtlantis extends EventTarget { reply.set([1, 0x24], 5); } else if (command === CLEAR_SETTINGS) { this.resets += 1; + } else if (command === 0x01 && this.handshakeMid !== null) { + // The wired V8's reply: four echoed key bytes, CID 0x3e, MID, type 2. + reply[4] = 8; + reply.set([0x84, 0xbf, 0x7a, 0xf2, 0x3e, this.handshakeMid, 0x02], 5); } else { reply[1] = 1; } @@ -282,6 +288,30 @@ test("a 3955 sensor's stages are read and written at 6912, not the legacy fields await client.close(); }); +test("a Scyrox on the V8's product ids is named by the handshake's MID", async () => { + for (const [productId, mid, name] of [ + [0xf5f6, 0x01, "Scyrox V8"], + [0xf5f6, 0x02, "Scyrox V6"], + [0xf5f7, 0x0c, "Scyrox V6"], + [0xf5f7, 0x0a, "Scyrox V8"], + ] as const) { + const device = new FakeAtlantis(productId); + device.handshakeMid = mid; + const client = new ScyroxHidClient(device as unknown as HIDDevice); + assert.equal((await client.readStatus()).name, name); + const handshake = device.sent.find((packet) => packet[0] === 0x01)!; + assert.deepEqual([...handshake.subarray(9, 13)], [0, 0, 0, 0], "four random bytes, then four zeros"); + await client.close(); + } +}); + +test("a refused handshake keeps the catalog's name", async () => { + const device = new FakeAtlantis(0xf5f6); + const client = new ScyroxHidClient(device as unknown as HIDDevice); + assert.equal((await client.readStatus()).name, "Scyrox V8"); + await client.close(); +}); + test("a Scyrox V8 reads and writes its stages in the legacy fields, up to 30,000", async () => { const device = new FakeAtlantis(0xf5f7); // The constructor's two legacy stages, 400 and 1,600, as the V8 keeps them. diff --git a/src/drivers/lamzu-atlantis/hid.test.ts b/src/drivers/lamzu-atlantis/hid.test.ts index e8093e30..3ba5ef6c 100644 --- a/src/drivers/lamzu-atlantis/hid.test.ts +++ b/src/drivers/lamzu-atlantis/hid.test.ts @@ -55,8 +55,8 @@ test("the wired mouse and every catalogued receiver are claimed", () => { test("other devices on CompX's shared vendor id are left alone", () => { // VXE R1 SE+ transports, a Teevolution Terra Pro, a VGN Dragonfly F2 Master+ // and Pulsar's own 4K receiver all enumerate under 0x3554, as do the Scyrox - // V8S, its dongle and the V8's dongle, which have their own registered client. - for (const productId of [0xf58e, 0xf58f, 0xf520, 0xfb56, 0x0002, 0xf515, 0xf517, 0xf5f7]) { + // V8S, its dongle, the V8 and its dongle, which have their own registered client. + for (const productId of [0xf58e, 0xf58f, 0xf520, 0xfb56, 0x0002, 0xf515, 0xf517, 0xf5f6, 0xf5f7]) { assert.equal(LamzuAtlantisHidClient.isSupported(device(LAMZU_ATLANTIS_VENDOR_ID, productId)), false); } }); diff --git a/src/drivers/lamzu-atlantis/hid.ts b/src/drivers/lamzu-atlantis/hid.ts index 331d89ed..480e0b0e 100644 --- a/src/drivers/lamzu-atlantis/hid.ts +++ b/src/drivers/lamzu-atlantis/hid.ts @@ -321,6 +321,7 @@ export class LamzuAtlantisHidClient { return await this.transaction(async () => { if (live && this.lastStatus) return await this.readLiveStatus(this.lastStatus); + await this.identify(); const battery = lamzuAtlantisDecodeBattery(await this.request(COMMAND.batteryLevel)); const profileCount = this.onboardProfileCount(); const activeProfile = profileCount > 0 ? (await this.request(COMMAND.getCurrentConfig))[0] ?? 0 : null; @@ -891,8 +892,15 @@ export class LamzuAtlantisHidClient { return await run; } + /** + * Runs at the start of every full status read, inside the transaction and + * before the name is computed, so a subclass can tell models apart that share + * a product id. The default has nothing to ask. + */ + protected async identify(): Promise {} + /** Unqueued: the caller already holds the transaction lock. */ - private async request(command: number, address = 0, payload: readonly number[] = []): Promise { + protected async request(command: number, address = 0, payload: readonly number[] = []): Promise { return await this.exchange(command, address, payload); } diff --git a/src/drivers/scyrox/hid.test.ts b/src/drivers/scyrox/hid.test.ts index fa894fe5..71a9af83 100644 --- a/src/drivers/scyrox/hid.test.ts +++ b/src/drivers/scyrox/hid.test.ts @@ -2,9 +2,13 @@ import assert from "node:assert/strict"; import test from "node:test"; import { + SCYROX_CID, SCYROX_PRODUCT_IDS, SCYROX_V8S_LIFT_OFF_MILLIMETRES, SCYROX_VENDOR_ID, + scyroxDecodeHandshake, + scyroxEncodeHandshake, + scyroxModelForMid, scyroxProduct, } from "@openmouse/protocol/scyrox"; import { @@ -15,9 +19,11 @@ import { import { ScyroxHidClient } from "./hid.ts"; import { createSupportedClient, deviceBrand } from "../registry.ts"; -/** The V8S on its cable and its Turbo 8k dongle; the V8's dongle is 0xf5f7. */ +/** The V8S on its cable and its Turbo 8k dongle; the V8 on its cable and its dongle. */ const V8S_PRODUCT_IDS = [0xf515, 0xf517]; +const V8_WIRED = 0xf5f6; const V8_DONGLE = 0xf5f7; +const V8_PRODUCT_IDS = [V8_WIRED, V8_DONGLE]; function collection( usagePage: number, @@ -53,7 +59,7 @@ const device = ( collections: HIDCollectionInfo[] = SCYROX_COLLECTIONS, ): HIDDevice => ({ vendorId, productId, productName: "Scyrox V8S", collections } as unknown as HIDDevice); -test("the V8S on both transports and the V8's dongle are claimed", () => { +test("the V8S and the V8 are claimed on both transports", () => { for (const productId of SCYROX_PRODUCT_IDS) { assert.ok(ScyroxHidClient.isSupported(device(SCYROX_VENDOR_ID, productId))); } @@ -86,13 +92,14 @@ test("the registry creates the Scyrox client under the Scyrox brand", () => { const client = createSupportedClient(device(SCYROX_VENDOR_ID, productId)); assert.ok(client instanceof ScyroxHidClient); assert.equal(deviceBrand(client), "Scyrox"); - assert.equal(client.displayName(), productId === V8_DONGLE ? "Scyrox V8" : "Scyrox V8S"); + assert.equal(client.displayName(), V8_PRODUCT_IDS.includes(productId) ? "Scyrox V8" : "Scyrox V8S"); } }); test("only the dongles report themselves as wireless", () => { assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, 0xf515)).isWireless(), false); assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, 0xf517)).isWireless(), true); + assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, V8_WIRED)).isWireless(), false); assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, V8_DONGLE)).isWireless(), true); }); @@ -155,28 +162,32 @@ test("both V8S transports read their DPI stages from the 3955 region", () => { }); test("the V8 keeps its 3950 stages in the legacy fields, up to 30,000 DPI", () => { - const product = scyroxProduct(SCYROX_VENDOR_ID, V8_DONGLE)!; - // The mouse read five legacy stages matching the configurator; the - // ceiling is the configurator's own for this mouse's 3950 sensor. - assert.equal(product.dpiLayout ?? "legacy", "legacy"); - assert.equal(product.maxDpi, 30000); - assert.equal(product.dpiStep, 50); - assert.equal(product.maxDpiStages, 5); - assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, V8_DONGLE)).maxDpi(), 30000); + for (const productId of V8_PRODUCT_IDS) { + const product = scyroxProduct(SCYROX_VENDOR_ID, productId)!; + // The mouse read five legacy stages matching the configurator; the + // ceiling is the configurator's own for this mouse's 3950 sensor. + assert.equal(product.dpiLayout ?? "legacy", "legacy"); + assert.equal(product.maxDpi, 30000); + assert.equal(product.dpiStep, 50); + assert.equal(product.maxDpiStages, 5); + assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)).maxDpi(), 30000); + } }); test("the V8 leaves out what was not verified on it", async () => { - const product = scyroxProduct(SCYROX_VENDOR_ID, V8_DONGLE)!; - // Its 3950 lift-off codes (3, 1, 2 for 0.7, 1 and 2 mm) fit neither the - // two-stop write nor the 3955 scale; its angle fields read unsealed; the - // restore command was never sent to it. - assert.equal(product.liftOffMillimetres, undefined); - assert.notEqual(product.supportsAngleTuning, true); - assert.notEqual(product.supportsFactoryReset, true); - // Flash 173 and 183 held the same timer on hardware. - assert.equal(product.mirrorSleepToPerformanceTime, true); - const client = new ScyroxHidClient(device(SCYROX_VENDOR_ID, V8_DONGLE)); - await assert.rejects(() => client.setLiftOffDistance("Low")); + for (const productId of V8_PRODUCT_IDS) { + const product = scyroxProduct(SCYROX_VENDOR_ID, productId)!; + // Its 3950 lift-off codes (3, 1, 2 for 0.7, 1 and 2 mm) fit neither the + // two-stop write nor the 3955 scale; its angle fields read unsealed; the + // restore command was never sent to it. + assert.equal(product.liftOffMillimetres, undefined); + assert.notEqual(product.supportsAngleTuning, true); + assert.notEqual(product.supportsFactoryReset, true); + // Flash 173 and 183 held the same timer on hardware. + assert.equal(product.mirrorSleepToPerformanceTime, true); + const client = new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)); + await assert.rejects(() => client.setLiftOffDistance("Low")); + } }); test("the sensor-mode register is not offered as a performance toggle", async () => { @@ -185,3 +196,16 @@ test("the sensor-mode register is not offered as a performance toggle", async () await assert.rejects(() => client.setHyperMode(true)); } }); + +test("the handshake decodes the wired V8's reply and maps MIDs to models", () => { + // Payload of the wired V8's reply on hardware: 84 bf 7a f2 3e 01 02. + assert.deepEqual( + scyroxDecodeHandshake(Uint8Array.of(0x84, 0xbf, 0x7a, 0xf2, 0x3e, 0x01, 0x02, 0, 0, 0)), + { cid: SCYROX_CID, mid: 1, type: 2 }, + ); + assert.equal(scyroxDecodeHandshake(Uint8Array.of(1, 2, 3)), null); + assert.deepEqual(scyroxEncodeHandshake([0x112, 0x34, 0x56, 0x78]), [0x12, 0x34, 0x56, 0x78, 0, 0, 0, 0]); + for (const mid of [1, 10, 11]) assert.equal(scyroxModelForMid(mid), "V8"); + for (const mid of [2, 12, 13]) assert.equal(scyroxModelForMid(mid), "V6"); + assert.equal(scyroxModelForMid(5), undefined); +}); diff --git a/src/drivers/scyrox/hid.ts b/src/drivers/scyrox/hid.ts index 9a43e567..7e4ef72e 100644 --- a/src/drivers/scyrox/hid.ts +++ b/src/drivers/scyrox/hid.ts @@ -1,5 +1,14 @@ import { LamzuAtlantisHidClient } from "../lamzu-atlantis/hid.ts"; -import { SCYROX_V8S_20K_ADDRESS, scyroxProduct } from "@openmouse/protocol/scyrox"; +import { + SCYROX_CID, + SCYROX_V8S_20K_ADDRESS, + scyroxDecodeHandshake, + scyroxEncodeHandshake, + scyroxModelForMid, + scyroxProduct, +} from "@openmouse/protocol/scyrox"; + +const HANDSHAKE_COMMAND = 0x01; /** * Scyrox's CompX generation: the V8S mouse (wired 0x3554:0xf515) and its @@ -22,10 +31,37 @@ import { SCYROX_V8S_20K_ADDRESS, scyroxProduct } from "@openmouse/protocol/scyro * verified (see docs/scyrox-v8-testing.md). */ export class ScyroxHidClient extends LamzuAtlantisHidClient { + /** The model the handshake's MID named; null until read, or if it failed. */ + private identifiedModel: string | null = null; + private identityRead = false; + constructor(device: HIDDevice) { super(device, scyroxProduct(device.vendorId, device.productId) ?? null); } + /** + * The V8 and the V6 share product ids (the vendor tool tells them apart by + * MID alone), so the 3950 entries ask once per connection. A refusal or a + * silent mouse behind the dongle keeps the catalog's name. + */ + protected override async identify(): Promise { + if (this.identityRead) return; + this.identityRead = true; + const product = scyroxProduct(this.device.vendorId, this.device.productId); + if (product?.model !== "V8") return; + try { + const random = Array.from({ length: 4 }, () => Math.floor(Math.random() * 256)); + const identity = scyroxDecodeHandshake(await this.request(HANDSHAKE_COMMAND, 0, scyroxEncodeHandshake(random))); + if (identity?.cid === SCYROX_CID) this.identifiedModel = scyroxModelForMid(identity.mid) ?? null; + } catch { + // Keep the catalog name. + } + } + + override displayName(): string { + return this.identifiedModel ? `Scyrox ${this.identifiedModel}` : super.displayName(); + } + static override isSupported(device: HIDDevice): boolean { return scyroxProduct(device.vendorId, device.productId) !== undefined && LamzuAtlantisHidClient.hasConfigCollection(device); diff --git a/src/scyrox/index.ts b/src/scyrox/index.ts index 20d0acfc..bbeb897d 100644 --- a/src/scyrox/index.ts +++ b/src/scyrox/index.ts @@ -28,8 +28,51 @@ export const SCYROX_VENDOR_ID = 0x3554; export const SCYROX_V8S_CID = 0x3e; export const SCYROX_V8S_MID = 0x05; +/** + * Every Scyrox reports CID 62 (0x3e); the model is the MID, not the product + * id. The vendor configurator (S-center 3.1.0, cfg.json) groups the MIDs by + * model and gives the V8 and the V6 the same 3950 sensor, 30,000 DPI ceiling + * and controls, so a V6 enumerates on the V8's product ids and only its name + * differs. Hardware: a wired V8 (0xf5f6, firmware v2.20) answered CID 0x3e, + * MID 0x01, type 0x02 (wired). + */ +export const SCYROX_CID = 0x3e; +export const SCYROX_V8_MIDS: readonly number[] = [1, 10, 11]; +export const SCYROX_V6_MIDS: readonly number[] = [2, 12, 13]; + +/** + * The command 0x01 handshake payload as the configurator sends it: four + * random bytes, then four zero bytes. A bare 0x01 is refused with status 1. + */ +export function scyroxEncodeHandshake(random: readonly number[] = [0, 0, 0, 0]): number[] { + return [...random.slice(0, 4).map((value) => value & 0xff), 0, 0, 0, 0]; +} + +export interface ScyroxIdentity { + cid: number; + mid: number; + /** Connection type: 0/1/4/5 wireless at 1K/4K/2K/8K, 2/3 wired at 1K/8K. */ + type: number; +} + +/** + * Reads CID, MID and type from the handshake reply's payload (bytes 9-11 of + * the raw report, which is payload offsets 4-6). + */ +export function scyroxDecodeHandshake(payload: Uint8Array): ScyroxIdentity | null { + if (payload.length < 7) return null; + return { cid: payload[4]!, mid: payload[5]!, type: payload[6]! }; +} + +/** The model a MID names, for the 3950 generation that shares product ids. */ +export function scyroxModelForMid(mid: number): "V8" | "V6" | undefined { + if (SCYROX_V8_MIDS.includes(mid)) return "V8"; + if (SCYROX_V6_MIDS.includes(mid)) return "V6"; + return undefined; +} + /** Product ids this brand owns on CompX's shared vendor id. */ -export const SCYROX_PRODUCT_IDS: readonly number[] = [0xf515, 0xf517, 0xf5f7]; +export const SCYROX_PRODUCT_IDS: readonly number[] = [0xf515, 0xf517, 0xf5f6, 0xf5f7]; /** * The "20K" switch: 20,000 FPS sensor scanning, which the vendor configurator @@ -118,6 +161,24 @@ export const SCYROX_PRODUCTS: ReadonlyMap = new Map([ supportsFactoryReset: true, mirrorSleepToPerformanceTime: true, }], + // The V8 on its cable: "SCYROX V8", 0x3554:0xf5f6, release 0x0220. Same + // mouse and sensor as behind the 8K dongle below, so the same fields. + [0xf5f6, { + brand: "Scyrox", + model: "V8", + wireless: false, + pollingRates: RATES_V8S, + rateFamily: "pulsar", + dpiLayout: "legacy", + verified: true, + minDpi: 50, + maxDpi: 30000, + dpiStep: 50, + maxDpiStages: 5, + supportsLiftOffDistance: false, + supportsHyperMode: false, + mirrorSleepToPerformanceTime: true, + }], // The V8's "SCYROX 8K Dongle". The vendor configurator offers the V8S's // seven rates for it, and the mouse held 0x10 while the configurator showed // 2,000 Hz, so it shares the CompX rate bytes. From c74e25560e3b9602f11da4572dabada66c445f3b Mon Sep 17 00:00:00 2001 From: Centralfire2112 <113206164+Centralfire2112@users.noreply.github.com> Date: Wed, 11 Nov 2026 20:51:08 +0200 Subject: [PATCH 2/6] Scyrox: record the V6 verified on hardware over the 8K dongle A V6 on 0x3554:0xf5f7 answered MID 2, was named "Scyrox V6" and read every field cleanly (firmware v2.24, legacy stage layout). Read-only. --- docs/scyrox-v8-testing.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/scyrox-v8-testing.md b/docs/scyrox-v8-testing.md index 2c90ac5d..bc872d89 100644 --- a/docs/scyrox-v8-testing.md +++ b/docs/scyrox-v8-testing.md @@ -54,8 +54,29 @@ and gives the V8 (MID 1, 10, 11) and the V6 (MID 2, 12, 13) the same 3950 sensor, 30,000 DPI ceiling and controls. `ScyroxHidClient` therefore sends the handshake once per connection on the V8 entries and names the mouse "Scyrox V6" for a V6 MID; a refused or unanswered handshake keeps the -catalog's "Scyrox V8". No V6 has been connected yet, and `0xF5F4` (sensor -unknown) is not claimed. +catalog's "Scyrox V8". `0xF5F4` (sensor unknown) is not claimed. + +### V6 on hardware + +A Scyrox V6 on the "SCYROX 8K Dongle" (`0x3554:0xf5f7`, release `0x0216`, +dongle version `02 16`), read through node-hid on Windows with a read-only +build of `ScyroxHidClient` that refuses every command but 0x01, 0x03, 0x04, +0x08, 0x0e, 0x12 and 0x1d: + +- Same product id and collection layout as the V8's dongle. +- Handshake payload `e0 ec fc 6b 3e 02 05`: CID `0x3e`, MID 2 (V6), type 5 + (wireless 8K). The client named it "Scyrox V6". +- Firmware `02 24`, v2.24, the version the configurator's V6 upgrade tool + ships. +- `readStatus`: three stages 500/800/1,600 with stage 2 active, 1,000 Hz, + battery 75% / 4,013 mV discharging, profile 1, debounce 0 ms, sleep 300 s, + motion sync, angle snapping, ripple control and performance on, 20K off, + firmware "Mouse v2.24". Every field carried its seal. +- The raw flash agrees field by field: rate `01 54`, three stages `03 52`, + active stage `02 53`, 20K `00 55`, legacy stages `09 09 00 43`, + `0f 0f 00 37` and `1f 1f 00 17` (500, 800, 1,600 DPI), sleep `1e 37` at 173 + and 183, performance `01 54` at 181. The 3955 region at 6912 reads `ff`, as + on the V8, confirming the legacy layout. ## Protocol family @@ -144,7 +165,7 @@ differences, which the catalog follows: was, as a round trip ending on the rate read first. - The sleep reading: the flash held 180 (30 minutes), while the configurator screenshot showed "1min", likely its default before the device read. -- A V6 on hardware: its product ids, and the MID-based name. +- The V6 on its cable (expected `0xf5f6`) and any write to a V6. - What `0xF5F4` is. The configurator lists it as a wireless mouse id. - The 4,000 and 8,000 Hz bytes on the V8: the configurator offers them, but neither has been read from this mouse. From ff70a8956c33e9a77e362055dbfb888eed62e1cd Mon Sep 17 00:00:00 2001 From: Centralfire2112 <113206164+Centralfire2112@users.noreply.github.com> Date: Wed, 11 Nov 2026 21:27:30 +0200 Subject: [PATCH 3/6] Scyrox V8/V6: lift-off, wired rate cap, angle mode, 30 ms debounce, restore - Lift-off: the 3950's out-of-order codes (3, 1, 2 = 0.7, 1, 2 mm) map to the Low/Medium/High stops through a new liftOffStopCodes product table. - The wired V8 (0xf5f6) offers 125-1000 Hz only; higher rates are dongle-only. - Mouse Angle Mode and Restore turned on; Key Response Time up to 30 ms via a new maxDebounceMs product field. - Verified on a V8 over the dongle: lift-off, stage colour, angle and debounce round trips, each read back and restored. --- src/drivers/lamzu-atlantis/client.test.ts | 26 +++++++++++++ src/drivers/lamzu-atlantis/hid.ts | 47 +++++++++++++++++++---- src/drivers/scyrox/hid.test.ts | 27 +++++++++---- src/lamzu/atlantis.ts | 10 +++++ src/scyrox/index.ts | 37 ++++++++++++++++-- 5 files changed, 128 insertions(+), 19 deletions(-) diff --git a/src/drivers/lamzu-atlantis/client.test.ts b/src/drivers/lamzu-atlantis/client.test.ts index 93d02a4f..c65bffe4 100644 --- a/src/drivers/lamzu-atlantis/client.test.ts +++ b/src/drivers/lamzu-atlantis/client.test.ts @@ -305,6 +305,32 @@ test("a Scyrox on the V8's product ids is named by the handshake's MID", async ( } }); +test("a Scyrox V8 maps the 3950's lift-off codes onto the three stops", async () => { + for (const productId of [0xf5f6, 0xf5f7]) { + const device = new FakeAtlantis(productId); + device.writeField(FLASH.liftOffDistance, [3]); // 0.7 mm, as the V8 read + const client = new ScyroxHidClient(device as unknown as HIDDevice); + const status = await client.readStatus(); + assert.equal(status.liftOffDistance, "Low"); + assert.deepEqual(status.supportedLiftOffDistances, ["Low", "Medium", "High"]); + assert.equal(status.liftOffScale, undefined); + + for (const [stop, code] of [["High", 2], ["Medium", 1], ["Low", 3]] as const) { + assert.equal(await client.setLiftOffDistance(stop), stop); + assert.equal(device.flash[FLASH.liftOffDistance], code, `${stop} writes code ${code}`); + } + await client.close(); + } +}); + +test("a code outside the 3950 table reads as no stop", async () => { + const device = new FakeAtlantis(0xf5f7); + device.writeField(FLASH.liftOffDistance, [5]); + const client = new ScyroxHidClient(device as unknown as HIDDevice); + assert.equal((await client.readStatus()).liftOffDistance, null); + await client.close(); +}); + test("a refused handshake keeps the catalog's name", async () => { const device = new FakeAtlantis(0xf5f6); const client = new ScyroxHidClient(device as unknown as HIDDevice); diff --git a/src/drivers/lamzu-atlantis/hid.ts b/src/drivers/lamzu-atlantis/hid.ts index 480e0b0e..80c59da5 100644 --- a/src/drivers/lamzu-atlantis/hid.ts +++ b/src/drivers/lamzu-atlantis/hid.ts @@ -293,7 +293,7 @@ export class LamzuAtlantisHidClient { } getDebounceMaxMs(): number { - return DEBOUNCE_MAX_MS; + return this.debounceMaxMs(); } getSleepOptions(): readonly number[] { @@ -352,16 +352,20 @@ export class LamzuAtlantisHidClient { } const liftOffMillimetres = this.product()?.liftOffMillimetres; - const liftOffRaw = this.supports("supportsLiftOffDistance") || liftOffMillimetres + const liftOffStopCodes = this.product()?.liftOffStopCodes; + const liftOffRaw = this.supports("supportsLiftOffDistance") || liftOffMillimetres || liftOffStopCodes ? (await this.readField(FLASH.liftOffDistance, 1))[0] ?? 0 : null; const liftOffScale = liftOffMillimetres && liftOffRaw !== null ? lamzuAtlantisLiftOffScale(liftOffRaw, liftOffMillimetres) : undefined; - // A scale product's byte is a height code, not one of Lamzu's two stops. - const liftOffDistance = liftOffScale - ? lamzuAtlantisNearestLiftOffStop(liftOffScale.millimetres) - : liftOffRaw === null || liftOffMillimetres ? null : lamzuAtlantisDecodeLiftOffDistance(liftOffRaw); + // A scale product's byte is a height code, not one of Lamzu's two stops, + // and a stop-code product's byte is whatever its own table says. + const liftOffDistance = liftOffStopCodes + ? this.liftOffStopForCode(liftOffRaw) + : liftOffScale + ? lamzuAtlantisNearestLiftOffStop(liftOffScale.millimetres) + : liftOffRaw === null || liftOffMillimetres ? null : lamzuAtlantisDecodeLiftOffDistance(liftOffRaw); const debounceMs = (await this.readField(FLASH.debounceTime, 1))[0] ?? 0; const sleepRaw = this.supports("supportsSleepTimeout") ? (await this.readField(FLASH.sleepTime, 1))[0] ?? 0 @@ -429,6 +433,9 @@ export class LamzuAtlantisHidClient { ...(sleepRaw !== null ? { sleepTimeout: sleepRaw > 0 ? sleepRaw * TIMER_STEP_SECONDS : null } : {}), liftOffDistance, ...(liftOffScale !== undefined ? { liftOffScale } : {}), + ...(liftOffStopCodes + ? { supportedLiftOffDistances: (["Low", "Medium", "High"] as const).filter((stop) => liftOffStopCodes[stop] !== undefined) } + : {}), ...(motionSync !== undefined ? { motionSync } : {}), ...(angleSnapping !== undefined ? { angleSnapping } : {}), ...(rippleControl !== undefined ? { rippleControl } : {}), @@ -485,8 +492,31 @@ export class LamzuAtlantisHidClient { }); } + private debounceMaxMs(): number { + return this.product()?.maxDebounceMs ?? DEBOUNCE_MAX_MS; + } + + private liftOffStopForCode(code: number | null): LiftOffDistance | null { + const table = this.product()?.liftOffStopCodes; + if (!table || code === null) return null; + return (["Low", "Medium", "High"] as const).find((stop) => table[stop] === code) ?? null; + } + async setLiftOffDistance(value: LiftOffDistance): Promise { return await this.transaction(async () => { + const stopCodes = this.product()?.liftOffStopCodes; + if (stopCodes) { + const code = stopCodes[value as "Low" | "Medium" | "High"]; + if (code === undefined) { + throw new Error(`This mouse does not support a ${value.toLowerCase()} lift-off distance.`); + } + const confirmed = this.liftOffStopForCode(await this.writeByte(FLASH.liftOffDistance, code)); + if (confirmed !== value) { + throw new Error(`The mouse kept a ${String(confirmed).toLowerCase()} lift-off distance instead of ${value.toLowerCase()}.`); + } + this.patch({ liftOffDistance: confirmed }); + return confirmed; + } if (!this.supports("supportsLiftOffDistance")) { throw new Error("This mouse does not expose a configurable lift-off distance."); } @@ -561,8 +591,9 @@ export class LamzuAtlantisHidClient { async setDebounceTime(milliseconds: number): Promise { return await this.transaction(async () => { - if (!Number.isInteger(milliseconds) || milliseconds < 0 || milliseconds > DEBOUNCE_MAX_MS) { - throw new Error(`Debounce must be a whole number of milliseconds between 0 and ${DEBOUNCE_MAX_MS}.`); + const max = this.debounceMaxMs(); + if (!Number.isInteger(milliseconds) || milliseconds < 0 || milliseconds > max) { + throw new Error(`Debounce must be a whole number of milliseconds between 0 and ${max}.`); } const confirmed = await this.writeByte(FLASH.debounceTime, milliseconds); if (confirmed !== milliseconds) { diff --git a/src/drivers/scyrox/hid.test.ts b/src/drivers/scyrox/hid.test.ts index 71a9af83..47521d10 100644 --- a/src/drivers/scyrox/hid.test.ts +++ b/src/drivers/scyrox/hid.test.ts @@ -104,7 +104,7 @@ test("only the dongles report themselves as wireless", () => { }); test("the vendor's polling-rate list is offered on both transports", () => { - for (const productId of SCYROX_PRODUCT_IDS) { + for (const productId of SCYROX_PRODUCT_IDS.filter((id) => id !== V8_WIRED)) { assert.deepEqual( new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)).getSupportedPollingRates(), [125, 250, 500, 1000, 2000, 4000, 8000], @@ -112,6 +112,17 @@ test("the vendor's polling-rate list is offered on both transports", () => { } }); +test("the V8 and V6 on their cable stop at 1,000 Hz; the rest is dongle-only", () => { + assert.deepEqual( + new ScyroxHidClient(device(SCYROX_VENDOR_ID, V8_WIRED)).getSupportedPollingRates(), + [125, 250, 500, 1000], + ); + assert.deepEqual( + new ScyroxHidClient(device(SCYROX_VENDOR_ID, V8_DONGLE)).getSupportedPollingRates(), + [125, 250, 500, 1000, 2000, 4000, 8000], + ); +}); + test("lift-off is the 3955's five-height scale, not the two-stop write", async () => { for (const productId of V8S_PRODUCT_IDS) { assert.deepEqual( @@ -174,19 +185,19 @@ test("the V8 keeps its 3950 stages in the legacy fields, up to 30,000 DPI", () = } }); -test("the V8 leaves out what was not verified on it", async () => { +test("the V8 offers the configurator's 3950 controls", async () => { for (const productId of V8_PRODUCT_IDS) { const product = scyroxProduct(SCYROX_VENDOR_ID, productId)!; // Its 3950 lift-off codes (3, 1, 2 for 0.7, 1 and 2 mm) fit neither the - // two-stop write nor the 3955 scale; its angle fields read unsealed; the - // restore command was never sent to it. + // two-stop write nor the 3955 scale, so they get a stop table. The angle + // fields read sealed on a V8 and a V6, and Key Response Time goes to 30 ms. assert.equal(product.liftOffMillimetres, undefined); - assert.notEqual(product.supportsAngleTuning, true); - assert.notEqual(product.supportsFactoryReset, true); + assert.deepEqual(product.liftOffStopCodes, { Low: 3, Medium: 1, High: 2 }); + assert.equal(product.supportsAngleTuning, true); + assert.equal(product.supportsFactoryReset, true); + assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)).getDebounceMaxMs(), 30); // Flash 173 and 183 held the same timer on hardware. assert.equal(product.mirrorSleepToPerformanceTime, true); - const client = new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)); - await assert.rejects(() => client.setLiftOffDistance("Low")); } }); diff --git a/src/lamzu/atlantis.ts b/src/lamzu/atlantis.ts index 5b5dff38..297235c0 100644 --- a/src/lamzu/atlantis.ts +++ b/src/lamzu/atlantis.ts @@ -184,6 +184,16 @@ export interface LamzuAtlantisProduct { * `liftOffScale`, and the coarse `liftOffDistance` is the nearest stop. */ liftOffMillimetres?: readonly number[]; + /** + * When set, the lift-off byte holds one of these codes, each one of the + * shared stops, rather than Lamzu's two stops or a 1-to-n scale. The 3950 + * codes its heights out of order (3, 1, 2 for 0.7, 1 and 2 mm), which only + * an explicit table describes. The status lists the keys as + * `supportedLiftOffDistances`. + */ + liftOffStopCodes?: Readonly>>; + /** The longest debounce the vendor offers, in ms; the client default is 15. */ + maxDebounceMs?: number; /** Controls below default to off: no Lamzu unit has exercised them. */ supportsAngleTuning?: boolean; supportsFactoryReset?: boolean; diff --git a/src/scyrox/index.ts b/src/scyrox/index.ts index bbeb897d..17089993 100644 --- a/src/scyrox/index.ts +++ b/src/scyrox/index.ts @@ -100,6 +100,21 @@ export type ScyroxProduct = LamzuAtlantisProduct; */ const RATES_V8S = [125, 250, 500, 1000, 2000, 4000, 8000] as const; +/** + * The V8 and V6 on their cable report handshake type 2, which the vendor + * configurator treats as a 1,000 Hz ceiling (type 3 would be wired 8K), and + * it offers nothing above 1,000 Hz there. The higher rates are dongle-only. + */ +const RATES_V8_WIRED = [125, 250, 500, 1000] as const; + +/** + * The 3950's three lift-off heights. The configurator's English strings list + * them as code 3 = 0.7 mm, 1 = 1 mm and 2 = 2 mm (mouse.sensor.LODOptions, + * "3950"), so they map onto the shared stops low to high in that order. A + * V8 read code 3 and a V6 read code 1. + */ +export const SCYROX_3950_LIFT_OFF_STOP_CODES = { Low: 3, Medium: 1, High: 2 } as const; + /** * Both transports speak CompX's own rate bytes (`rateFamily: "pulsar"`): the * vendor configurator writes 0x10, 0x20 and 0x40 for 2,000, 4,000 and 8,000 Hz, @@ -167,7 +182,7 @@ export const SCYROX_PRODUCTS: ReadonlyMap = new Map([ brand: "Scyrox", model: "V8", wireless: false, - pollingRates: RATES_V8S, + pollingRates: RATES_V8_WIRED, rateFamily: "pulsar", dpiLayout: "legacy", verified: true, @@ -176,6 +191,14 @@ export const SCYROX_PRODUCTS: ReadonlyMap = new Map([ dpiStep: 50, maxDpiStages: 5, supportsLiftOffDistance: false, + liftOffStopCodes: SCYROX_3950_LIFT_OFF_STOP_CODES, + // Mouse Angle Mode: flash 189 and 191 read sealed on a V8 (angle 0, on) + // and a V6 (angle 0, off), and the configurator shows the slider. + supportsAngleTuning: true, + // The configurator's Restore button, command 0x09, as on the V8S. + supportsFactoryReset: true, + // The configurator's Key Response Time goes to 30 ms on the 3950 entries. + maxDebounceMs: 30, supportsHyperMode: false, mirrorSleepToPerformanceTime: true, }], @@ -202,9 +225,17 @@ export const SCYROX_PRODUCTS: ReadonlyMap = new Map([ dpiStep: 50, maxDpiStages: 5, // The 3950 codes its three heights 3, 1 and 2 (0.7, 1 and 2 mm), which - // neither Lamzu's two stops nor a 1-to-n scale describes, so lift-off - // stays out until the byte has its own decoder. + // neither Lamzu's two stops nor a 1-to-n scale describes, so they get an + // explicit stop table. supportsLiftOffDistance: false, + liftOffStopCodes: SCYROX_3950_LIFT_OFF_STOP_CODES, + // Mouse Angle Mode: flash 189 and 191 read sealed on a V8 (angle 0, on) + // and a V6 (angle 0, off), and the configurator shows the slider. + supportsAngleTuning: true, + // The configurator's Restore button, command 0x09, as on the V8S. + supportsFactoryReset: true, + // The configurator's Key Response Time goes to 30 ms on the 3950 entries. + maxDebounceMs: 30, supportsHyperMode: false, // Flash 173 and 183 both held 180 (30 minutes in the configurator's // table), as its sleep setter writes them. From 2c14b0890bed163a87e32036bcfe557e3802b519 Mon Sep 17 00:00:00 2001 From: Centralfire2112 <113206164+Centralfire2112@users.noreply.github.com> Date: Thu, 12 Nov 2026 08:16:41 +0200 Subject: [PATCH 4/6] Scyrox: link the 20K switch to performance mode 20K scanning only runs under Competitive Mode (performance mode here). Turning 20K on now turns performance mode on first instead of failing, so a flash that stages both no longer fails when turbo is written first. Turning performance mode off now turns 20K off too, so the mouse is not left with a stored 20K byte it would act on later. --- src/drivers/lamzu-atlantis/client.test.ts | 34 +++++++++++++++++------ src/drivers/lamzu-atlantis/hid.ts | 30 ++++++++++++++++---- 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/src/drivers/lamzu-atlantis/client.test.ts b/src/drivers/lamzu-atlantis/client.test.ts index c65bffe4..91788086 100644 --- a/src/drivers/lamzu-atlantis/client.test.ts +++ b/src/drivers/lamzu-atlantis/client.test.ts @@ -355,23 +355,41 @@ test("a Scyrox V8 reads and writes its stages in the legacy fields, up to 30,000 await client.close(); }); -test("the 20K switch reads and writes flash 8, gated on performance mode", async () => { +test("the 20K switch reads and writes flash 8, linked to performance mode", async () => { const device = new FakeAtlantis(0xf515, FLASH.sensor3955DpiValues + 6); device.writeField(FLASH.dpiStageCount, [1]); device.flash.set(lamzuAtlantisEncodeDpiStage3955(1600), FLASH.sensor3955DpiValues); const client = new ScyroxHidClient(device as unknown as HIDDevice); assert.equal((await client.readStatus()).turboMode, false, "off while the byte is zero"); - // The vendor configurator disables the switch until Competitive Mode is on; - // the driver refuses the write rather than flipping both switches. + // 20K only runs under Competitive Mode, so turning it on turns that on too. device.writeField(FLASH.performanceState, [0]); - await assert.rejects(() => client.setTurboMode(true), /requires performance mode/); - assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 0, "the refused write never reached the device"); - - device.writeField(FLASH.performanceState, [1]); assert.equal(await client.setTurboMode(true), true); assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 1); - assert.equal((await client.readStatus(true)).turboMode, true); + let status = await client.readStatus(true); + assert.equal(status.turboMode, true); + assert.equal(status.performanceMode, true, "performance mode came on with 20K"); + + // Turning 20K off leaves performance mode alone. + assert.equal(await client.setTurboMode(false), false); + status = await client.readStatus(true); + assert.equal(status.turboMode, false); + assert.equal(status.performanceMode, true); + + // Turning performance mode off takes 20K with it. + assert.equal(await client.setTurboMode(true), true); + assert.equal(await client.setPerformanceMode(false), false); + assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 0); + status = await client.readStatus(true); + assert.equal(status.turboMode, false, "20K went off with performance mode"); + assert.equal(status.performanceMode, false); + + // Both on in either order, as a staged flash might write them. + assert.equal(await client.setPerformanceMode(true), true); + assert.equal(await client.setTurboMode(true), true); + status = await client.readStatus(true); + assert.equal(status.turboMode, true); + assert.equal(status.performanceMode, true); await client.close(); }); diff --git a/src/drivers/lamzu-atlantis/hid.ts b/src/drivers/lamzu-atlantis/hid.ts index 80c59da5..a7c580cb 100644 --- a/src/drivers/lamzu-atlantis/hid.ts +++ b/src/drivers/lamzu-atlantis/hid.ts @@ -648,7 +648,24 @@ export class LamzuAtlantisHidClient { async setPerformanceMode(enabled: boolean): Promise { if (!this.supports("supportsPerformanceMode")) throw new Error("This mouse does not expose performance mode."); - return await this.setFlag(FLASH.performanceState, enabled, "performanceMode", "competition mode"); + const turboAddress = this.turboModeAddress(); + if (enabled || turboAddress === null) { + return await this.setFlag(FLASH.performanceState, enabled, "performanceMode", "competition mode"); + } + // 20K scanning only runs under Competitive Mode, so switching that off + // takes the 20K switch with it, as the vendor configurator does, rather + // than leaving a stored 20K byte the mouse would act on later. + return await this.transaction(async () => { + if ((await this.readRaw(turboAddress, 1))[0] !== 0) { + const turbo = (await this.writeByte(turboAddress, 0)) !== 0; + if (turbo) throw new Error("The mouse left turbo mode on."); + this.patch({ turboMode: false }); + } + const confirmed = (await this.writeByte(FLASH.performanceState, 0)) === 1; + if (confirmed) throw new Error("The mouse left competition mode on."); + this.patch({ performanceMode: false }); + return false; + }); } async setHyperMode(enabled: boolean): Promise { @@ -657,16 +674,19 @@ export class LamzuAtlantisHidClient { } /** - * 20,000 FPS sensor scanning, shown as the shared "turbo mode" switch. The - * vendor configurator refuses to enable it until Competitive Mode is on, and - * so does this, rather than flipping a second switch on the user's behalf. + * 20,000 FPS sensor scanning, shown as the shared "turbo mode" switch. It + * only runs under Competitive Mode (performance mode here), so turning it on + * turns that on first. Refusing instead failed the whole flash whenever both + * switches were staged together and turbo happened to be written first. */ async setTurboMode(enabled: boolean): Promise { return await this.transaction(async () => { const address = this.turboModeAddress(); if (address === null) throw new Error("This mouse does not expose a turbo frame-rate mode."); if (enabled && (await this.readField(FLASH.performanceState, 1))[0] !== 1) { - throw new Error("20,000 FPS mode requires performance mode to be turned on first."); + const performance = (await this.writeByte(FLASH.performanceState, 1)) === 1; + if (!performance) throw new Error("The mouse left competition mode off, which 20,000 FPS mode needs."); + this.patch({ performanceMode: true }); } const confirmed = (await this.writeByte(address, enabled ? 1 : 0)) === 1; if (confirmed !== enabled) throw new Error(`The mouse left turbo mode ${confirmed ? "on" : "off"}.`); From edb8b4c692cde0ee1471df963520bfde202938fb Mon Sep 17 00:00:00 2001 From: Centralfire2112 <113206164+Centralfire2112@users.noreply.github.com> Date: Thu, 12 Nov 2026 08:39:59 +0200 Subject: [PATCH 5/6] Scyrox: address review on the V8/V6 support - Turbo/performance link is opt-in: a new linksTurboToPerformanceMode() hook, off by default, so other Atlantis products keep refusing turbo without performance mode and write performance mode on its own. Only the Scyrox client opts in. Tested with a non-Scyrox turbo product. - The link is one helper, and a pair that fails halfway puts the first switch back, so a failed performance-off no longer loses the 20K setting. - identify() retries: only a reply settles the handshake. An unanswered or refused one is asked again on a full read at least 30 s later, so a V6 asleep behind the dongle is named once it wakes, and a silent mouse costs one timeout per interval rather than one per read. Fixed key bytes replace Math.random(). - The V8-only writes (lift-off stop table, angle tuning, 30 ms debounce, Restore) are offered only once the handshake names a V8. A V6 or an unidentified mouse gets the shared controls. - A wired mouse reporting handshake type 3 (wired 8K) gets the 8K rates. - A lift-off code outside the 3950 table reads as no stop but keeps the stops on offer, so choosing one corrects it. Tested. - Docs: V6 marked read-only, the V8 notes brought up to date. --- docs/scyrox-v8-testing.md | 84 ++++++++--- src/drivers/lamzu-atlantis/client.test.ts | 169 +++++++++++++++++++++- src/drivers/lamzu-atlantis/hid.ts | 94 +++++++++--- src/drivers/scyrox/hid.test.ts | 10 +- src/drivers/scyrox/hid.ts | 81 +++++++++-- src/scyrox/index.ts | 22 ++- 6 files changed, 395 insertions(+), 65 deletions(-) diff --git a/docs/scyrox-v8-testing.md b/docs/scyrox-v8-testing.md index bc872d89..87d2f131 100644 --- a/docs/scyrox-v8-testing.md +++ b/docs/scyrox-v8-testing.md @@ -52,13 +52,33 @@ product ids: wired `0xF5F6` and `0xF515`, wireless `0xF5F4`, `0xF5F7` and `0xF517`. It tells models apart by the handshake's MID, not by product id, and gives the V8 (MID 1, 10, 11) and the V6 (MID 2, 12, 13) the same 3950 sensor, 30,000 DPI ceiling and controls. `ScyroxHidClient` therefore sends -the handshake once per connection on the V8 entries and names the mouse -"Scyrox V6" for a V6 MID; a refused or unanswered handshake keeps the -catalog's "Scyrox V8". `0xF5F4` (sensor unknown) is not claimed. - -### V6 on hardware - -A Scyrox V6 on the "SCYROX 8K Dongle" (`0x3554:0xf5f7`, release `0x0216`, +the handshake on the V8 entries and names the mouse "Scyrox V6" for a V6 +MID. `0xF5F4` (sensor unknown) is not claimed. + +- **Unanswered or refused handshake:** the client keeps the catalog's + "Scyrox V8" and asks again on a full read at least 30 s later. A mouse + asleep behind the dongle is still named once it wakes, and a silent mouse + costs one timeout per interval, not one per read. The first reply settles + it for the connection. +- **Key bytes:** the handshake sends fixed key bytes (`4f 4d 53 01`) rather + than the configurator's random ones, so captured traces are reproducible. +- **Connection type:** the reply's type byte is used too. A wired mouse + reporting type 3 (wired 8K) is offered the 8K rate list instead of the + wired 1K default. + +### Writes are gated on the V8 + +The 3950 entries' extra writes (the lift-off stop table, angle tuning, +the 30 ms Key Response Time and Restore) were verified on a V8 only. The V6 +reads different values in the angle fields at 189 and 191, so a write there +is unverified on a V6. The client therefore offers these controls only after +the handshake has named the mouse a V8. A V6, and a mouse that has not +answered yet, gets the shared Atlantis controls only. + +### V6 on hardware (read-only) + +No write has been sent to a V6. What was verified is identification and a +full read. A Scyrox V6 on the "SCYROX 8K Dongle" (`0x3554:0xf5f7`, release `0x0216`, dongle version `02 16`), read through node-hid on Windows with a read-only build of `ScyroxHidClient` that refuses every command but 0x01, 0x03, 0x04, 0x08, 0x0e, 0x12 and 0x1d: @@ -145,27 +165,55 @@ differences, which the catalog follows: - Lift-off: the 3950 offers three heights coded 3, 1 and 2 for 0.7, 1 and 2 mm. That order fits neither the Atlantis two-stop write nor the 1-to-n - scale the V8S uses, so lift-off is not offered (`supportsLiftOffDistance: - false`, no `liftOffMillimetres`). -- Angle tuning: the configurator shows it only when 189 and 191 are sealed, - and both read `ff`, so `supportsAngleTuning` stays off. -- Key response time: the configurator allows up to 30 ms on the V8; the - Atlantis client offers 0-15 ms. + scale the V8S uses, so the catalog gives it an explicit stop table + (`liftOffStopCodes: { Low: 3, Medium: 1, High: 2 }`) and no + `liftOffMillimetres`. A byte outside the table reads as no stop + (`liftOffDistance: null`). The three stops stay on offer, so choosing one + writes a known code over it. +- Angle tuning: the configurator shows it only when 189 and 191 are sealed. + On the first V8 dump both read `ff`. A later read found them sealed (angle + 0, on), and the angle round trip below was verified on that V8, so + `supportsAngleTuning` is on for an identified V8. +- Key response time: the configurator allows up to 30 ms on the V8 + (`maxDebounceMs: 30`); the Atlantis client's default ceiling is 15 ms. +- Restore: the configurator's Restore button, command `0x09`, as on the + V8S (`supportsFactoryReset`). - Sleep: 173 and 183 held the same value, as the configurator's Scyrox sleep setter writes them, so `mirrorSleepToPerformanceTime` stays on. - SensorMode at 185 is left alone (`supportsHyperMode: false`), as on the V8S. - The 20K switch at flash 8 is shown for the V8 too (`FpsScanShow: true`) and - read `00 55`. + read `00 55`. The configurator greys it out until Competitive Mode + (performance mode, flash 181) is on, so on Scyrox the two are linked: + - 20K on turns performance mode on first. + - Performance mode off turns 20K off first. + - If the second write of a pair does not take, the first is put back. + - Other Atlantis products keep the two switches separate. + +The lift-off stop table, angle tuning, the 30 ms ceiling and Restore are +offered only once the handshake names the mouse a V8 (see "Writes are gated +on the V8"). + +## Verified writes on the V8 + +On the V8 behind its 8K dongle, each was written, read back and restored: + +- the polling rate +- lift-off +- the DPI stage colour +- the angle +- debounce ## Not yet verified -- DPI, lift-off, angle tuning, sleep, debounce, the 20K switch, profiles, - buttons and Restore were never written to the V8. Only the polling rate - was, as a round trip ending on the rate read first. +- Sleep, the 20K switch and its link to performance mode, profiles, buttons + and Restore have not been written to a V8. - The sleep reading: the flash held 180 (30 minutes), while the configurator screenshot showed "1min", likely its default before the device read. -- The V6 on its cable (expected `0xf5f6`) and any write to a V6. +- The V6 on its cable (expected `0xf5f6`) and any write to a V6. V6 writes + beyond the shared Atlantis controls stay off until one is verified. +- A wired 8K Scyrox (handshake type 3); the rate list it gets comes from the + configurator's type table. - What `0xF5F4` is. The configurator lists it as a wireless mouse id. - The 4,000 and 8,000 Hz bytes on the V8: the configurator offers them, but neither has been read from this mouse. diff --git a/src/drivers/lamzu-atlantis/client.test.ts b/src/drivers/lamzu-atlantis/client.test.ts index 91788086..83f7710a 100644 --- a/src/drivers/lamzu-atlantis/client.test.ts +++ b/src/drivers/lamzu-atlantis/client.test.ts @@ -15,7 +15,7 @@ import { } from "@openmouse/protocol/lamzu"; import { pulsarVgnEncodeDpi } from "@openmouse/protocol/pulsar"; import { TEEVOLUTION_KEY_CLASS as KEY, teevolutionEncodeKeyFunction } from "@openmouse/protocol/teevolution"; -import { SCYROX_V8S_20K_ADDRESS } from "@openmouse/protocol/scyrox"; +import { SCYROX_HANDSHAKE_KEY, SCYROX_V8S_20K_ADDRESS } from "@openmouse/protocol/scyrox"; import { LamzuAtlantisHidClient } from "./hid.ts"; import { NoirM1NexHidClient } from "../noir/m1-nex-hid.ts"; import { ScyroxHidClient } from "../scyrox/hid.ts"; @@ -53,6 +53,12 @@ class FakeAtlantis extends EventTarget { mute = false; /** A Scyrox MID to answer the 0x01 handshake with; null refuses it. */ handshakeMid: number | null = null; + /** The handshake's connection type: 2 wired 1K, 3 wired 8K, 5 wireless 8K. */ + handshakeType = 0x02; + /** Leaves the handshake unanswered, as a mouse asleep behind its dongle does. */ + handshakeSilent = false; + /** Flash addresses whose writes are acknowledged but never stored. */ + stuckAddresses = new Set(); /** Adds a leading byte to the input DataView, as a real event can. */ offsetReplies = false; /** Replies queued while held, released by releaseReplies(). */ @@ -113,6 +119,7 @@ class FakeAtlantis extends EventTarget { this.sent.push(Uint8Array.from(body)); this.announceReport(); if (this.mute) return; + if (this.handshakeSilent && body[0] === 0x01) return; const reply = new Uint8Array(PACKET); reply.set(body.subarray(0, 5)); @@ -122,7 +129,7 @@ class FakeAtlantis extends EventTarget { if (command === COMMAND.readFlashData) { reply.set(this.flash.subarray(address, address + length), 5); } else if (command === COMMAND.writeFlashData) { - this.flash.set(body.subarray(5, 5 + length), address); + if (!this.stuckAddresses.has(address)) this.flash.set(body.subarray(5, 5 + length), address); } else if (command === COMMAND.getCurrentConfig) { reply[4] = 1; reply[5] = this.profile; @@ -140,7 +147,7 @@ class FakeAtlantis extends EventTarget { } else if (command === 0x01 && this.handshakeMid !== null) { // The wired V8's reply: four echoed key bytes, CID 0x3e, MID, type 2. reply[4] = 8; - reply.set([0x84, 0xbf, 0x7a, 0xf2, 0x3e, this.handshakeMid, 0x02], 5); + reply.set([0x84, 0xbf, 0x7a, 0xf2, 0x3e, this.handshakeMid, this.handshakeType], 5); } else { reply[1] = 1; } @@ -300,7 +307,101 @@ test("a Scyrox on the V8's product ids is named by the handshake's MID", async ( const client = new ScyroxHidClient(device as unknown as HIDDevice); assert.equal((await client.readStatus()).name, name); const handshake = device.sent.find((packet) => packet[0] === 0x01)!; - assert.deepEqual([...handshake.subarray(9, 13)], [0, 0, 0, 0], "four random bytes, then four zeros"); + assert.deepEqual( + [...handshake.subarray(5, 13)], + [...SCYROX_HANDSHAKE_KEY, 0, 0, 0, 0], + "the fixed key bytes, then four zeros", + ); + await client.close(); + } +}); + +/** A Scyrox client that retries an unanswered handshake without waiting. */ +class EagerScyroxClient extends ScyroxHidClient { + constructor(device: HIDDevice, retryMs = 0) { + super(device); + this.identifyRetryMs = retryMs; + } +} + +const handshakes = (device: FakeAtlantis) => device.sent.filter((packet) => packet[0] === 0x01).length; + +test("a V6 asleep on the first read is still named once it wakes", async () => { + const device = new FakeAtlantis(0xf5f7); + device.handshakeMid = 0x02; + device.handshakeSilent = true; + const client = new EagerScyroxClient(device as unknown as HIDDevice); + let status = await client.readStatus(); + assert.equal(status.name, "Scyrox V8", "the catalog name while the mouse is silent"); + assert.equal(status.angleTuning, undefined, "no V8-only control before the mouse is named"); + + device.handshakeSilent = false; + status = await client.readStatus(); + assert.equal(status.name, "Scyrox V6", "asked again after waking"); + assert.equal(status.angleTuning, undefined, "a V6 gets no V8-only control either"); + const asked = handshakes(device); + await client.readStatus(); + assert.equal(handshakes(device), asked, "a reply settles it for the connection"); + await client.close(); +}); + +test("an unanswered handshake waits before asking again", async () => { + const device = new FakeAtlantis(0xf5f7); + device.handshakeSilent = true; + const client = new EagerScyroxClient(device as unknown as HIDDevice, 60_000); + await client.readStatus(); + const asked = handshakes(device); + assert.ok(asked > 0); + await client.readStatus(); + assert.equal(handshakes(device), asked, "no second timeout inside the retry interval"); + await client.close(); +}); + +test("a refused handshake is asked again on a later read", async () => { + const device = new FakeAtlantis(0xf5f6); + const client = new EagerScyroxClient(device as unknown as HIDDevice); + assert.equal((await client.readStatus()).name, "Scyrox V8"); + device.handshakeMid = 0x01; + const status = await client.readStatus(); + assert.equal(status.name, "Scyrox V8"); + assert.deepEqual(status.supportedLiftOffDistances, ["Low", "Medium", "High"], "V8 controls once named"); + await client.close(); +}); + +test("the V8-only writes wait for the handshake to name a V8", async () => { + for (const mid of [null, 0x02] as const) { + const device = new FakeAtlantis(0xf5f7); + device.handshakeMid = mid; + const client = new ScyroxHidClient(device as unknown as HIDDevice); + const status = await client.readStatus(); + assert.equal(status.supportedLiftOffDistances, undefined); + assert.equal(client.getDebounceMaxMs(), 15); + await assert.rejects(() => client.setLiftOffDistance("Low")); + await assert.rejects(() => client.setAngleTuning(5), /angle tuning/); + await assert.rejects(() => client.setDebounceTime(30), /between 0 and 15/); + await assert.rejects(() => client.factoryReset()); + await client.close(); + } + const device = new FakeAtlantis(0xf5f7); + device.handshakeMid = 0x01; + const client = new ScyroxHidClient(device as unknown as HIDDevice); + await client.readStatus(); + assert.equal(client.getDebounceMaxMs(), 30); + assert.equal(await client.setDebounceTime(30), 30); + await client.close(); +}); + +test("a wired Scyrox reporting the wired 8K type offers the 8K rates", async () => { + for (const [type, rates] of [ + [0x02, [125, 250, 500, 1000]], + [0x03, [125, 250, 500, 1000, 2000, 4000, 8000]], + ] as const) { + const device = new FakeAtlantis(0xf5f6); + device.handshakeMid = 0x01; + device.handshakeType = type; + const client = new ScyroxHidClient(device as unknown as HIDDevice); + await client.readStatus(); + assert.deepEqual(client.getSupportedPollingRates(), rates); await client.close(); } }); @@ -308,6 +409,7 @@ test("a Scyrox on the V8's product ids is named by the handshake's MID", async ( test("a Scyrox V8 maps the 3950's lift-off codes onto the three stops", async () => { for (const productId of [0xf5f6, 0xf5f7]) { const device = new FakeAtlantis(productId); + device.handshakeMid = 0x01; device.writeField(FLASH.liftOffDistance, [3]); // 0.7 mm, as the V8 read const client = new ScyroxHidClient(device as unknown as HIDDevice); const status = await client.readStatus(); @@ -323,11 +425,19 @@ test("a Scyrox V8 maps the 3950's lift-off codes onto the three stops", async () } }); -test("a code outside the 3950 table reads as no stop", async () => { +test("a code outside the 3950 table reads as no stop and can be corrected", async () => { const device = new FakeAtlantis(0xf5f7); + device.handshakeMid = 0x01; device.writeField(FLASH.liftOffDistance, [5]); const client = new ScyroxHidClient(device as unknown as HIDDevice); - assert.equal((await client.readStatus()).liftOffDistance, null); + const status = await client.readStatus(); + // No stop is claimed for a code the table does not know, but the stops stay + // on offer so choosing one writes a known code over it. + assert.equal(status.liftOffDistance, null); + assert.deepEqual(status.supportedLiftOffDistances, ["Low", "Medium", "High"]); + assert.equal(await client.setLiftOffDistance("Medium"), "Medium"); + assert.equal(device.flash[FLASH.liftOffDistance], 1); + assert.equal((await client.readStatus()).liftOffDistance, "Medium"); await client.close(); }); @@ -393,6 +503,53 @@ test("the 20K switch reads and writes flash 8, linked to performance mode", asyn await client.close(); }); +test("a linked 20K write that fails halfway puts the first switch back", async () => { + const device = new FakeAtlantis(0xf515, FLASH.sensor3955DpiValues + 6); + device.writeField(FLASH.dpiStageCount, [1]); + device.flash.set(lamzuAtlantisEncodeDpiStage3955(1600), FLASH.sensor3955DpiValues); + const client = new ScyroxHidClient(device as unknown as HIDDevice); + await client.readStatus(); + + // 20K on: performance mode goes on first, then 20K does not take. + device.writeField(FLASH.performanceState, [0]); + device.stuckAddresses.add(SCYROX_V8S_20K_ADDRESS); + await assert.rejects(() => client.setTurboMode(true), /turbo mode off.*, so competition mode was put back/); + assert.equal(device.flash[FLASH.performanceState], 0, "performance mode rolled back"); + device.stuckAddresses.clear(); + + // Performance off: 20K goes off first, then performance mode does not take. + device.writeField(FLASH.performanceState, [1]); + device.writeField(SCYROX_V8S_20K_ADDRESS, [1]); + device.stuckAddresses.add(FLASH.performanceState); + await assert.rejects(() => client.setPerformanceMode(false), /competition mode on.*, so turbo mode was put back/); + assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 1, "the 20K setting is not lost"); + await client.close(); +}); + +/** A non-Scyrox Atlantis product with a turbo byte, which does not opt into the link. */ +class UnlinkedTurboClient extends LamzuAtlantisHidClient { + protected override turboModeAddress(): number | null { + return SCYROX_V8S_20K_ADDRESS; + } +} + +test("other Atlantis products keep turbo and performance mode separate", async () => { + const device = new FakeAtlantis(); + const client = new UnlinkedTurboClient(device as unknown as HIDDevice); + await client.readStatus(); + + device.writeField(FLASH.performanceState, [0]); + await assert.rejects(() => client.setTurboMode(true), /requires performance mode/); + assert.equal(device.flash[FLASH.performanceState], 0, "performance mode was not turned on"); + assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 0, "the refused write never reached the device"); + + device.writeField(FLASH.performanceState, [1]); + assert.equal(await client.setTurboMode(true), true); + assert.equal(await client.setPerformanceMode(false), false); + assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 1, "turbo is left as it was"); + await client.close(); +}); + test("a mouse without the 20K byte does not expose turbo mode", async () => { const client = clientFor(new FakeAtlantis()); assert.equal((await client.readStatus()).turboMode, undefined); diff --git a/src/drivers/lamzu-atlantis/hid.ts b/src/drivers/lamzu-atlantis/hid.ts index a7c580cb..ece28a41 100644 --- a/src/drivers/lamzu-atlantis/hid.ts +++ b/src/drivers/lamzu-atlantis/hid.ts @@ -58,6 +58,13 @@ const ANGLE_TUNING_MAX_DEGREES = 30; type LiftOffDistance = NonNullable; +/** One side of a linked pair of one-byte flags (turbo and performance mode). */ +interface LinkedFlag { + address: number; + field: "turboMode" | "performanceMode"; + label: string; +} + /** * Lamzu's Atlantis generation (0x3554), which speaks CompX's report-8 * interrupt protocol rather than the feature-report page/command protocol the @@ -112,7 +119,7 @@ export class LamzuAtlantisHidClient { && LamzuAtlantisHidClient.hasConfigCollection(device); } - private product(): LamzuAtlantisProduct | undefined { + protected product(): LamzuAtlantisProduct | undefined { return this.productOverride ?? lamzuAtlantisProduct(this.device.vendorId, this.device.productId); } @@ -167,6 +174,17 @@ export class LamzuAtlantisHidClient { return null; } + /** + * Whether turbo and performance mode move together: turbo on turns + * performance mode on first, and performance mode off turns turbo off + * first. Off by default, where turbo on without performance mode is refused + * and performance mode is written on its own; a subclass opts in only where + * the vendor's own tool links the two. + */ + protected linksTurboToPerformanceMode(): boolean { + return false; + } + protected minimumDpi(): number { return this.product()?.minDpi ?? DPI_MIN; } @@ -649,21 +667,18 @@ export class LamzuAtlantisHidClient { async setPerformanceMode(enabled: boolean): Promise { if (!this.supports("supportsPerformanceMode")) throw new Error("This mouse does not expose performance mode."); const turboAddress = this.turboModeAddress(); - if (enabled || turboAddress === null) { + if (enabled || turboAddress === null || !this.linksTurboToPerformanceMode()) { return await this.setFlag(FLASH.performanceState, enabled, "performanceMode", "competition mode"); } - // 20K scanning only runs under Competitive Mode, so switching that off - // takes the 20K switch with it, as the vendor configurator does, rather - // than leaving a stored 20K byte the mouse would act on later. + // Linked: turbo only runs under performance mode, so switching that off + // takes turbo with it rather than leaving a stored turbo byte the mouse + // would act on later. return await this.transaction(async () => { - if ((await this.readRaw(turboAddress, 1))[0] !== 0) { - const turbo = (await this.writeByte(turboAddress, 0)) !== 0; - if (turbo) throw new Error("The mouse left turbo mode on."); - this.patch({ turboMode: false }); - } - const confirmed = (await this.writeByte(FLASH.performanceState, 0)) === 1; - if (confirmed) throw new Error("The mouse left competition mode on."); - this.patch({ performanceMode: false }); + await this.writeLinkedFlags( + { address: turboAddress, field: "turboMode", label: "turbo mode" }, + { address: FLASH.performanceState, field: "performanceMode", label: "competition mode" }, + false, + ); return false; }); } @@ -675,18 +690,24 @@ export class LamzuAtlantisHidClient { /** * 20,000 FPS sensor scanning, shown as the shared "turbo mode" switch. It - * only runs under Competitive Mode (performance mode here), so turning it on - * turns that on first. Refusing instead failed the whole flash whenever both - * switches were staged together and turbo happened to be written first. + * only runs under performance mode. Where the two are linked, turning turbo + * on turns performance mode on first; otherwise it is refused until + * performance mode is on. */ async setTurboMode(enabled: boolean): Promise { return await this.transaction(async () => { const address = this.turboModeAddress(); if (address === null) throw new Error("This mouse does not expose a turbo frame-rate mode."); if (enabled && (await this.readField(FLASH.performanceState, 1))[0] !== 1) { - const performance = (await this.writeByte(FLASH.performanceState, 1)) === 1; - if (!performance) throw new Error("The mouse left competition mode off, which 20,000 FPS mode needs."); - this.patch({ performanceMode: true }); + if (!this.linksTurboToPerformanceMode()) { + throw new Error("20,000 FPS mode requires performance mode to be turned on first."); + } + await this.writeLinkedFlags( + { address: FLASH.performanceState, field: "performanceMode", label: "competition mode" }, + { address, field: "turboMode", label: "turbo mode" }, + true, + ); + return true; } const confirmed = (await this.writeByte(address, enabled ? 1 : 0)) === 1; if (confirmed !== enabled) throw new Error(`The mouse left turbo mode ${confirmed ? "on" : "off"}.`); @@ -866,6 +887,41 @@ export class LamzuAtlantisHidClient { }); } + /** + * Sets two linked one-byte flags to `value`, `first` then `second`, as one + * change. Each write is read back. If `second` does not take, `first` is put + * back to the byte it held before, so a failure never leaves one switch + * changed without the other. The caller holds the transaction. + */ + private async writeLinkedFlags(first: LinkedFlag, second: LinkedFlag, value: boolean): Promise { + const target = value ? 1 : 0; + const state = value ? "off" : "on"; + const before = (await this.readRaw(first.address, 1))[0] ?? 0; + if ((await this.writeByte(first.address, target)) !== target) { + throw new Error(`The mouse left ${first.label} ${state}.`); + } + let secondTook = false; + let failure: unknown = null; + try { + secondTook = (await this.writeByte(second.address, target)) === target; + } catch (error) { + failure = error; + } + if (!secondTook) { + let restored = true; + try { + restored = (await this.writeByte(first.address, before)) === before; + } catch { + restored = false; + } + const cause = failure instanceof Error ? ` (${failure.message})` : ""; + throw new Error(restored + ? `The mouse left ${second.label} ${state}${cause}, so ${first.label} was put back.` + : `The mouse left ${second.label} ${state}${cause}, and ${first.label} could not be put back.`); + } + this.patch({ [first.field]: value, [second.field]: value }); + } + /** * Both angle fields must carry their seal, which is what the vendor * configurator checks before it shows the slider at all, so a firmware diff --git a/src/drivers/scyrox/hid.test.ts b/src/drivers/scyrox/hid.test.ts index 47521d10..d919394a 100644 --- a/src/drivers/scyrox/hid.test.ts +++ b/src/drivers/scyrox/hid.test.ts @@ -185,17 +185,19 @@ test("the V8 keeps its 3950 stages in the legacy fields, up to 30,000 DPI", () = } }); -test("the V8 offers the configurator's 3950 controls", async () => { +test("the V8 catalog carries the configurator's 3950 controls", async () => { for (const productId of V8_PRODUCT_IDS) { const product = scyroxProduct(SCYROX_VENDOR_ID, productId)!; // Its 3950 lift-off codes (3, 1, 2 for 0.7, 1 and 2 mm) fit neither the - // two-stop write nor the 3955 scale, so they get a stop table. The angle - // fields read sealed on a V8 and a V6, and Key Response Time goes to 30 ms. + // two-stop write nor the 3955 scale, so they get a stop table. Key + // Response Time goes to 30 ms. The client offers these only once the + // handshake names a V8 (see the Atlantis client tests). assert.equal(product.liftOffMillimetres, undefined); assert.deepEqual(product.liftOffStopCodes, { Low: 3, Medium: 1, High: 2 }); assert.equal(product.supportsAngleTuning, true); assert.equal(product.supportsFactoryReset, true); - assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)).getDebounceMaxMs(), 30); + assert.equal(product.maxDebounceMs, 30); + assert.equal(new ScyroxHidClient(device(SCYROX_VENDOR_ID, productId)).getDebounceMaxMs(), 15, "not before the handshake"); // Flash 173 and 183 held the same timer on hardware. assert.equal(product.mirrorSleepToPerformanceTime, true); } diff --git a/src/drivers/scyrox/hid.ts b/src/drivers/scyrox/hid.ts index 7e4ef72e..ff2c633a 100644 --- a/src/drivers/scyrox/hid.ts +++ b/src/drivers/scyrox/hid.ts @@ -1,15 +1,23 @@ import { LamzuAtlantisHidClient } from "../lamzu-atlantis/hid.ts"; +import type { LamzuAtlantisProduct } from "@openmouse/protocol/lamzu"; import { SCYROX_CID, + SCYROX_HANDSHAKE_KEY, + SCYROX_POLLING_RATES_8K, + SCYROX_TYPE_WIRED_8K, SCYROX_V8S_20K_ADDRESS, scyroxDecodeHandshake, scyroxEncodeHandshake, scyroxModelForMid, scyroxProduct, + type ScyroxIdentity, } from "@openmouse/protocol/scyrox"; const HANDSHAKE_COMMAND = 0x01; +/** How long a failed handshake waits before a later full read asks again. */ +const IDENTIFY_RETRY_MS = 30_000; + /** * Scyrox's CompX generation: the V8S mouse (wired 0x3554:0xf515) and its * "Turbo 8k" dongle (0x3554:0xf517). The Atlantis client does the talking — @@ -31,9 +39,14 @@ const HANDSHAKE_COMMAND = 0x01; * verified (see docs/scyrox-v8-testing.md). */ export class ScyroxHidClient extends LamzuAtlantisHidClient { - /** The model the handshake's MID named; null until read, or if it failed. */ - private identifiedModel: string | null = null; - private identityRead = false; + /** What the handshake answered; null until a Scyrox reply was read. */ + private identity: ScyroxIdentity | null = null; + /** Set once the handshake got a reply, or has nothing to ask. */ + private identitySettled = false; + /** No new handshake before this time, after one went unanswered. */ + private nextIdentifyAt = 0; + /** Exposed so a test can retry without waiting. */ + protected identifyRetryMs = IDENTIFY_RETRY_MS; constructor(device: HIDDevice) { super(device, scyroxProduct(device.vendorId, device.productId) ?? null); @@ -41,25 +54,57 @@ export class ScyroxHidClient extends LamzuAtlantisHidClient { /** * The V8 and the V6 share product ids (the vendor tool tells them apart by - * MID alone), so the 3950 entries ask once per connection. A refusal or a - * silent mouse behind the dongle keeps the catalog's name. + * MID alone), so the 3950 entries ask until the mouse answers. A mouse + * asleep behind the dongle does not answer; the next full read after + * IDENTIFY_RETRY_MS asks again, so a silent mouse costs one timeout per + * interval rather than one per read, and a mouse that wakes is still named. */ protected override async identify(): Promise { - if (this.identityRead) return; - this.identityRead = true; - const product = scyroxProduct(this.device.vendorId, this.device.productId); - if (product?.model !== "V8") return; + if (this.identitySettled || Date.now() < this.nextIdentifyAt) return; + if (this.catalogEntry()?.model !== "V8") { + this.identitySettled = true; + return; + } try { - const random = Array.from({ length: 4 }, () => Math.floor(Math.random() * 256)); - const identity = scyroxDecodeHandshake(await this.request(HANDSHAKE_COMMAND, 0, scyroxEncodeHandshake(random))); - if (identity?.cid === SCYROX_CID) this.identifiedModel = scyroxModelForMid(identity.mid) ?? null; + const reply = await this.request(HANDSHAKE_COMMAND, 0, scyroxEncodeHandshake(SCYROX_HANDSHAKE_KEY)); + // Any reply settles it: asking again would get the same answer. + this.identitySettled = true; + const identity = scyroxDecodeHandshake(reply); + if (identity?.cid === SCYROX_CID) this.identity = identity; } catch { - // Keep the catalog name. + this.nextIdentifyAt = Date.now() + this.identifyRetryMs; } } + private catalogEntry(): LamzuAtlantisProduct | undefined { + return scyroxProduct(this.device.vendorId, this.device.productId); + } + + private identifiedModel(): "V8" | "V6" | null { + return this.identity ? scyroxModelForMid(this.identity.mid) ?? null : null; + } + + /** + * The 3950 entries' extra writes (the lift-off stop table, angle tuning, + * the 30 ms debounce ceiling and Restore) were verified on a V8 only, and a + * V6 reads different values in the angle fields, so they are offered only + * once the handshake has named the mouse a V8. A wired mouse that reports + * the wired 8K type gets the 8K rate list instead of the 1K default. + */ + protected override product(): LamzuAtlantisProduct | undefined { + const catalog = super.product(); + if (!catalog || catalog.model !== "V8") return catalog; + const rates = !catalog.wireless && this.identity?.type === SCYROX_TYPE_WIRED_8K + ? { pollingRates: SCYROX_POLLING_RATES_8K } + : {}; + if (this.identifiedModel() === "V8") return { ...catalog, ...rates }; + const { liftOffStopCodes: _stops, maxDebounceMs: _debounce, ...shared } = catalog; + return { ...shared, ...rates, supportsAngleTuning: false, supportsFactoryReset: false }; + } + override displayName(): string { - return this.identifiedModel ? `Scyrox ${this.identifiedModel}` : super.displayName(); + const model = this.identifiedModel(); + return model ? `Scyrox ${model}` : super.displayName(); } static override isSupported(device: HIDDevice): boolean { @@ -71,4 +116,12 @@ export class ScyroxHidClient extends LamzuAtlantisHidClient { protected override turboModeAddress(): number | null { return SCYROX_V8S_20K_ADDRESS; } + + /** + * The configurator greys out 20K until Competitive Mode (performance mode + * here) is on, and 20K only runs under it, so the two move together. + */ + protected override linksTurboToPerformanceMode(): boolean { + return true; + } } diff --git a/src/scyrox/index.ts b/src/scyrox/index.ts index 17089993..5c3d50d0 100644 --- a/src/scyrox/index.ts +++ b/src/scyrox/index.ts @@ -41,8 +41,15 @@ export const SCYROX_V8_MIDS: readonly number[] = [1, 10, 11]; export const SCYROX_V6_MIDS: readonly number[] = [2, 12, 13]; /** - * The command 0x01 handshake payload as the configurator sends it: four - * random bytes, then four zero bytes. A bare 0x01 is refused with status 1. + * The four key bytes this package sends in the handshake. The configurator + * sends random ones, but the mouse treats them as an opaque key, so fixed + * bytes keep captured traces reproducible. + */ +export const SCYROX_HANDSHAKE_KEY: readonly number[] = [0x4f, 0x4d, 0x53, 0x01]; + +/** + * The command 0x01 handshake payload as the configurator sends it: four key + * bytes, then four zero bytes. A bare 0x01 is refused with status 1. */ export function scyroxEncodeHandshake(random: readonly number[] = [0, 0, 0, 0]): number[] { return [...random.slice(0, 4).map((value) => value & 0xff), 0, 0, 0, 0]; @@ -55,6 +62,9 @@ export interface ScyroxIdentity { type: number; } +/** Handshake type 3: a wired mouse with an 8K ceiling, per the configurator. */ +export const SCYROX_TYPE_WIRED_8K = 3; + /** * Reads CID, MID and type from the handshake reply's payload (bytes 9-11 of * the raw report, which is payload offsets 4-6). @@ -100,10 +110,14 @@ export type ScyroxProduct = LamzuAtlantisProduct; */ const RATES_V8S = [125, 250, 500, 1000, 2000, 4000, 8000] as const; +/** Every rate the CompX table encodes, up to 8,000 Hz. */ +export const SCYROX_POLLING_RATES_8K: readonly number[] = RATES_V8S; + /** * The V8 and V6 on their cable report handshake type 2, which the vendor - * configurator treats as a 1,000 Hz ceiling (type 3 would be wired 8K), and - * it offers nothing above 1,000 Hz there. The higher rates are dongle-only. + * configurator treats as a 1,000 Hz ceiling, and it offers nothing above + * 1,000 Hz there. This is the default until the handshake answers; a wired + * mouse that reports type 3 (wired 8K) gets SCYROX_POLLING_RATES_8K instead. */ const RATES_V8_WIRED = [125, 250, 500, 1000] as const; From 56480cafb070731a8f09b73f315ae2691af64649 Mon Sep 17 00:00:00 2001 From: Centralfire2112 <113206164+Centralfire2112@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:17:38 +0200 Subject: [PATCH 6/6] Scyrox: offer the 3950 controls on the V6, tested on hardware The V6 was used and tested with the same controls as the V8 (polling rate, lift-off, stage colour, angle, debounce) and they worked as on the V8, so the lift-off stop table, angle tuning, the 30 ms debounce ceiling and Restore are offered once the handshake names a V8 or a V6. A mouse that has not answered the handshake yet still gets the shared controls only. --- docs/scyrox-v8-testing.md | 35 ++++++++++--------- src/drivers/lamzu-atlantis/client.test.ts | 41 ++++++++++++----------- src/drivers/scyrox/hid.test.ts | 2 +- src/drivers/scyrox/hid.ts | 11 +++--- 4 files changed, 47 insertions(+), 42 deletions(-) diff --git a/docs/scyrox-v8-testing.md b/docs/scyrox-v8-testing.md index 87d2f131..5df82416 100644 --- a/docs/scyrox-v8-testing.md +++ b/docs/scyrox-v8-testing.md @@ -66,19 +66,20 @@ MID. `0xF5F4` (sensor unknown) is not claimed. reporting type 3 (wired 8K) is offered the 8K rate list instead of the wired 1K default. -### Writes are gated on the V8 +### Writes wait for the handshake -The 3950 entries' extra writes (the lift-off stop table, angle tuning, -the 30 ms Key Response Time and Restore) were verified on a V8 only. The V6 -reads different values in the angle fields at 189 and 191, so a write there -is unverified on a V6. The client therefore offers these controls only after -the handshake has named the mouse a V8. A V6, and a mouse that has not -answered yet, gets the shared Atlantis controls only. +The 3950 entries' extra writes (the lift-off stop table, angle tuning, the +30 ms Key Response Time and Restore) were tested on a V8 and a V6. The +client offers them once the handshake has named the mouse either model. A +mouse that has not answered yet gets the shared Atlantis controls only. -### V6 on hardware (read-only) +### V6 on hardware -No write has been sent to a V6. What was verified is identification and a -full read. A Scyrox V6 on the "SCYROX 8K Dongle" (`0x3554:0xf5f7`, release `0x0216`, +The V6 was first checked read-only: identification and a full read. It was +then used and tested with the same controls as the V8 (see "Verified writes +on the V8 and V6"), which worked as they do on the V8. + +The read-only check used a Scyrox V6 on the "SCYROX 8K Dongle" (`0x3554:0xf5f7`, release `0x0216`, dongle version `02 16`), read through node-hid on Windows with a read-only build of `ScyroxHidClient` that refuses every command but 0x01, 0x03, 0x04, 0x08, 0x0e, 0x12 and 0x1d: @@ -191,10 +192,10 @@ differences, which the catalog follows: - Other Atlantis products keep the two switches separate. The lift-off stop table, angle tuning, the 30 ms ceiling and Restore are -offered only once the handshake names the mouse a V8 (see "Writes are gated -on the V8"). +offered only once the handshake names the mouse a V8 or a V6 (see "Writes +wait for the handshake"). -## Verified writes on the V8 +## Verified writes on the V8 and V6 On the V8 behind its 8K dongle, each was written, read back and restored: @@ -204,14 +205,16 @@ On the V8 behind its 8K dongle, each was written, read back and restored: - the angle - debounce +The V6 behind the 8K dongle was used and tested with the same controls, and +they worked as on the V8. + ## Not yet verified - Sleep, the 20K switch and its link to performance mode, profiles, buttons - and Restore have not been written to a V8. + and Restore have not been written to a V8 or V6. - The sleep reading: the flash held 180 (30 minutes), while the configurator screenshot showed "1min", likely its default before the device read. -- The V6 on its cable (expected `0xf5f6`) and any write to a V6. V6 writes - beyond the shared Atlantis controls stay off until one is verified. +- The V6 on its cable (expected `0xf5f6`). - A wired 8K Scyrox (handshake type 3); the rate list it gets comes from the configurator's type table. - What `0xF5F4` is. The configurator lists it as a wireless mouse id. diff --git a/src/drivers/lamzu-atlantis/client.test.ts b/src/drivers/lamzu-atlantis/client.test.ts index 83f7710a..e976013c 100644 --- a/src/drivers/lamzu-atlantis/client.test.ts +++ b/src/drivers/lamzu-atlantis/client.test.ts @@ -333,12 +333,12 @@ test("a V6 asleep on the first read is still named once it wakes", async () => { const client = new EagerScyroxClient(device as unknown as HIDDevice); let status = await client.readStatus(); assert.equal(status.name, "Scyrox V8", "the catalog name while the mouse is silent"); - assert.equal(status.angleTuning, undefined, "no V8-only control before the mouse is named"); + assert.equal(status.supportedLiftOffDistances, undefined, "no 3950 extras before the mouse is named"); device.handshakeSilent = false; status = await client.readStatus(); assert.equal(status.name, "Scyrox V6", "asked again after waking"); - assert.equal(status.angleTuning, undefined, "a V6 gets no V8-only control either"); + assert.deepEqual(status.supportedLiftOffDistances, ["Low", "Medium", "High"], "the 3950 extras once named"); const asked = handshakes(device); await client.readStatus(); assert.equal(handshakes(device), asked, "a reply settles it for the connection"); @@ -368,27 +368,28 @@ test("a refused handshake is asked again on a later read", async () => { await client.close(); }); -test("the V8-only writes wait for the handshake to name a V8", async () => { - for (const mid of [null, 0x02] as const) { +test("the 3950 extras wait for the handshake to name a V8 or a V6", async () => { + const unnamed = new FakeAtlantis(0xf5f7); + const client = new ScyroxHidClient(unnamed as unknown as HIDDevice); + const status = await client.readStatus(); + assert.equal(status.supportedLiftOffDistances, undefined); + assert.equal(client.getDebounceMaxMs(), 15); + await assert.rejects(() => client.setLiftOffDistance("Low")); + await assert.rejects(() => client.setAngleTuning(5), /angle tuning/); + await assert.rejects(() => client.setDebounceTime(30), /between 0 and 15/); + await assert.rejects(() => client.factoryReset()); + await client.close(); + + for (const mid of [0x01, 0x02]) { const device = new FakeAtlantis(0xf5f7); device.handshakeMid = mid; - const client = new ScyroxHidClient(device as unknown as HIDDevice); - const status = await client.readStatus(); - assert.equal(status.supportedLiftOffDistances, undefined); - assert.equal(client.getDebounceMaxMs(), 15); - await assert.rejects(() => client.setLiftOffDistance("Low")); - await assert.rejects(() => client.setAngleTuning(5), /angle tuning/); - await assert.rejects(() => client.setDebounceTime(30), /between 0 and 15/); - await assert.rejects(() => client.factoryReset()); - await client.close(); + const named = new ScyroxHidClient(device as unknown as HIDDevice); + assert.deepEqual((await named.readStatus()).supportedLiftOffDistances, ["Low", "Medium", "High"]); + assert.equal(named.getDebounceMaxMs(), 30); + assert.equal(await named.setDebounceTime(30), 30); + assert.equal(await named.setLiftOffDistance("High"), "High"); + await named.close(); } - const device = new FakeAtlantis(0xf5f7); - device.handshakeMid = 0x01; - const client = new ScyroxHidClient(device as unknown as HIDDevice); - await client.readStatus(); - assert.equal(client.getDebounceMaxMs(), 30); - assert.equal(await client.setDebounceTime(30), 30); - await client.close(); }); test("a wired Scyrox reporting the wired 8K type offers the 8K rates", async () => { diff --git a/src/drivers/scyrox/hid.test.ts b/src/drivers/scyrox/hid.test.ts index d919394a..df71d82e 100644 --- a/src/drivers/scyrox/hid.test.ts +++ b/src/drivers/scyrox/hid.test.ts @@ -191,7 +191,7 @@ test("the V8 catalog carries the configurator's 3950 controls", async () => { // Its 3950 lift-off codes (3, 1, 2 for 0.7, 1 and 2 mm) fit neither the // two-stop write nor the 3955 scale, so they get a stop table. Key // Response Time goes to 30 ms. The client offers these only once the - // handshake names a V8 (see the Atlantis client tests). + // handshake names a V8 or V6 (see the Atlantis client tests). assert.equal(product.liftOffMillimetres, undefined); assert.deepEqual(product.liftOffStopCodes, { Low: 3, Medium: 1, High: 2 }); assert.equal(product.supportsAngleTuning, true); diff --git a/src/drivers/scyrox/hid.ts b/src/drivers/scyrox/hid.ts index ff2c633a..67a449cc 100644 --- a/src/drivers/scyrox/hid.ts +++ b/src/drivers/scyrox/hid.ts @@ -86,10 +86,11 @@ export class ScyroxHidClient extends LamzuAtlantisHidClient { /** * The 3950 entries' extra writes (the lift-off stop table, angle tuning, - * the 30 ms debounce ceiling and Restore) were verified on a V8 only, and a - * V6 reads different values in the angle fields, so they are offered only - * once the handshake has named the mouse a V8. A wired mouse that reports - * the wired 8K type gets the 8K rate list instead of the 1K default. + * the 30 ms debounce ceiling and Restore) were tested on a V8 and a V6, so + * they are offered once the handshake has named the mouse either model. A + * mouse that has not answered yet gets the shared controls only. A wired + * mouse that reports the wired 8K type gets the 8K rate list instead of the + * 1K default. */ protected override product(): LamzuAtlantisProduct | undefined { const catalog = super.product(); @@ -97,7 +98,7 @@ export class ScyroxHidClient extends LamzuAtlantisHidClient { const rates = !catalog.wireless && this.identity?.type === SCYROX_TYPE_WIRED_8K ? { pollingRates: SCYROX_POLLING_RATES_8K } : {}; - if (this.identifiedModel() === "V8") return { ...catalog, ...rates }; + if (this.identifiedModel() !== null) return { ...catalog, ...rates }; const { liftOffStopCodes: _stops, maxDebounceMs: _debounce, ...shared } = catalog; return { ...shared, ...rates, supportsAngleTuning: false, supportsFactoryReset: false }; }