PhotonLink SDK

光子互联 - 基于 WebHID 的 HP 协议游戏外设通信 SDK。

✨ 特性

• 🔌 WebHID 通信 - 原生浏览器 HID 设备通信
• 📦 HP 协议 - 设备识别 → 按设备类型挂载子树（键盘等）
• 🎯 TypeScript - 完整的类型定义
• 🔧 模块化设计 - 按需导入，支持 Tree Shaking

📦 安装

pnpm add @photon-link/sdk

🚀 快速开始

import { PhotonLink, HPKeyboard } from '@photon-link/sdk';

const sdk = new PhotonLink({
  apiKey: 'YOUR_API_KEY',
  filters: [
    { vendorId: 0x3402, productId: 0x0300, usage: 0x01, usagePage: 0xff00 },
  ],
});

const wrapped = await sdk.requestDevice();
if (wrapped) {
  await sdk.connect(wrapped.uuid);

  // 获取设备句柄（首次调用内部发 cmd 0x00 完成识别，按设备类型返回句柄）
  const device = await sdk.getDeviceHandle();

  if (device instanceof HPKeyboard) {
    const info = await device.system.getDeviceInfo();
    console.log(info);
  }

  await sdk.disconnect();
}

📖 API 结构

import { PhotonLink, HPKeyboard, Command, Profile, LightAreaType } from '@photon-link/sdk';

// SDK 主类
const sdk = new PhotonLink({ apiKey, filters: [...] });

// 设备识别（cmd 0x00，所有设备公用）
sdk.identify              // IdentifyModule（getProtocolVersion / getDeviceInfo / getFeatureSpec）
const device = await sdk.getDeviceHandle(); // 首次调用完成识别，返回 HPKeyboard | null

// 键盘模块（device instanceof HPKeyboard 后通过 device.* 访问）
device.system        // 系统
device.light         // 灯光
device.key           // 按键
device.advancedKey   // 高级键
device.performance   // 性能
device.macro         // 宏
device.adjusting     // 校准
device.update        // 固件升级

// 协议枚举（全部平铺）
Command.CMD_SYSTEM
Profile.PROFILE_1
LightAreaType.MAIN

🔧 功能示例

系统

const info = await device.system.getDeviceInfo();
await device.system.restoreFactorySettings([Profile.PROFILE_1]);
await device.system.setLockWin(LockWinSubCommand.LOCK);
await device.system.setReportRate(1000);

灯光

const areas = await device.light.getLightArea();
const base = await device.light.getBaseLayerControl(LightAreaType.MAIN);
await device.light.setAreaColor(LightAreaType.MAIN, colors);

按键

const layout = await device.key.getKeymap(0, 6, 16);
await device.key.setKey(0, 0, 0, 0x04);

固件升级

const list = await device.update.getAvailableFirmwares({ vid, pid, board_id });
const bin = await device.update.downloadFirmware(list[0].uuid);
await device.update.upgrade(bin, (progress, status) => console.log(progress, status));

📦 导出内容

import {
  PhotonLink,   // SDK 主类
  HPKeyboard,   // 键盘设备句柄
  IdentifyModule,
  DeviceType,

  Command,      // 协议枚举
  Profile,
  LightAreaType,
  // ...

  createApi,    // 后端 API 工厂
  TelemetryModule,

  SDKError,     // 错误类
  TimeoutError,

  DeviceStatus, // 设备状态
  DeviceEvent,

  Logger,       // 日志
  LogLevel,

  SDK_VERSION,  // 版本
} from '@photon-link/sdk';

📁 输出格式

dist/
├── esm/    # ES Module
├── cjs/    # CommonJS
└── umd/    # UMD

浏览器使用

<script src="dist/umd/index.min.js"></script>
<script>
  const sdk = new PhotonLink.SDK({ apiKey, filters: [...] });
</script>

📄 License

MIT