yjx-sdk-mouse 0.1.0

package/README.md

@@ -0,0 +1,287 @@
+# yjx-sdk-mouse
+
+永佳新鼠标 WebHID SDK，用于在浏览器中连接兼容设备，并读取或写入 DPI、回报率、休眠策略、按键映射和宏配置。
+
+## 安装
+
+```bash
+npm install yjx-sdk-mouse
+```
+
+也可以使用 pnpm：
+
+```bash
+pnpm add yjx-sdk-mouse
+```
+
+## 使用条件
+
+- 运行环境需要提供 WebHID，即存在 `navigator.hid`。
+- 页面需要运行在安全上下文中，例如 HTTPS 或本地开发环境。
+- 首次选择设备必须由用户操作触发，因此请在按钮点击等事件中调用 `requestDevices()`。
+- SDK 是 ESM 包，请使用 `import` 引入。
+
+```ts
+if (!('hid' in navigator)) {
+  throw new Error('当前浏览器不支持 WebHID');
+}
+```
+
+## 快速开始
+
+```ts
+import { createMouse } from 'yjx-sdk-mouse';
+
+const mouse = createMouse();
+
+document.querySelector('#connect')?.addEventListener('click', async () => {
+  // 首次连接时弹出浏览器设备选择框。
+  const selected = await mouse.requestDevices();
+  const device = selected[0];
+
+  if (!device) {
+    console.log('未选择设备');
+    return;
+  }
+
+  await mouse.init(device.id);
+  console.log('已连接：', mouse.currentDevice);
+
+  const dpi = await mouse.dpi.get();
+  console.log('DPI 配置：', dpi);
+});
+```
+
+浏览器已经授权过设备时，可以先用 `getDevices()` 静默读取：
+
+```ts
+const devices = await mouse.getDevices();
+if (devices[0]) {
+  await mouse.init(devices[0].id);
+}
+```
+
+使用完毕后关闭设备：
+
+```ts
+await mouse.closeDevice();
+```
+
+## 创建设备实例
+
+### 使用默认设备参数
+
+`createMouse()` 和 `Mouse.createDefault()` 都会使用 SDK 内置的有线、2.4G 接收器设备过滤参数。
+
+```ts
+import Mouse, { createMouse } from 'yjx-sdk-mouse';
+
+const mouse1 = createMouse();
+const mouse2 = Mouse.createDefault();
+```
+
+### 自定义 VID、PID 和 HID Collection
+
+```ts
+import { createMouse } from 'yjx-sdk-mouse';
+
+const mouse = createMouse({
+  configs: [
+    {
+      vendorId: 0xa8a5,
+      productId: 0x2255,
+      usagePage: 0xff01,
+      usage: 0x10,
+    },
+  ],
+  timeout: 3000,
+});
+```
+
+## DPI
+
+```ts
+const profile = await mouse.dpi.get();
+// { currentIndex, pollRate, levels }
+
+// 切换到第 2 档，索引从 0 开始。
+await mouse.dpi.setCurrentIndex(1);
+
+// 修改第 1 档 DPI。
+await mouse.dpi.setLevel(0, 1600);
+
+// 一次写入完整配置。
+await mouse.dpi.set({
+  currentIndex: 0,
+  pollRate: 1000,
+  levels: [800, 1200, 1600, 2400, 3200, 5000],
+});
+```
+
+如果界面中维护了尚未写入的本地配置，请使用 `setCurrentIndexFrom()` 或 `setLevelFrom()`，避免先执行 `get()` 而覆盖本地修改：
+
+```ts
+const draft = await mouse.dpi.get();
+draft.levels[0] = 1200;
+
+await mouse.dpi.setLevelFrom(draft, 1, 1600);
+```
+
+## 性能设置
+
+```ts
+const settings = await mouse.performance.get();
+console.log(settings);
+
+await mouse.performance.set({
+  pollRate: 1000,
+  sleepMinutes: 10,
+  neverSleep: false,
+  scrollReverse: false,
+  wakeOnMove: true,
+});
+
+await mouse.performance.setPollRate(500);
+```
+
+支持的回报率为 `125 | 250 | 500 | 1000` Hz。
+
+## 按键映射
+
+```ts
+import { KEY_PRESETS } from 'yjx-sdk-mouse';
+
+const mapping = await mouse.button.get();
+console.log(mapping);
+
+const mutePreset = KEY_PRESETS.find((item) => item.id === 'mute');
+if (mutePreset) {
+  await mouse.button.setSlot('back', mutePreset);
+}
+
+await mouse.button.resetSlot('back');
+await mouse.button.resetAll();
+```
+
+可通过以下导出项构建按键配置界面：
+
+- `KEY_PRESETS`：全部预设。
+- `KEYBOARD_PRESETS`：键盘按键预设。
+- `COMMAND_PRESETS`：系统和组合命令预设。
+- `COMMAND_PRESET_GROUPS`：已分组的命令预设。
+- `BUTTON_SLOTS`、`BUTTON_SLOT_LABEL`：鼠标按键槽位和显示名称。
+
+## 宏
+
+`macroIndex` 范围是 `0..31`。键盘的 `keyCode` 使用 USB HID Keyboard Usage，例如字母 A 为 `0x04`。
+
+```ts
+import type { MouseMacro } from 'yjx-sdk-mouse';
+
+const macros: MouseMacro[] = [
+  {
+    actions: [
+      { type: 'keyboard', keyCode: 0x04, action: 'keydown', delay: 20 },
+      { type: 'keyboard', keyCode: 0x04, action: 'keyup', delay: 20 },
+      { type: 'mouse', button: 'left', action: 'mousedown', delay: 20 },
+      { type: 'mouse', button: 'left', action: 'mouseup', delay: 20 },
+    ],
+  },
+];
+
+// 写入 profile 0，并把第 0 个宏分配给后退键。
+await mouse.macro.setAndAssign(
+  'back',
+  macros,
+  {
+    macroIndex: 0,
+    repeat: 1,
+    triggerMode: 0,
+  },
+  0,
+);
+```
+
+也可以分开写入和分配：
+
+```ts
+await mouse.macro.set(macros, 0);
+await mouse.macro.assignButton('back', { macroIndex: 0 });
+```
+
+## 设备信息和事件
+
+```ts
+const info = await mouse.getDeviceInfo();
+console.log(info.boardId, info.firmwareVersion);
+
+mouse.on('statusChange', (event) => {
+  console.log('DPI 档位：', event.dpiIndex);
+  console.log('回报率：', event.pollRate);
+});
+
+mouse.on('usbChange', (event) => {
+  console.log('USB 状态：', event.type);
+});
+```
+
+取消监听：
+
+```ts
+const handleStatus = (event: { dpiIndex: number }) => {
+  console.log(event.dpiIndex);
+};
+
+mouse.on('statusChange', handleStatus);
+mouse.off('statusChange', handleStatus);
+```
+
+## 恢复出厂设置
+
+此操作会重置性能、DPI、按键和宏配置：
+
+```ts
+const result = await mouse.other.factoryReset();
+console.log(result);
+```
+
+## 原始协议调用
+
+只有在需要扩展设备协议时才建议使用：
+
+```ts
+const response = await mouse.sendRaw(new Uint8Array(64));
+await mouse.sendRawNoResponse(new Uint8Array(64));
+```
+
+## 主要 API
+
+| API | 说明 |
+| --- | --- |
+| `getDevices()` | 获取浏览器已经授权的兼容设备 |
+| `requestDevices()` | 打开浏览器设备选择器 |
+| `init(id)` | 打开设备并执行连接握手 |
+| `closeDevice()` | 关闭当前设备 |
+| `getDeviceInfo()` | 获取板卡和固件信息 |
+| `getFirmwareVersion(refresh?)` | 获取固件版本，可选择强制刷新 |
+| `dpi` | DPI 档位读取和写入 |
+| `performance` | 回报率、休眠、滚轮和唤醒设置 |
+| `button` | 按键映射读取和写入 |
+| `macro` | 宏数据写入和按键分配 |
+| `other.factoryReset()` | 恢复出厂设置 |
+
+## 错误处理
+
+所有设备操作都返回 Promise，建议统一使用 `try/catch`：
+
+```ts
+try {
+  const devices = await mouse.requestDevices();
+  if (devices[0]) {
+    await mouse.init(devices[0].id);
+  }
+} catch (error) {
+  console.error('鼠标连接失败：', error);
+}
+```
+

