# @mxmauro/iot-comm\.js 中文文档

规范地址：https://npmcn.com/package/%40mxmauro/iot-comm.js/

版本：0\.3\.1
npm 元数据更新时间：2026-11-01T22:48:51.832Z
中文译文更新时间：2026-11-01T23:06:46.934Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40mxmauro/iot-comm.js
原文对照：https://npmcn.com/package/%40mxmauro/iot-comm.js/?lang=original
项目主页：https://github.com/mxmauro/iot-comm.js
源码仓库：https://github.com/mxmauro/iot-comm.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，77 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-08-17T01:41:13.279Z
- 最新版本发布：2026-11-01T22:48:51.530Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

Javascript库，使用IoT- comm库与ESP IoT设备通信

## 安装

```sh
npm install @mxmauro/iot-comm.js
```

也可以使用：`pnpm add @mxmauro/iot-comm.js`、`yarn add @mxmauro/iot-comm.js`、`bun add @mxmauro/iot-comm.js`

## README

# iot-comm.js

JavaScript客户端库，用于与运行的ESP IoT设备进行安全通信 [esp-iot-comm](https://github.com/mxmauro/esp-components/tree/master/esp_iot_comm) 服务器组件。

## 概述

`iot-comm.js` 提供安全的基于websocket的客户端，用于连接使用esp-iot-comm组件的ESP32物联网设备。它 实现与服务器相同的加密协议和通信模式，确保端到端安全性和设备可靠性 控制。

## 关键特性

-   **安全通信**： AES-256加密，支持ECDH密钥交换、ECDSA认证、挑战响应保护 重播攻击。
-   **WebSocket传输**：实时双向通信。
-   **用户管理**：对设备上的用户进行创建、删除和管理。
-   **凭证管理**：安全地更改和重置用户凭据。
-   **设备配置**：设置发现设备的mDNS主机名。
-   **跨平台的**：可在Node.js和浏览器环境中工作。
-   **事件驱动的**：监听消息和连接事件。
-   **打印稿的支持**包含完整的TypeScript定义。
-   **服务器身份挂钩**：可选继续认证前SHA-256指纹审批回调。

## 安装

### NodeJS

从npm安装：

```bash
npm install @mxmauro/iot-comm.js
```

### CDN

你可以通过jsDelivr CDN直接在浏览器中使用这个库，而不需要安装它：

```html
<script src="https://cdn.jsdelivr.net/gh/mxmauro/iot-comm.js@v0.1.0/dist/umd/index.js"></script>
```

取代 `v0.1.0` 使用所需的版本标记。

## 示例

看到 `examples/` 完整实现目录：

-   `examples/browser/` Web浏览器演示与用户界面
-   `examples/nodejs/` - Node.js控制台和密钥生成示例

## 快速入门

### 生成ECDSA密钥对

```ts
import { Client, toB64 } from '@mxmauro/iot-comm.js';

const { privateKey, publicKey } = await Client.generateECDSAKeyPair();

console.log('Private key:', toB64(privateKey));
console.log('Public key:', toB64(publicKey));
```

### 连接设备

```ts
import { Client } from '@mxmauro/iot-comm.js';

const client = new Client();

await client.connect({
    hostname: '192.168.1.25:80',
    username: 'admin',
    privateKey: '<base64-private-key>',
    verifyServerFingerprint: async (fingerprint) => {
        return fingerprint === '<sha256-device-public-key-hex>';
    }
});
```

这个 `verifyServerFingerprint` Callback接收大写十六进制 `SHA-256(devicePublicKey)` 指纹派生 从 `/ws/init` 库验证服务器提供的设备签名后的响应。返回 `true` 继续 连接，返回 `false` 用 `ConnectionAbortedError`，以及抛出的错误从 `connect()`.

连接成功后， `client.maxPacketSize` 报告设备和发布的最大报文大小 `client.isAdmin` 通过认证的用户是否具有管理员权限。

### 取消连接设置

通过一项 `AbortSignal` 取消正在进行的操作 `connect()` 呼叫。信号只影响设置；在a之后终止它 连接成功不会关闭会话。

```ts
const abortController = new AbortController();
const connecting = client.connect({
    hostname: '192.168.1.25:80',
    username: 'admin',
    privateKey: '<base64-private-key>',
    signal: abortController.signal
});

abortController.abort(new Error('Connection cancelled'));
await connecting;
```

### 使用OTA上传固件

```ts
await client.uploadFirmware({
    image: firmwareBlob,
    onProgress: ({ sentBytes, totalBytes }) => {
        console.log(`Uploaded ${sentBytes}/${totalBytes}`);
    }
});
```

供浏览器使用， `Blob` 是最简单的输入类型。对于Node.js或更高级的情况，您还可以传递一个 `ArrayBuffer`， `Uint8Array`， `Buffer`，或块的同步/异步可迭代对象。当图像源是可迭代的，您还必须提供 `imageSize`.

```ts
await client.uploadFirmware({
    image: async function* () {
        yield chunk1;
        yield chunk2;
        yield chunk3;
    }(),
    imageSize: totalFirmwareSize,
    chunkSize: 1024,
    signal: abortController.signal
});
```

当您需要手动控制OTA会话时，也可以使用较低级别的命令方法：

```ts
await client.otaBeginCommand(firmwareSize);
await client.otaWriteCommand(chunk);
await client.otaCancelCommand();
```

### 配置AudioLight多输出设备

AudioLightNode V2分别存储输入和照明。读取或更新同一身份验证会话中的每个完整部分； 然后只有在所有请求的更新成功后才重新启动：

```ts
const input = await client.getInputConfigCommand();
const lighting = await client.getLightingConfigCommand();

await client.setInputConfigCommand({ ...input, resetGpio: undefined });
await client.setLightingConfigCommand([
    { type: 'rgb5050', redGpio: 4, greenGpio: 5, blueGpio: 6, activeLow: false },
    { type: 'ws281x', dataGpio: 7, ledCount: 60 }
]);
await client.rebootCommand();
```

忽略可选输入或WS281x镜像gpio以使它们断开连接。协议的 `0xff` 表示被翻译为和从 `undefined` 在内部。照明输出为有序槽；第一个输出是slot `0`． 客户端拒绝截断的回复和无效 在发送前配置部分。配置更改将被保存，但要到以下时间才会生效 `rebootCommand()` 成功。

Color、fade、set-and-fade、raw-DMX和raw-WS281x方法接受插槽目标(`0` 或者 `1`)， `LIGHTING_TARGET_ALL`，或者 `undefined`. 后两个目标是每个活动槽。插槽目标必须指向一个活动的插槽；不兼容的照明类型上的原始命令是A 设备上有效的no-op。WS281x原始数据以连续的红、绿、蓝字节形式提供； `setRawWs281xRgbDataCommand(target, firstLed, data)` 地址从一个led。

## 许可证

MIT许可证-参见 [许可证](https://npmcn.com/package/%40mxmauro/iot-comm.js/LICENSE) 文件查看详细信息。

## 贡献

欢迎投稿！请确保所有更改保持与esp-iot-comm服务器协议的兼容性。

## 常见问题

### @mxmauro/iot-comm\.js 是什么？

Javascript库，使用IoT- comm库与ESP IoT设备通信

### 如何安装 @mxmauro/iot-comm\.js？

在项目目录运行 npm install @mxmauro/iot-comm\.js，或使用 pnpm add / yarn add / bun add。

### @mxmauro/iot-comm\.js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @mxmauro/iot-comm\.js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @mxmauro/iot-comm\.js 可以商用吗？

@mxmauro/iot-comm\.js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @mxmauro/iot-comm\.js 还在维护吗？

最新版本 0\.3\.1 发布于 2026/11/02（1 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/08/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。