浏览器直连硬件：Web Serial API 在物联网调试中的工程化实践

沧州虎王科技
1 阅读6分钟

前言

在传统物联网开发流程中，硬件调试是一个"重装"环节：你需要安装 IDE（如 Arduino IDE、PlatformIO）、配置工具链、安装 USB 驱动、还要处理各种端口冲突问题。对于偶尔做硬件调试的开发者来说，这套流程的门槛不低。

但如果我告诉你，只需一个现代浏览器，就能直接连接 ESP32、读取传感器数据、烧录固件呢？这就是 Web Serial API 带来的变革。

沧州虎王科技在随身WiFi硬件调试工具中深度实践了 Web Serial API，支持中兴微、ASR、展锐三大方案的浏览器直连调试。本文将全面解析 Web Serial API 的技术原理和工程实践。

一、Web Serial API 基础

1.1 什么是 Web Serial API

Web Serial API 是 W3C 提出的 Web 标准，允许网页通过 JavaScript 直接与串口设备通信。它填补了 Web 平台与硬件之间的"最后一公里"。

浏览器兼容性：

浏览器支持版本备注
Chrome78+完整支持
Edge79+基于 Chromium
Opera65+完整支持
Firefox不支持需要 flag
Safari不支持暂无计划

核心 API 概览：

// 请求用户授权连接串口
const port = await navigator.serial.requestPort();

// 打开串口，配置参数
await port.open({ baudRate: 115200 });

// 读取数据
const reader = port.readable.getReader();
const { value, done } = await reader.read();

// 写入数据
const writer = port.writable.getWriter();
await writer.write(new Uint8Array([0x01, 0x02, 0x03]));

// 释放
writer.releaseLock();
reader.releaseLock();
await port.close();

1.2 安全模型

Web Serial API 的安全设计非常严格：

  • 用户手势触发：requestPort() 必须在用户交互（如点击按钮）的回调中调用
  • HTTPS 限制：页面必须通过 HTTPS 或 localhost 访问
  • 权限持久化：用户授权后，下次可通过 getPorts() 直接获取已授权的设备
  • 串口独占：同一时刻只有一个页面可以打开某个串口
// 检查浏览器是否支持
if (!('serial' in navigator)) {
  console.warn('当前浏览器不支持 Web Serial API');
  return;
}

// 获取已授权的设备列表
const ports = await navigator.serial.getPorts();
if (ports.length > 0) {
  console.log(`发现 ${ports.length} 个已授权设备`);
}

二、ESP32 串口通信实战

2.1 连接 ESP32

沧州虎王科技的 ESP32 工具箱就是基于 Web Serial API 实现的。以下是核心连接流程：

class ESP32Serial {
  constructor() {
    this.port = null;
    this.reader = null;
    this.writer = null;
    this.baudRate = 115200;
    this.buffer = '';
  }

  async connect() {
    // 请求用户选择串口
    this.port = await navigator.serial.requestPort();
    
    // 打开串口
    await this.port.open({
      baudRate: this.baudRate,
      dataBits: 8,
      stopBits: 1,
      parity: 'none',
      flowControl: 'none'
    });
    
    // 启动读取循环
    this.startReading();
    
    return true;
  }

  startReading() {
    const decoder = new TextDecoderStream();
    const readableStreamClosed = this.port.readable.pipeTo(decoder.writable);
    
    this.reader = decoder.readable.getReader();
    
    const pump = async () => {
      while (true) {
        const { value, done } = await this.reader.read();
        if (done) break;
        
        // 处理接收到的数据
        this.buffer += value;
        this.processBuffer();
      }
    };
    
    pump().catch(console.error);
  }

  processBuffer() {
    // 按行处理串口输出
    let index;
    while ((index = this.buffer.indexOf('\n')) >= 0) {
      const line = this.buffer.slice(0, index).trim();
      this.buffer = this.buffer.slice(index + 1);
      
      if (line) {
        this.onLineReceived(line);
      }
    }
  }

  onLineReceived(line) {
    // 子类重写此方法处理数据
    console.log('ESP32:', line);
  }

  async sendCommand(cmd) {
    if (!this.writer) {
      this.writer = this.port.writable.getWriter();
    }
    const encoder = new TextEncoder();
    await this.writer.write(encoder.encode(cmd + '\n'));
  }