package/dist/constants.d.ts

@@ -0,0 +1,79 @@
+/** Web HID Report ID（原厂驱动 sendReport 第一个参数） */
+export declare const REPORT_ID = 240;
+/** @deprecated 使用 REPORT_ID */
+export declare const PACKET_HEADER = 240;
+/** 逻辑包长度：byte0=ReportID + 63 字节 payload */
+export declare const PACKET_SIZE = 64;
+/** sendReport 实际发送的 payload 长度 */
+export declare const PAYLOAD_SIZE = 63;
+/** 2.4G 接收器 VID（AJ159 V2 SE） */
+export declare const RECEIVER_VENDOR_ID = 43173;
+/** 有线连接 VID（AJ159 V2 SE） */
+export declare const WIRED_VENDOR_ID = 43172;
+/** 默认 2.4G 接收器 VID */
+export declare const DEFAULT_VENDOR_ID = 43173;
+export declare const DEFAULT_PRODUCT_ID = 8789;
+export declare const DEFAULT_USAGE_PAGE = 65281;
+export declare const DEFAULT_USAGE = 16;
+/** 协议命令字（抓包 + 文档推断） */
+export declare const Command: {
+    /** 协议握手 */
+    readonly Handshake: 82;
+    /** 保活 / 确认 */
+    readonly Ping: 4;
+    /** 读内存块 */
+    readonly ReadBlock: 48;
+    /** 读内存（短） */
+    readonly ReadShort: 8;
+    /** 读内存（重试 / 等待响应） */
+    readonly ReadRetry: 14;
+    /** 写内存块 */
+    readonly WriteBlock: 15;
+    /** 写按键映射 */
+    readonly WriteKeys: 9;
+    /** 写宏数据块 */
+    readonly WriteMacro: 13;
+    /** 提交 / 保存宏数据 */
+    readonly CommitMacro: 16;
+    /** 设备主动上报：DPI / 回报率切换（原厂 onListeners statu） */
+    readonly StatusReport: 250;
+};
+export type CommandCode = (typeof Command)[keyof typeof Command];
+/** 读区域基址 */
+export declare const READ_ADDRESS = 2981;
+/** 写区域基址 */
+export declare const WRITE_ADDRESS = 2734;
+/** 按键映射写地址 */
+export declare const KEY_WRITE_ADDRESS = 8869;
+/** 按键映射写偏移 */
+export declare const KEY_WRITE_OFFSET = 48;
+/** 内存偏移（原厂驱动抓包） */
+export declare const MemoryOffset: {
+    readonly Config: 44;
+    readonly DeviceInfo: 46;
+    readonly Profile: 47;
+};
+/** 握手默认载荷 */
+export declare const HANDSHAKE_PAYLOAD: readonly [1, 0, 26, 0];
+/** 内存访问默认标志 */
+export declare const MEMORY_FLAGS: readonly [1, 1, 1];
+/** 回报率档位（设备存储值为 index + 1，见原厂 getMouseConfigInfo） */
+export declare const PollRateIndex: {
+    readonly Hz125: 0;
+    readonly Hz250: 1;
+    readonly Hz500: 2;
+    readonly Hz1000: 3;
+};
+export declare const PollRateFromIndex: Record<number, 125 | 250 | 500 | 1000>;
+export declare const PollRateToIndex: Record<125 | 250 | 500 | 1000, number>;
+/** @deprecated 使用 PollRateToIndex + 1 写入设备 */
+export declare const PollRateCode: {
+    readonly Hz125: 1;
+    readonly Hz250: 2;
+    readonly Hz500: 3;
+    readonly Hz1000: 4;
+};
+export declare const PollRateFromCode: Record<number, 125 | 250 | 500 | 1000>;
+export declare const PollRateToCode: Record<125 | 250 | 500 | 1000, number>;
+export declare function isWiredVendorId(vendorId: number): boolean;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,eAAO,MAAM,SAAS,MAAO,CAAC;AAE9B,+BAA+B;AAC/B,eAAO,MAAM,aAAa,MAAY,CAAC;AAEvC,2CAA2C;AAC3C,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,kCAAkC;AAClC,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,gCAAgC;AAChC,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,4BAA4B;AAC5B,eAAO,MAAM,eAAe,QAAS,CAAC;AACtC,sBAAsB;AACtB,eAAO,MAAM,iBAAiB,QAAqB,CAAC;AACpD,eAAO,MAAM,kBAAkB,OAAS,CAAC;AACzC,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,aAAa,KAAO,CAAC;AAElC,uBAAuB;AACvB,eAAO,MAAM,OAAO;IAClB,WAAW;;IAEX,cAAc;;IAEd,WAAW;;IAEX,aAAa;;IAEb,qBAAqB;;IAErB,WAAW;;IAEX,YAAY;;IAEZ,YAAY;;IAEZ,iBAAiB;;IAEjB,+CAA+C;;CAEvC,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAEjE,YAAY;AACZ,eAAO,MAAM,YAAY,OAAS,CAAC;AACnC,YAAY;AACZ,eAAO,MAAM,aAAa,OAAS,CAAC;AACpC,cAAc;AACd,eAAO,MAAM,iBAAiB,OAAS,CAAC;AACxC,cAAc;AACd,eAAO,MAAM,gBAAgB,KAAO,CAAC;AAErC,mBAAmB;AACnB,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,aAAa;AACb,eAAO,MAAM,iBAAiB,wBAAoC,CAAC;AAEnE,eAAe;AACf,eAAO,MAAM,YAAY,oBAA8B,CAAC;AAExD,qDAAqD;AACrD,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAKpE,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,EAAE,MAAM,CAKlE,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAKnE,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,EAAE,MAAM,CAKjE,CAAC;AAEF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/constants.js

