diff --git a/docs/scyrox-v8-testing.md b/docs/scyrox-v8-testing.md index 93e27fe2..5df82416 100644 --- a/docs/scyrox-v8-testing.md +++ b/docs/scyrox-v8-testing.md @@ -28,6 +28,77 @@ 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 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 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 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 + +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: + +- 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 @@ -95,28 +166,58 @@ 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 or a V6 (see "Writes +wait for the handshake"). + +## Verified writes on the V8 and V6 + +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 + +The V6 behind the 8K dongle was used and tested with the same controls, and +they worked as on the V8. ## 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 or V6. - 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`). +- 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 2a345899..e976013c 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"; @@ -51,6 +51,14 @@ 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; + /** 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(). */ @@ -111,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)); @@ -120,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; @@ -135,6 +144,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, this.handshakeType], 5); } else { reply[1] = 1; } @@ -282,6 +295,160 @@ 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(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.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.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"); + 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 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 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(); + } +}); + +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(); + } +}); + +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(); + 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 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); + 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(); +}); + +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. @@ -299,23 +466,88 @@ 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]); + assert.equal(await client.setTurboMode(true), true); + assert.equal(device.flash[SCYROX_V8S_20K_ADDRESS], 1); + 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(); +}); + +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(device.flash[SCYROX_V8S_20K_ADDRESS], 1); - assert.equal((await client.readStatus(true)).turboMode, 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(); }); 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..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; } @@ -293,7 +311,7 @@ export class LamzuAtlantisHidClient { } getDebounceMaxMs(): number { - return DEBOUNCE_MAX_MS; + return this.debounceMaxMs(); } getSleepOptions(): readonly number[] { @@ -321,6 +339,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; @@ -351,16 +370,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 @@ -428,6 +451,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 } : {}), @@ -484,8 +510,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."); } @@ -560,8 +609,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) { @@ -616,7 +666,21 @@ 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 || !this.linksTurboToPerformanceMode()) { + return await this.setFlag(FLASH.performanceState, enabled, "performanceMode", "competition mode"); + } + // 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 () => { + await this.writeLinkedFlags( + { address: turboAddress, field: "turboMode", label: "turbo mode" }, + { address: FLASH.performanceState, field: "performanceMode", label: "competition mode" }, + false, + ); + return false; + }); } async setHyperMode(enabled: boolean): Promise { @@ -625,16 +689,25 @@ 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 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) { - throw new Error("20,000 FPS mode requires performance mode to be turned on first."); + 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"}.`); @@ -814,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 @@ -891,8 +999,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..df71d82e 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,18 +92,19 @@ 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); }); 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], @@ -105,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( @@ -155,28 +173,34 @@ 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); -}); - -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)!; + // 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 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. Key + // Response Time goes to 30 ms. The client offers these only once the + // 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); + assert.equal(product.supportsFactoryReset, true); + 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); + } }); test("the sensor-mode register is not offered as a performance toggle", async () => { @@ -185,3 +209,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..67a449cc 100644 --- a/src/drivers/scyrox/hid.ts +++ b/src/drivers/scyrox/hid.ts @@ -1,5 +1,22 @@ import { LamzuAtlantisHidClient } from "../lamzu-atlantis/hid.ts"; -import { SCYROX_V8S_20K_ADDRESS, scyroxProduct } from "@openmouse/protocol/scyrox"; +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 @@ -22,10 +39,75 @@ import { SCYROX_V8S_20K_ADDRESS, scyroxProduct } from "@openmouse/protocol/scyro * verified (see docs/scyrox-v8-testing.md). */ export class ScyroxHidClient extends LamzuAtlantisHidClient { + /** 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); } + /** + * The V8 and the V6 share product ids (the vendor tool tells them apart by + * 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.identitySettled || Date.now() < this.nextIdentifyAt) return; + if (this.catalogEntry()?.model !== "V8") { + this.identitySettled = true; + return; + } + try { + 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 { + 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 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(); + 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() !== null) return { ...catalog, ...rates }; + const { liftOffStopCodes: _stops, maxDebounceMs: _debounce, ...shared } = catalog; + return { ...shared, ...rates, supportsAngleTuning: false, supportsFactoryReset: false }; + } + + override displayName(): string { + const model = this.identifiedModel(); + return model ? `Scyrox ${model}` : super.displayName(); + } + static override isSupported(device: HIDDevice): boolean { return scyroxProduct(device.vendorId, device.productId) !== undefined && LamzuAtlantisHidClient.hasConfigCollection(device); @@ -35,4 +117,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/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 20d0acfc..5c3d50d0 100644 --- a/src/scyrox/index.ts +++ b/src/scyrox/index.ts @@ -28,8 +28,61 @@ 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 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]; +} + +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; +} + +/** 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). + */ +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 @@ -57,6 +110,25 @@ 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, 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; + +/** + * 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, @@ -118,6 +190,32 @@ 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_V8_WIRED, + rateFamily: "pulsar", + dpiLayout: "legacy", + verified: true, + minDpi: 50, + maxDpi: 30000, + 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, + }], // 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. @@ -141,9 +239,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.