nearlink-web-flasher

English · 简体中文

基于 Web Serial API 的星闪（NearLink）WS63 / BS2x（BS21 / BS21E） 芯片网页烧录库。

无需安装任何本地软件，在 Chrome / Edge / Opera 中即可完成 .fwpkg 固件包的在线烧录：解析固件包 → LoaderBoot 握手 → YMODEM 传输 → 复位运行。

⚠️ 版权说明：.fwpkg 固件格式与 LoaderBoot 烧录协议归**海思（HiSilicon）**所有，本库为兼容实现。海星社区（StarFish）是本工具的维护方，并非格式/协议的权利人。

特性

• ✅ 纯前端，零依赖，基于浏览器原生 Web Serial API
• ✅ .fwpkg 固件包解析（含魔数 / CRC 校验 / 分区表）
• ✅ 星闪 LoaderBoot 烧录协议（握手 / 切换波特率 / 发送分区 / 复位），WS63 与 BS2x 通用
• ✅ 标准 YMODEM 文件传输（CRC 模式，1024 字节数据块）
• ✅ 串口管理（读写缓冲、RTS 控制、波特率切换、帧同步）
• ✅ 完整的进度回调，便于接入任意 UI

兼容性

| 能力 | 要求 | |------|------| | 浏览器 | Chrome / Edge / Opera 89+（需支持 Web Serial API） | | 环境 | https 或 localhost（安全上下文） | | 硬件 | 星闪 WS63 / BS2x 开发板 + 对应串口驱动（CH340 / CP2102 等） |

⚠️ Web Serial API 在 file:// 协议下不可用，请通过本地服务器访问演示页。

🔌 驱动说明：多数开发板使用 CH340 USB 转串口芯片，Windows 用户需先安装 CH340 驱动（macOS 和多数 Linux 发行版免驱）。装好后插上开发板，浏览器即可识别串口。

安装

本库是零依赖、纯 ES 模块，没有构建步骤，无需 Node.js 也能在浏览器里直接使用。以下三种方式任选其一：

方式一：npm

npm install nearlink-web-flasher

import { NearLinkFlasher } from 'nearlink-web-flasher';

方式二：从 Git 安装

npm install git+https://gitcode.com/hinearlink/nearlink-web-flasher.git

import { NearLinkFlasher } from 'nearlink-web-flasher';

方式三：无需 npm，浏览器直接 import

直接引用源码文件（演示页 examples/index.html 就是这种方式）：

<script type="module">
  // 本地引用（把 src 目录拷贝到你的项目里）
  import { NearLinkFlasher } from './nearlink-web-flasher/src/flasher.js';

  // 或直接引用 Git 仓库的 raw 地址
  // import { NearLinkFlasher } from 'https://gitcode.com/hinearlink/nearlink-web-flasher/raw/main/src/flasher.js';
</script>

⚠️ 无论哪种方式，页面都必须通过 http://localhost 或 https 访问。

快速开始

import { NearLinkFlasher } from 'nearlink-web-flasher';

const flasher = new NearLinkFlasher();
const file = document.querySelector('#firmware').files[0];

try {
  await flasher.flash(file, {
    baudRate: 115200,               // 传输波特率（可设 460800 / 921600 等）
    onProgress: ({ stage, percent, message }) => {
      console.log(`[${percent}%] ${message}`);
    },
  });
  console.log('烧录成功');
} catch (err) {
  console.error('烧录失败:', err);
}

烧录过程中，芯片需要按下 复位键（RST） 来完成握手（进度回调会给出 Wait for Handshake 提示）。

API

NearLinkFlasher

• flash(file, options) — 执行烧录
• disconnect() — 主动断开串口
• static isSupported() — 是否支持 Web Serial API

FwpkgParser

• parse(arrayBuffer) → { header, bins }
• static validate(arrayBuffer) → boolean

SerialPortManager

connect / disconnect / write / read / readExact / waitForPattern / readUntilMagic / changeBaudRate / setRTS 等。

NearLinkProtocol

buildCommandFrame / recvDataFrame / reqHandshake / reqReset / reqBaudrate / reqSendBin。

YModem

sendFileBuf(name, data, onProgress)。

目录结构

nearlink-web-flasher/
├── src/
│   ├── index.js           # 入口
│   ├── serial-port.js     # SerialPortManager 串口管理器
│   ├── crc16.js           # CRC16 校验
│   ├── protocol.js        # NearLinkProtocol 烧录协议
│   ├── ymodem.js          # YModem 传输
│   ├── fwpkg.js           # FwpkgParser 固件包解析
│   └── flasher.js         # NearLinkFlasher 编排器
├── docs/
│   ├── PROTOCOL.md        # 烧录协议说明
│   └── FWPKG_FORMAT.md    # .fwpkg 文件格式说明
├── examples/
│   └── index.html         # 最小可运行演示
└── README.md

演示

npx serve .        # 或 python -m http.server 8080

然后访问 examples/index.html（需 Chrome/Edge/Opera 89+）。

协议文档

• 烧录协议
• .fwpkg 固件包格式

相关资源

• 海星社区 StarFish：https://hinearlink.com（本库为海星社区「固件中心」在线烧录功能的开源版本）
• 固件仓库：https://gitcode.com/hinearlink/firmware_repo

测试

npm test        # 等价于 node --test

纯逻辑部分（CRC16 / .fwpkg 解析 / 协议帧构造 / YMODEM 组帧）已覆盖单元测试，无需真实硬件即可运行。

作者

GaoXiaolong · [email protected]

License

Apache License 2.0 © 2026 GaoXiaolong

本项目采用 Apache 2.0 许可证，含专利授权条款。分发时需保留 LICENSE 与 NOTICE 文件，修改过的文件需标注改动。