@@ -0,0 +1,100 @@
+/** Web HID Report ID（原厂驱动 sendReport 第一个参数） */
+export const REPORT_ID = 0xf0;
+/** @deprecated 使用 REPORT_ID */
+export const PACKET_HEADER = REPORT_ID;
+/** 逻辑包长度：byte0=ReportID + 63 字节 payload */
+export const PACKET_SIZE = 64;
+/** sendReport 实际发送的 payload 长度 */
+export const PAYLOAD_SIZE = 63;
+/** 2.4G 接收器 VID（AJ159 V2 SE） */
+export const RECEIVER_VENDOR_ID = 0xa8a5;
+/** 有线连接 VID（AJ159 V2 SE） */
+export const WIRED_VENDOR_ID = 0xa8a4;
+/** 默认 2.4G 接收器 VID */
+export const DEFAULT_VENDOR_ID = RECEIVER_VENDOR_ID;
+export const DEFAULT_PRODUCT_ID = 0x2255;
+export const DEFAULT_USAGE_PAGE = 0xff01;
+export const DEFAULT_USAGE = 0x10;
+/** 协议命令字（抓包 + 文档推断） */
+export const Command = {
+    /** 协议握手 */
+    Handshake: 0x52,
+    /** 保活 / 确认 */
+    Ping: 0x04,
+    /** 读内存块 */
+    ReadBlock: 0x30,
+    /** 读内存（短） */
+    ReadShort: 0x08,
+    /** 读内存（重试 / 等待响应） */
+    ReadRetry: 0x0e,
+    /** 写内存块 */
+    WriteBlock: 0x0f,
+    /** 写按键映射 */
+    WriteKeys: 0x09,
+    /** 写宏数据块 */
+    WriteMacro: 0x0d,
+    /** 提交 / 保存宏数据 */
+    CommitMacro: 0x10,
+    /** 设备主动上报：DPI / 回报率切换（原厂 onListeners statu） */
+    StatusReport: 0xfa,
+};
+/** 读区域基址 */
+export const READ_ADDRESS = 0x0ba5;
+/** 写区域基址 */
+export const WRITE_ADDRESS = 0x0aae;
+/** 按键映射写地址 */
+export const KEY_WRITE_ADDRESS = 0x22a5;
+/** 按键映射写偏移 */
+export const KEY_WRITE_OFFSET = 0x30;
+/** 内存偏移（原厂驱动抓包） */
+export const MemoryOffset = {
+    Config: 0x2c,
+    DeviceInfo: 0x2e,
+    Profile: 0x2f,
+};
+/** 握手默认载荷 */
+export const HANDSHAKE_PAYLOAD = [0x01, 0x00, 0x1a, 0x00];
+/** 内存访问默认标志 */
+export const MEMORY_FLAGS = [0x01, 0x01, 0x01];
+/** 回报率档位（设备存储值为 index + 1，见原厂 getMouseConfigInfo） */
+export const PollRateIndex = {
+    Hz125: 0,
+    Hz250: 1,
+    Hz500: 2,
+    Hz1000: 3,
+};
+export const PollRateFromIndex = {
+    0: 125,
+    1: 250,
+    2: 500,
+    3: 1000,
+};
+export const PollRateToIndex = {
+    125: PollRateIndex.Hz125,
+    250: PollRateIndex.Hz250,
+    500: PollRateIndex.Hz500,
+    1000: PollRateIndex.Hz1000,
+};
+/** @deprecated 使用 PollRateToIndex + 1 写入设备 */
+export const PollRateCode = {
+    Hz125: 0x01,
+    Hz250: 0x02,
+    Hz500: 0x03,
+    Hz1000: 0x04,
+};
+export const PollRateFromCode = {
+    1: 125,
+    2: 250,
+    3: 500,
+    4: 1000,
+};
+export const PollRateToCode = {
+    125: PollRateCode.Hz125,
+    250: PollRateCode.Hz250,
+    500: PollRateCode.Hz500,
+    1000: PollRateCode.Hz1000,
+};
+export function isWiredVendorId(vendorId) {
+    return vendorId === WIRED_VENDOR_ID;
+}
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/controllers/button.d.ts

