JS `Web HID API` (浏览器)：与人机接口设备（如游戏手柄）交互

嘿，各位代码界的探险家们，欢迎来到今天的“Web HID API：让浏览器也能玩转硬件”讲座！准备好了吗？我们要开始深入了解如何让你的浏览器成为硬件控制大师了！

开场白：告别键盘侠，拥抱硬件控

一直以来，浏览器都像是躲在屏幕后面的宅男，除了和服务器聊天，几乎不和真实世界互动。但是，时代变了！Web HID API 的出现，就像给浏览器装上了一双灵巧的手，让它能够直接和各种人机接口设备（Human Interface Device，简称 HID）对话，比如游戏手柄、特殊键盘、甚至是定制的工业控制面板。

想象一下，你可以用浏览器控制机械臂，用游戏手柄控制智能家居，或者用定制键盘完成复杂的图像编辑操作。是不是感觉世界都变得有趣起来了？

第一章：HID 是个啥？为什么我们需要它？

首先，我们来聊聊 HID。简单来说，HID 就是一种通用的设备接口标准，它定义了设备如何与主机（比如你的电脑）进行通信。常见的 HID 设备包括：

键盘
鼠标
游戏手柄
触摸屏
条形码扫描器

等等等等，反正只要是用来和人交互的，都可以算作 HID 设备。

为什么我们需要 Web HID API 呢？

传统的 Web 技术，比如 JavaScript，只能通过浏览器提供的有限接口来与硬件交互。这就像隔着一层玻璃和硬件对话，效率低，功能也受限。

Web HID API 的出现，打破了这层玻璃，让 JavaScript 可以直接访问 HID 设备，实现更底层的控制和更丰富的功能。

第二章：Web HID API 的核心概念

Web HID API 涉及几个关键概念，理解了它们，才能更好地驾驭这个强大的工具。

HID 对象：这是 Web HID API 的入口点，通过 navigator.hid 可以访问到它。
HIDDevice 对象：代表一个已连接的 HID 设备。
HIDReportEvent 对象：当 HID 设备发送数据时，会触发一个 HIDReportEvent 事件，包含设备发送的数据。
Report ID： HID 设备发送的数据包，每个数据包可以有一个 Report ID，用于区分不同的数据类型。

第三章：代码实战：连接你的第一个 HID 设备

理论讲多了容易打瞌睡，让我们直接上代码！

第一步：请求设备访问权限

在使用 Web HID API 之前，必须先请求用户授权，才能访问 HID 设备。

async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        { vendorId: 0x1234, productId: 0x5678 }, // 替换成你的设备的 Vendor ID 和 Product ID
      ],
    });

    if (devices.length > 0) {
      console.log("已选择设备:", devices[0]);
      await connectToDevice(devices[0]);
    } else {
      console.log("未选择任何设备。");
    }
  } catch (error) {
    console.error("请求设备失败:", error);
  }
}

代码解释：

navigator.hid.requestDevice()：这个方法会弹出一个设备选择窗口，让用户选择要连接的 HID 设备。
filters：一个可选的参数，用于过滤设备。vendorId 和 productId 是 HID 设备的厂商 ID 和产品 ID，可以在设备管理器中找到。
await：因为 requestDevice() 是一个异步函数，所以需要使用 await 等待它完成。

第二步：连接设备

拿到 HIDDevice 对象后，就可以连接设备了。

async function connectToDevice(device) {
  try {
    await device.open();
    console.log("设备已连接:", device.productName);

    device.addEventListener("inputreport", handleInputReport);

  } catch (error) {
    console.error("连接设备失败:", error);
  }
}

代码解释：

device.open()：打开设备连接。
device.addEventListener("inputreport", handleInputReport)：监听 inputreport 事件，当设备发送数据时，会触发这个事件。

第三步：处理设备数据

当设备发送数据时，handleInputReport 函数会被调用。

function handleInputReport(event) {
  const { data, device, reportId } = event;
  const uint8Array = new Uint8Array(data.buffer);

  console.log("收到数据:", uint8Array, "Report ID:", reportId);

  // 在这里处理设备发送的数据
  // 例如，解析游戏手柄的按钮状态和摇杆位置
}