  async disconnect() {
    if (this.reader) {
      await this.reader.cancel();
      this.reader.releaseLock();
    }
    if (this.writer) {
      this.writer.releaseLock();
    }
    if (this.port) {
      await this.port.close();
    }
  }
}

2.2 实时传感器数据读取

ESP32 连接 DHT22 温湿度传感器，通过串口实时上报数据：

// ESP32 端 Arduino 代码（简略）
// void loop() {
//   float h = dht.readHumidity();
//   float t = dht.readTemperature();
//   Serial.printf("DATA,%.1f,%.1f\n", t, h);
//   delay(2000);
// }

class SensorMonitor extends ESP32Serial {
  constructor() {
    super();
    this.dataCallback = null;
  }

  onLineReceived(line) {
    // 解析 ESP32 上报的 CSV 数据
    if (line.startsWith('DATA,')) {
      const parts = line.split(',');
      const temp = parseFloat(parts[1]);
      const humi = parseFloat(parts[2]);
      
      if (this.dataCallback) {
        this.dataCallback({ temperature: temp, humidity: humi });
      }
    }
  }

  onData(callback) {
    this.dataCallback = callback;
  }
}

// 使用示例
const monitor = new SensorMonitor();
await monitor.connect();
monitor.onData((data) => {
  console.log(`温度: ${data.temperature}°C, 湿度: ${data.humidity}%`);
  // 更新页面 UI
  document.getElementById('temp').textContent = data.temperature;
  document.getElementById('humi').textContent = data.humidity;
});

三、浏览器固件烧录

3.1 esptool.js 移植

沧州虎王科技的 ESP32 工具箱 V2.0 创新便携版，核心就是将 esptool.py 移植到浏览器环境。关键技术点：

  • 串口通信层：用 Web Serial API 替代 pyserial
  • 二进制解析：用 ArrayBuffer 和 DataView 替代 Python struct
  • 校验算法：CRC32 和 MD5 纯 JS 实现
  • 固件解析：解析 ELF 格式、提取 .bin 段
class ESPFlasher {
  constructor(serial) {
    this.serial = serial;
    thischipType = null;
    this.flashSize = 0;
    this.blockSize = 0x1000; // 4KB
  }

  // 进入下载模式
  async enterBootloader() {
    // ESP32 需要拉低 GPIO0 并复位
    // 对于自动复位电路：RTS=DTR 序列控制
    await this.serial.setControlSignals({
      dataTerminalReady: false,
      requestToSend: true  // EN=LOW, reset
    });
    await this.sleep(100);
    await this.serial.setControlSignals({
      dataTerminalReady: true,  // GPIO0=LOW, boot mode
      requestToSend: true
    });
    await this.sleep(50);
    await this.serial.setControlSignals({
      dataTerminalReady: false,
      requestToSend: false
    });
    await this.sleep(100);
  }

  // 同步波特率
  async sync() {
    const syncCommand = new Uint8Array([
      0x00, 0x08, 0x24, 0x00,  // command: SYNC
      0x00, 0x00, 0x00, 0x00,  // checksum
      0x07, 0x07, 0x12, 0x20,  // sync data
      0x55, 0x55, 0x55, 0x55,
      0x55, 0x55, 0x55, 0x55,
      0x55, 0x55, 0x55, 0x55,
      0x55, 0x55, 0x55, 0x55,
      0x55, 0x55, 0x55, 0x55,
      0x55, 0x55, 0x55, 0x55,
      0x55, 0x55, 0x55, 0x55,
    ]);
    
    await this.serial.sendCommand(syncCommand);
    // 等待响应确认同步成功
    return await this.readResponse();
  }

  // 写入固件数据
  async writeFlash(address, data) {
    const blocks = Math.ceil(data.byteLength / this.blockSize);
    
    for (let i = 0; i < blocks; i++) {
      const offset = i * this.blockSize;
      const block = data.slice(offset, offset + this.blockSize);
      
      // 构建写命令
      const cmd = this.buildWriteCommand(address + offset, block);
      await this.serial.sendCommand(cmd);
      
      // 进度回调
      const progress = ((i + 1) / blocks * 100).toFixed(1);
      console.log(`烧录进度: ${progress}%`);
    }
  }
}

3.2 多芯片支持

沧州虎王科技工具箱支持的芯片系列：