@@ -0,0 +1,15 @@
+import type { DeviceLayer } from '../device/index.js';
+import type { ButtonMapping, KeyPreset, MouseButtonSlot, MouseKeyMapping } from '../types.js';
+export declare class ButtonController {
+    private readonly device;
+    constructor(device: DeviceLayer);
+    get(): Promise<ButtonMapping>;
+    set(mapping: ButtonMapping): Promise<ButtonMapping>;
+    setSlot(slot: MouseButtonSlot, preset: KeyPreset): Promise<ButtonMapping>;
+    resetAll(): Promise<ButtonMapping>;
+    resetSlot(slot: MouseButtonSlot): Promise<ButtonMapping>;
+    formatLabel(key: MouseKeyMapping, getMacroName?: (macroIndex: number) => string | undefined): string;
+    getPresets(): KeyPreset[];
+    getPresetId(key: MouseKeyMapping): string;
+}
+//# sourceMappingURL=button.d.ts.map

package/dist/controllers/button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.d.ts","sourceRoot":"","sources":["../../src/controllers/button.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9F,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,WAAW;IAE1C,GAAG,IAAI,OAAO,CAAC,aAAa,CAAC;IAM7B,GAAG,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAKnD,OAAO,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC;IAMzE,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;IAKlC,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAM9D,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,MAAM;IAIpG,UAAU,IAAI,SAAS,EAAE;IAIzB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM;CAG1C"}