代码解释：

event.data：一个 DataView 对象，包含设备发送的数据。
new Uint8Array(data.buffer)：将 DataView 对象转换为 Uint8Array 对象，方便处理。
event.reportId：Report ID，用于区分不同的数据类型。

第四步：发送数据到设备

有些 HID 设备支持双向通信，你可以通过 Web HID API 向设备发送数据。

async function sendOutputReport(device, reportId, data) {
  try {
    await device.sendReport(reportId, data);
    console.log("数据已发送到设备:", data, "Report ID:", reportId);
  } catch (error) {
    console.error("发送数据失败:", error);
  }
}

代码解释：

device.sendReport(reportId, data)：向设备发送数据。
reportId：Report ID，用于指定数据类型。
data：一个 Uint8Array 对象，包含要发送的数据。

完整代码示例：

<!DOCTYPE html>
<html>
<head>
  <title>Web HID API 示例</title>
</head>
<body>
  <button id="connectButton">连接 HID 设备</button>

  <script>
    const connectButton = document.getElementById("connectButton");

    connectButton.addEventListener("click", requestHIDDevice);

    async function requestHIDDevice() {
      try {
        const devices = await navigator.hid.requestDevice({
          filters: [
            { vendorId: 0x1234, productId: 0x5678 }, // 替换成你的设备的 Vendor ID 和 Product ID
          ],
        });

        if (devices.length > 0) {
          console.log("已选择设备:", devices[0]);
          await connectToDevice(devices[0]);
        } else {
          console.log("未选择任何设备。");
        }
      } catch (error) {
        console.error("请求设备失败:", error);
      }
    }

    async function connectToDevice(device) {
      try {
        await device.open();
        console.log("设备已连接:", device.productName);

        device.addEventListener("inputreport", handleInputReport);

        // 示例：发送数据到设备
        // const data = new Uint8Array([0x01, 0x02, 0x03]);
        // await sendOutputReport(device, 0x01, data);

      } catch (error) {
        console.error("连接设备失败:", error);
      }
    }

    function handleInputReport(event) {
      const { data, device, reportId } = event;
      const uint8Array = new Uint8Array(data.buffer);

      console.log("收到数据:", uint8Array, "Report ID:", reportId);

      // 在这里处理设备发送的数据
      // 例如，解析游戏手柄的按钮状态和摇杆位置
    }

    async function sendOutputReport(device, reportId, data) {
      try {
        await device.sendReport(reportId, data);
        console.log("数据已发送到设备:", data, "Report ID:", reportId);
      } catch (error) {
        console.error("发送数据失败:", error);
      }
    }
  </script>
</body>
</html>

第四章：进阶技巧：解析 HID Report Descriptor

Web HID API 仅仅提供了数据的原始访问，如何解析这些数据，才是真正的挑战。HID 设备通过 Report Descriptor 来描述数据的结构和含义。

什么是 Report Descriptor？

Report Descriptor 是一个二进制数据结构，它描述了 HID 设备的数据格式，包括：

Report ID
字段类型（输入、输出、Feature）
字段大小
字段含义（例如，按钮、摇杆、传感器数据）

如何解析 Report Descriptor？

解析 Report Descriptor 是一项复杂的任务，通常需要借助专门的库或者工具。以下是一些常用的方法：

使用现成的库： 网上有一些开源的 JavaScript 库可以帮助你解析 Report Descriptor，例如node-hid (虽然名字里有node，但在浏览器里也可以配合browserify 或者 webpack使用)，它提供了一些方便的 API 来获取设备信息和解析数据。
手动解析： 如果你想深入了解 Report Descriptor 的结构，可以尝试手动解析。你需要阅读 HID 规范，了解 Report Descriptor 的语法和语义。

一个简单的 Report Descriptor 示例：