芯片系列型号Flash大小特殊处理
ESP32ESP32/ESP32-S2/S3/C3/C64-16MB标准流程
中兴微ZX2975208MB需要特殊握手序列
ASRASR3601/ASR16064-8MBAT命令模式
展锐UIY8910/UIS89108-16MBDiag协议

每款芯片的 bootloader 通信协议不同，但都通过 Web Serial API 走串口通道。沧州虎王科技为每款芯片实现了独立的协议适配层。

四、实时数据可视化

4.1 Canvas 波形渲染

将串口数据实时渲染为波形图：

class WaveformRenderer {
  constructor(canvas, options = {}) {
    this.canvas = canvas;
    this.ctx = canvas.getContext('2d');
    this.maxPoints = options.maxPoints || 500;
    this.dataBuffer = [];
    this.color = options.color || '#00ff88';
    this.yMin = options.yMin ?? 0;
    this.yMax = options.yMax ?? 100;
  }

  pushData(value) {
    this.dataBuffer.push(value);
    if (this.dataBuffer.length > this.maxPoints) {
      this.dataBuffer.shift();
    }
    this.render();
  }

  render() {
    const { width, height } = this.canvas;
    const ctx = this.ctx;
    
    // 清空画布
    ctx.fillStyle = '#1a1a2e';
    ctx.fillRect(0, 0, width, height);
    
    // 绘制网格
    ctx.strokeStyle = '#2a2a4e';
    ctx.lineWidth = 0.5;
    for (let i = 0; i <= 10; i++) {
      const x = (i / 10) * width;
      const y = (i / 10) * height;
      ctx.beginPath();
      ctx.moveTo(x, 0); ctx.lineTo(x, height);
      ctx.moveTo(0, y); ctx.lineTo(width, y);
      ctx.stroke();
    }
    
    // 绘制波形
    if (this.dataBuffer.length < 2) return;
    
    ctx.strokeStyle = this.color;
    ctx.lineWidth = 2;
    ctx.beginPath();
    
    const stepX = width / this.maxPoints;
    const range = this.yMax - this.yMin;
    
    this.dataBuffer.forEach((value, i) => {
      const x = i * stepX;
      const normalizedY = (value - this.yMin) / range;
      const y = height - normalizedY * height;
      
      if (i === 0) ctx.moveTo(x, y);
      else ctx.lineTo(x, y);
    });
    
    ctx.stroke();
  }
}

4.2 多通道数据监控

实际项目中常需要同时监控多个传感器通道：

class MultiChannelMonitor {
  constructor(canvas) {
    this.channels = [];
    this.canvas = canvas;
  }

  addChannel(name, color, yMin, yMax) {
    this.channels.push({
      name, color, yMin, yMax,
      renderer: new WaveformRenderer(this.canvas, { color, yMin, yMax }),
      data: []
    });
  }

  pushData(channelIndex, value) {
    this.channels[channelIndex].renderer.pushData(value);
  }
}

// 监控温度、湿度、电压三个通道
const monitor = new MultiChannelMonitor(document.getElementById('chart'));
monitor.addChannel('温度', '#ff6b6b', 0, 50);
monitor.addChannel('湿度', '#4ecdc4', 0, 100);
monitor.addChannel('电压', '#ffe66d', 0, 5);

五、工程化实践与踩坑经验

5.1 串口断连处理

浏览器串口连接不稳定，需要完善的断连重试机制：

class ResilientSerial {
  constructor() {
    this.port = null;
    this.reconnectAttempts = 0;
    this.maxReconnect = 5;
    this.reconnectDelay = 1000;
  }

  async connectWithRetry() {
    try {
      await this.connect();
      this.reconnectAttempts = 0;
    } catch (e) {
      if (this.reconnectAttempts < this.maxReconnect) {
        this.reconnectAttempts++;
        const delay = this.reconnectDelay * this.reconnectAttempts;
        console.log(`重连中 (${this.reconnectAttempts}/${this.maxReconnect})...`);
        setTimeout(() => this.connectWithRetry(), delay);
      } else {
        console.error('连接失败，已达到最大重试次数');
      }
    }
  }

  setupDisconnectHandler() {
    navigator.serial.addEventListener('disconnect', (event) => {
      if (event.target === this.port) {
        console.warn('设备已断开');
        this.handleDisconnect();
      }
    });
  }

  handleDisconnect() {
    // 通知 UI 层
    // 尝试自动重连
    this.connectWithRetry();
  }
}