package/dist/controllers/button.js

@@ -0,0 +1,40 @@
+import { createDefaultButtonMapping, findPresetId, formatKeyLabel, keysToMapping, mappingToKeys, parseKeysResponse, presetToKey, readKeysPacket, writeKeysPacket, KEY_PRESETS, } from '../protocol/key.js';
+export class ButtonController {
+    device;
+    constructor(device) {
+        this.device = device;
+    }
+    async get() {
+        const response = await this.device.sendAndWait(readKeysPacket());
+        const keys = parseKeysResponse(response);
+        return keysToMapping(keys);
+    }
+    async set(mapping) {
+        await this.device.sendWriteAndWait(writeKeysPacket(mappingToKeys(mapping)));
+        return this.get();
+    }
+    async setSlot(slot, preset) {
+        const current = await this.get();
+        const key = presetToKey(preset, current[slot].index);
+        return this.set({ ...current, [slot]: key });
+    }
+    async resetAll() {
+        const defaults = createDefaultButtonMapping();
+        return this.set(defaults);
+    }
+    async resetSlot(slot) {
+        const defaults = createDefaultButtonMapping();
+        const current = await this.get();
+        return this.set({ ...current, [slot]: defaults[slot] });
+    }
+    formatLabel(key, getMacroName) {
+        return formatKeyLabel(key, getMacroName);
+    }
+    getPresets() {
+        return KEY_PRESETS;
+    }
+    getPresetId(key) {
+        return findPresetId(key);
+    }
+}
+//# sourceMappingURL=button.js.map