0x05, 0x01,        // Usage Page (Generic Desktop)
0x09, 0x05,        // Usage (Gamepad)
0xA1, 0x01,        // Collection (Application)
0x85, 0x01,        //   Report ID (1)
0x05, 0x09,        //   Usage Page (Button)
0x19, 0x01,        //   Usage Minimum (Button 1)
0x29, 0x08,        //   Usage Maximum (Button 8)
0x15, 0x00,        //   Logical Minimum (0)
0x25, 0x01,        //   Logical Maximum (1)
0x95, 0x08,        //   Report Count (8)
0x75, 0x01,        //   Report Size (1)
0x81, 0x02,        //   Input (Data, Variable, Absolute)
0x05, 0x01,        //   Usage Page (Generic Desktop)
0x09, 0x30,        //   Usage (X)
0x09, 0x31,        //   Usage (Y)
0x15, 0x00,        //   Logical Minimum (0)
0x26, 0xFF, 0x00,  //   Logical Maximum (255)
0x75, 0x08,        //   Report Size (8)
0x95, 0x02,        //   Report Count (2)
0x81, 0x02,        //   Input (Data, Variable, Absolute)
0xC0              // End Collection

这个 Report Descriptor 描述了一个简单的游戏手柄，包含 8 个按钮和 X、Y 轴。

第五章：安全注意事项

使用 Web HID API 需要注意安全问题。

用户授权： 必须先请求用户授权，才能访问 HID 设备。
来源验证： 确保只连接来自可信来源的 HID 设备。
数据验证： 对设备发送的数据进行验证，防止恶意代码注入。

第六章：兼容性

Web HID API 的兼容性取决于浏览器。

浏览器	支持情况
Chrome	完全支持
Edge	完全支持
Firefox	部分支持
Safari	不支持

第七章：实战案例：打造一个自定义游戏手柄控制台

有了 Web HID API，你可以发挥想象力，打造各种有趣的应用程序。

案例描述：

我们要创建一个自定义游戏手柄控制台，允许用户自定义按键映射和摇杆灵敏度，并将配置保存到本地存储。

实现思路：

连接游戏手柄： 使用 Web HID API 连接游戏手柄。
解析 Report Descriptor： 解析游戏手柄的 Report Descriptor，获取按钮和摇杆的信息。
自定义按键映射： 创建一个用户界面，允许用户将游戏手柄的按钮映射到键盘按键。
自定义摇杆灵敏度： 创建一个用户界面，允许用户调整摇杆的灵敏度。
保存配置： 将用户的配置保存到本地存储。
模拟键盘事件： 当用户按下游戏手柄的按钮时，模拟键盘事件。

代码示例（简化版）：

// ... (连接设备的代码)

function handleInputReport(event) {
  const { data, device, reportId } = event;
  const uint8Array = new Uint8Array(data.buffer);

  // 解析游戏手柄数据
  const button1 = uint8Array[0] & 0x01; // 第一个字节的最低位代表按钮 1 的状态
  const button2 = uint8Array[0] & 0x02; // 第一个字节的第二低位代表按钮 2 的状态
  const joystickX = uint8Array[1]; // 第二个字节代表 X 轴的位置
  const joystickY = uint8Array[2]; // 第三个字节代表 Y 轴的位置

  // 根据用户配置模拟键盘事件
  if (button1 && userConfig.button1Mapping === "KeyA") {
    simulateKeyPress("KeyA");
  }

  // ... (其他按钮和摇杆的处理)
}

function simulateKeyPress(key) {
  // 创建键盘事件
  const keyboardEvent = new KeyboardEvent("keydown", { key });

  // 触发键盘事件
  document.dispatchEvent(keyboardEvent);
}

第八章：总结与展望

Web HID API 为 Web 开发者打开了一扇通往硬件世界的大门。我们可以利用它开发各种创新的应用程序，例如：

游戏控制器
工业控制面板
虚拟现实设备
智能家居控制

当然，Web HID API 仍然在发展中，未来还有很大的潜力。随着技术的不断成熟，相信它会成为 Web 开发的重要组成部分。

结束语：

今天的讲座就到这里了。希望你们通过今天的学习，能够掌握 Web HID API 的基本知识，并将其应用到实际项目中。记住，技术是用来改变世界的，让我们一起用 Web HID API 创造更美好的未来！

各位，下次再见！祝大家编程愉快， Bug 永不相见！

发表回复 取消回复

发表回复取消回复