diff --git a/docs/scyrox-v8-testing.md b/docs/scyrox-v8-testing.md index 93e27fe2..bc872d89 100644 --- a/docs/scyrox-v8-testing.md +++ b/docs/scyrox-v8-testing.md @@ -28,6 +28,56 @@ 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". `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 The V8 speaks the same CompX report-8 flash protocol as the V8S, and every @@ -115,8 +165,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". +- 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. 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.