package/dist/controllers/button.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"button.js","sourceRoot":"","sources":["../../src/controllers/button.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,YAAY,EACZ,cAAc,EACd,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,eAAe,EACf,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAI5B,MAAM,OAAO,gBAAgB;IACE;IAA7B,YAA6B,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAEpD,KAAK,CAAC,GAAG;QACP,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,EAAE,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,OAAsB;QAC9B,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAqB,EAAE,MAAiB;QACpD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,QAAQ,GAAG,0BAA0B,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAqB;QACnC,MAAM,QAAQ,GAAG,0BAA0B,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,WAAW,CAAC,GAAoB,EAAE,YAAyD;QACzF,OAAO,cAAc,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC;IAED,UAAU;QACR,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,WAAW,CAAC,GAAoB;QAC9B,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF"}

package/dist/controllers/device.d.ts

@@ -0,0 +1,19 @@
+import { type MouseConfigData } from '../protocol/packet.js';
+import type { DeviceLayer } from '../device/index.js';
+import type { DeviceInfoPayload, DpiProfile } from '../types.js';
+export declare class DeviceController {
+    private readonly device;
+    private cachedFirmwareVersion;
+    constructor(device: DeviceLayer);
+    handshake(): Promise<Uint8Array>;
+    ping(): Promise<Uint8Array>;
+    /** 读取固件版本（2.4G 下为接收器固件版本，对齐原厂 getVersionInfo） */
+    getFirmwareVersion(refresh?: boolean): Promise<string>;
+    getDeviceInfo(): Promise<DeviceInfoPayload>;
+    getMouseConfig(): Promise<MouseConfigData>;
+    setMouseConfig(config: MouseConfigData): Promise<MouseConfigData>;
+    getDpiProfile(): Promise<DpiProfile>;
+    setDpiProfile(profile: DpiProfile): Promise<DpiProfile>;
+    connectSequence(): Promise<void>;
+}
+//# sourceMappingURL=device.d.ts.map

package/dist/controllers/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/controllers/device.ts"],"names":[],"mappings":"AACA,OAAO,EAWL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAYjE,qBAAa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,qBAAqB,CAAuB;gBAEvB,MAAM,EAAE,WAAW;IAE1C,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAIhC,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAIjC,iDAAiD;IAC3C,kBAAkB,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBpD,aAAa,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAqB3C,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC;IAK1C,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAajE,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAUpC,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAkCvD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAQvC"}

package/dist/controllers/device.js