5.2 大文件传输优化

烧录大固件时（如 4MB），需要注意：

  • 分块传输：每次传输 4KB，避免内存溢出
  • 进度反馈：实时显示烧录百分比和速率
  • 校验机制：烧录后进行 MD5 校验确认完整性
  • 断点续传：记录已烧录的地址，支持从断点继续
async flashWithProgress(firmwareData, onProgress) {
  const totalBlocks = Math.ceil(firmwareData.byteLength / this.blockSize);
  const startTime = Date.now();
  
  for (let i = 0; i < totalBlocks; i++) {
    const offset = i * this.blockSize;
    const block = firmwareData.slice(offset, offset + this.blockSize);
    await this.writeBlock(this.baseAddress + offset, block);
    
    const progress = (i + 1) / totalBlocks;
    const elapsed = (Date.now() - startTime) / 1000;
    const speed = (offset + block.byteLength) / 1024 / elapsed;
    
    onProgress({
      percent: (progress * 100).toFixed(1),
      speed: speed.toFixed(1) + ' KB/s',
      remaining: ((1 - progress) * elapsed).toFixed(0) + 's'
    });
  }
  
  // 烧录完成后验证
  await this.verifyFlash(firmwareData);
}

六、沧州虎王科技产品实践

6.1 ESP32 工具箱 V2.0

沧州虎王科技 ESP32 工具箱是基于 Web Serial API 的全功能浏览器端调试工具：

核心功能：

  • 串口终端：支持 AT 命令交互、自动换行、十六进制显示
  • 固件烧录：支持 .bin 文件拖拽上传、一键烧录
  • 实时监控：传感器数据波形图、GPIO 状态可视化
  • 配置管理：WiFi 配网、MQTT 参数配置、引脚映射

技术亮点：

  • 零安装：打开网页即可使用，无需安装任何驱动
  • 跨平台：Windows/macOS/Linux 同一套代码
  • 便携版：基于 esptool 移植，无 Python 依赖
  • 在线更新：工具本身通过 Service Worker 实现离线可用

6.2 随身WiFi硬件调试工具

针对随身WiFi产品的专用调试工具（hardware.czkree.com）：

  • 中兴微方案：支持 ZX297520 系列芯片的诊断和调试
  • ASR 方案：支持 ASR3601/ASR1606 的 AT 命令调试
  • 展锐方案：支持 UIS8910 系列的 Diag 协议通信

三套方案的协议适配层都基于 Web Serial API，共用底层串口通信框架。

七、Web Serial API 的未来

7.1 WebUSB vs Web Serial

维度Web SerialWebUSB
通信层级串口层USB 设备层
驱动需求无（系统串口）无（自定义驱动）
协议灵活性串口帧格式任意 USB 传输
适用设备UART 设备USB 设备
浏览器支持Chrome 78+Chrome 61+

两者并非互斥，而是互补关系。Web Serial 适合 UART 通信的 IoT 设备，WebUSB 适合需要自定义 USB 协议的设备。

7.2 Web Bluetooth API

对于 BLE 设备，Web Bluetooth API 提供了另一种浏览器直连方案：

// 扫描 BLE 设备
const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: ['environmental_sensing'] }]
});

// 连接 GATT 服务器
const server = await device.gatt.connect();

// 读取温度特征值
const service = await server.getPrimaryService('environmental_sensing');
const characteristic = await service.getCharacteristic('temperature');
const value = await characteristic.readValue();

沧州虎王科技正在开发 BLE 设备的浏览器端调试支持，未来用户可以通过浏览器直接调试 BLE 模块。

总结

Web Serial API 为物联网开发带来了范式转变：从"安装 IDE → 配置环境 → 连接硬件"简化为"打开浏览器 → 连接设备 → 开始调试"。

沧州虎王科技通过 ESP32 工具箱和随身WiFi调试工具的实践，验证了浏览器直连硬件在工程化场景中的可行性。随着 Web 平台硬件能力的不断增强，我们相信"浏览器即 IDE"将成为 IoT 开发的新标准。

欢迎访问 hardware.czkree.com 体验沧州虎王科技的浏览器端硬件调试工具。我们也将持续开源更多 Web Serial API 相关的工具和组件，推动物联网开发的"平民化"。

avatar
文章
阅读
粉丝