@@ -0,0 +1,111 @@
+import { PollRateFromIndex } from '../constants.js';
+import { createHandshakePacket, createPingPacket, dpiProfileToMouseConfig, parseMouseConfig, buildMouseConfigWritePayload, readDeviceInfoPacket, readProfilePacket, writeProfilePacket, parsePingVersionReport, toHex, } from '../protocol/packet.js';
+const DPI_SLOT_COUNT = 6;
+function normalizeLevels(levels, base) {
+    const normalized = [...levels];
+    while (normalized.length < DPI_SLOT_COUNT) {
+        normalized.push(base?.[normalized.length] ?? 800);
+    }
+    return normalized.slice(0, DPI_SLOT_COUNT).map((value) => Math.round(value));
+}
+export class DeviceController {
+    device;
+    cachedFirmwareVersion = null;
+    constructor(device) {
+        this.device = device;
+    }
+    async handshake() {
+        return this.device.sendAndWait(createHandshakePacket());
+    }
+    async ping() {
+        return this.device.sendAndWait(createPingPacket());
+    }
+    /** 读取固件版本（2.4G 下为接收器固件版本，对齐原厂 getVersionInfo） */
+    async getFirmwareVersion(refresh = false) {
+        if (!refresh && this.cachedFirmwareVersion) {
+            return this.cachedFirmwareVersion;
+        }
+        const versionPromise = this.device.waitForMatchingReport((data) => parsePingVersionReport(data));
+        await this.device.sendNoResponse(createPingPacket());
+        const version = await versionPromise;
+        if (!version) {
+            throw new Error('无法读取固件版本');
+        }
+        this.cachedFirmwareVersion = version;
+        return version;
+    }
+    async getDeviceInfo() {
+        const firmwareVersion = await this.getFirmwareVersion();
+        let boardId;
+        let raw = new Uint8Array(0);
+        try {
+            const response = await this.device.sendAndWait(readDeviceInfoPacket());
+            raw = new Uint8Array(response);
+            boardId = response[7] | (response[8] << 8);
+        }
+        catch {
+            // 板卡 ID 为可选信息，版本读取失败不应影响主流程
+        }
+        return {
+            raw,
+            boardId,
+            firmwareVersion,
+            receiverFirmwareVersion: firmwareVersion,
+        };
+    }
+    async getMouseConfig() {
+        const response = await this.device.sendAndWait(readProfilePacket());
+        return parseMouseConfig(response);
+    }
+    async setMouseConfig(config) {
+        const writePacket = writeProfilePacket(buildMouseConfigWritePayload(config));
+        const writeResponse = await this.device.sendWriteAndWait(writePacket);
+        if (writeResponse[0] !== 0x0f) {
+            throw new Error(`配置写入回包异常: 期望 cmd=0x0f, 收到 0x${(writeResponse[0] ?? 0).toString(16)} data=${toHex(writeResponse, 32)}`);
+        }
+        return parseMouseConfig(writeResponse);
+    }
+    async getDpiProfile() {
+        const config = await this.getMouseConfig();
+        return {
+            currentIndex: config.currentIndex,
+            pollRate: PollRateFromIndex[config.pollRateIndex] ?? 1000,
+            levels: normalizeLevels(config.dpiLevels.slice(0, config.dpiCount)),
+        };
+    }
+    async setDpiProfile(profile) {
+        const base = await this.getMouseConfig();
+        const levels = normalizeLevels(profile.levels, base.dpiLevels);
+        const config = dpiProfileToMouseConfig({
+            currentIndex: profile.currentIndex,
+            pollRate: profile.pollRate,
+            levels,
+        }, base);
+        const echoed = await this.setMouseConfig(config);
+        const echoedLevels = normalizeLevels(echoed.dpiLevels.slice(0, echoed.dpiCount));
+        const mismatches = levels
+            .map((value, index) => ({ index, expected: value, actual: echoedLevels[index] ?? -1 }))
+            .filter((item) => item.expected !== item.actual);
+        if (mismatches.length > 0) {
+            const detail = mismatches
+                .map((item) => `档位${item.index + 1}: 期望 ${item.expected}, 回显 ${item.actual}`)
+                .join('; ');
+            throw new Error(`DPI 写入回显校验失败: ${detail}`);
+        }
+        return {
+            currentIndex: echoed.currentIndex,
+            pollRate: PollRateFromIndex[echoed.pollRateIndex] ?? profile.pollRate,
+            levels: echoedLevels,
+        };
+    }
+    async connectSequence() {
+        await this.handshake();
+        try {
+            await this.getFirmwareVersion(true);
+        }
+        catch {
+            // 连接阶段版本读取失败不阻断后续配置读取
+        }
+    }
+}
+//# sourceMappingURL=device.js.map