上次更新日期：2019 年 11 月 8 日
构建内容
在此 Codelab 中，您将构建一个使用 Web Serial API 与 BBC micro:bit 开发板在其 5x5 LED 矩阵上显示图片的网页。您将了解 Web Serial API，以及如何使用可读、可写和转换流通过浏览器与串行设备进行通信。
学习内容
- 如何打开和关闭 Web 串行端口
- 如何使用读取循环来处理来自输入流的数据
- 如何通过写入流发送数据
所需条件
- 采用最新 Espruino 固件的 BBC micro:bit 开发板
- 最新版 Chrome（78 或更高版本）
- 了解 HTML、CSS、JavaScript 和 Chrome 开发者工具
我们之所以选择在此 Codelab 中使用 micro:bit，是因为它经济实惠、可以提供几个输入（按钮）和输出（5x5 LED 显示屏），还可以提供更多输入和输出。如需详细了解 micro:bit 的功能，请参阅 Espruino 网站上的 BBC micro:bit 页面。
Web Serial API 为网站提供了一种通过脚本对串行设备执行读写操作的方式。该 API 允许网站与串行设备（例如微控制器和 3D 打印机）通信，从而将网络和现实世界联系起来。
有很多使用网络技术构建的控制软件示例。例如：
在某些情况下，这些网站会通过用户手动安装的原生代理应用与设备进行通信。在其他情况下，应用通过 Electron 等框架在打包的原生应用中提供。而在其他情况下，用户则需要执行额外的步骤，例如使用 U 盘将编译的应用复制到设备。
通过在网站和要控制的设备之间提供直接通信，可以改善用户体验。
启用 Web Serial API
Web Serial API 目前正在开发中，只能在标记后面使用。您必须在 chrome://flags 中启用 #enable-experimental-web-platform-features 标志。
获取代码
我们已将此 Codelab 所需的所有内容加入 Glitch 项目中。
- 打开新的浏览器标签页，然后转到 https://web-serial-codelab-start.glitch.me/。
- 点击 Remix Glitch 链接，创建您自己的入门级项目版本。
- 点击显示按钮，然后选择在新窗口中，查看代码的实际运行情况。
检查 Web Serial API 是否受支持
首先需要检查当前浏览器是否支持 Web Serial API。为此，请检查 serial 是否在 navigator 中。
在 DOMContentLoaded 事件中，将以下代码添加到您的项目中：
script.js - DOMContentLoaded
// CODELAB: Add feature detection here.
if ('serial' in navigator) {
const notSupported = document.getElementById('notSupported');
notSupported.classList.add('hidden');
}这项检查旨在检查网络序列号是否受支持。如果支持，则此代码会隐藏显示不支持 Web Serial 的横幅。
试试看
- 加载网页。
- 验证网页是否未显示表示 Web Serial 不受支持的红色横幅。
打开串行端口
接下来，我们需要打开串行端口。与大多数其他现代 API 一样，Web Serial API 是异步的。这样可防止界面在等待输入时发生阻塞，但这也很重要，因为网页随时可能会收到串行数据，而我们需要一种方法来侦听该数据。
由于计算机可能有多个串行设备，因此当浏览器尝试请求端口时，它会提示用户选择要连接哪个设备。
将以下代码添加到您的项目中：
script.js - connect()
// CODELAB: Add code to request & open port here.
// - Request a port and open a connection.
port = await navigator.serial.requestPort();
// - Wait for the port to open.
await port.open({ baudrate: 9600 });requestPort 调用会提示用户要连接到哪个设备。调用 port.open 会打开端口。我们还需要提供与串行设备通信的速度。BBC micro:bit 使用 USB 转序列芯片与主处理器之间的 9600 波特连接。
我们还将连接按钮连接起来，让用户点击该按钮时调用 connect()。
将以下代码添加到您的项目中：
script.js - clickConnect()
// CODELAB: Add connect code here.
await connect();试试看
我们的项目现在已具备最低的入门费用。点击连接按钮会提示用户选择要连接的串行设备，然后连接到 micro:bit。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 在该标签页上，您应该会看到指示您已连接到串行设备的图标：
设置输入流以监听串行端口中的数据
建立连接后，我们需要设置输入流和读取器，以从设备读取数据。首先，我们通过调用 port.readable 从端口获取可读数据流。我们知道从设备接收文本后，会通过管道进行解码。接下来，我们将获取读取器并开始读取循环。
将以下代码添加到您的项目中：
script.js - connect()
// CODELAB: Add code to read the stream here.
let decoder = new TextDecoderStream();
inputDone = port.readable.pipeTo(decoder.writable);
inputStream = decoder.readable;
reader = inputStream.getReader();
readLoop();读取循环是一个异步函数，它在一个循环中运行，并等待内容但不阻塞主线程。收到新数据时，读取器会返回两个属性：value 和 done 布尔值。如果 done 为 true，则表示端口已关闭或没有更多数据传入。
将以下代码添加到您的项目中：
script.js - readLoop()
// CODELAB: Add read loop here.
while (true) {
const { value, done } = await reader.read();
if (value) {
log.textContent += value + '\n';
}
if (done) {
console.log('[readLoop] DONE', done);
reader.releaseLock();
break;
}
}试试看
我们的项目现在可以连接到设备，并将从设备接收到的所有数据附加到日志元素。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 您应该会看到 Espruino 徽标：
设置输出流以向串行端口发送数据
串行通信通常是双向的。除了从串行端口接收数据之外，我们还希望将数据发送到端口。和输入流一样，我们只会通过输出流向 micro:bit 发送文本。
首先，创建一个文本编码器流，并将声音流传输到 port.writeable。
script.js - connect()
// CODELAB: Add code setup the output stream here.
const encoder = new TextEncoderStream();
outputDone = encoder.readable.pipeTo(port.writable);
outputStream = encoder.writable;当通过串行与 Espruino 固件串行连接时，BBC 微:位板会充当 JavaScript 读取-求值输出循环 (REPL)，这与在 Node.js shell 中类似。接下来，我们需要提供向数据流发送数据的方法。以下代码会从输出流中获取写入器，然后使用 write 发送每一行。发送的每一行都包含换行符 (\n)，用于告知 micro:bit 对发送的命令求值。
script.js - writeToStream()
// CODELAB: Write to output stream
const writer = outputStream.getWriter();
lines.forEach((line) => {
console.log('[SEND]', line);
writer.write(line + '\n');
});
writer.releaseLock();要将系统置于已知状态并阻止其回显我们向其发送的字符，我们需要发送 CTRL-C 并关闭回声。
script.js - connect()
// CODELAB: Send CTRL-C and turn off echo on REPL
writeToStream('\x03', 'echo(false);');试试看
我们的项目现在可以从 micro:bit 发送和接收数据。让我们验证一下能否正常发送命令：
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 在 Chrome DevTools 中打开 Console 标签页，然后输入
writeToStream('console.log("yes")');
您应该会在页面上看到如下所示的内容：
构建矩阵网格字符串
如需控制 micro:bit 上的 LED 矩阵，我们需要调用 show()。此方法在内置 5x5 LED 屏幕上显示图形。这需要一个二进制数或字符串。
我们将遍历复选框，生成一个由 1 和 0 组成的数组，用于指明已选中和未勾选的项。然后，我们需要反转阵列，因为复选框的顺序与矩阵中的 LED 的顺序相反。接下来，我们将数组转换为字符串，并创建要发送到 micro:bit 的命令。
script.js - sendGrid()
// CODELAB: Generate the grid
const arr = [];
ledCBs.forEach((cb) => {
arr.push(cb.checked === true ? 1 : 0);
});
writeToStream(`show(0b${arr.reverse().join('')})`);连接复选框以更新矩阵
接下来，我们需要监听复选框的更改，如果复选框发生更改，则将这些信息发送到 micro:bit。在特征检测代码 (// CODELAB: Add feature detection here.) 中，添加以下代码行：
script.js - DOMContentLoaded
initCheckboxes();此外，我们还会在 micro:bit 首次连接时重置网格，以便其显示笑脸。已提供 drawGrid() 函数。此函数的工作方式类似于 sendGrid()；它接受一个由 1 和 0 组成的数组，并视情况勾选复选框。
script.js - clickConnect()
// CODELAB: Reset the grid on connect here.
drawGrid(GRID_HAPPY);
sendGrid();试试看
现在，当网页打开与 micro:bit 的连接时，会发送一个笑脸。点击复选框将更新 LED 矩阵上的显示屏。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 微型 LED 矩阵应该会显示笑脸符号。
- 通过更改复选框，在 LED 矩阵上绘制不同的图案。
在微按钮上添加观看事件
微型位上有两个按钮，一个位于 LED 矩阵的两侧。Espruino 提供了一个 setWatch 函数，可在用户按下按钮时发送事件/回调。由于我们希望同时监听这两个按钮，因此我们将函数变为通用函数，并输出事件的详细信息。
script.js - watchButton()
// CODELAB: Hook up the micro:bit buttons to print a string.
const cmd = `
setWatch(function(e) {
print('{"button": "${btnId}", "pressed": ' + e.state + '}');
}, ${btnId}, {repeat:true, debounce:20, edge:"both"});
`;
writeToStream(cmd);接下来，每次将串行端口连接到设备时，我们都需要连接两个按钮（在微板上名为 BTN1 和 BTN2）。
script.js - clickConnect()
// CODELAB: Initialize micro:bit buttons.
watchButton('BTN1');
watchButton('BTN2');试试看
除了在连接时显示笑脸，您还可以按微按钮上的任意按钮向页面添加文字，指示用户按下的是哪个按钮。每个字符很可能独占一行。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 微笑 LED 矩阵上应有微笑。
- 按下 micro:bit 上的按钮，验证按钮是否将新的文本附加到按下的按钮的详情对应的网页上。
基本流处理
当推送其中一个 micro:bit 按钮时，micro:bit 会通过信息流将数据发送到串行端口。数据流非常有用，但也有可能是一项挑战，因为您不一定能一次性获取所有数据，这些数据可能会被任意分块。
该应用目前在传入的流中（传入 readLoop 中）输出传入的流。在大多数情况下，每个字符各占一行，但这并不是很有用。理想情况下，流应解析为单独的行，并且每条消息都显示为单独的行。
使用 TransformStream 转换数据流
为此，我们可以使用转换流 (TransformStream)，这样就可以解析传入的流并返回解析后的数据。转换流可位于流源（在本例中为 micro:bit）与消耗流（本例中为 readLoop）之间的任何环境中，并且可以在任意最终转换之前应用任意转换。您可以将其想象成一条组装线：当微件沿着线条向下时，直线中的每个步骤都会修改该微件，这样，当它到达最终目标位置时，它是一个功能齐全的微件。
如需了解详情，请参阅 MDN's Streams API 概念。
使用 LineBreakTransformer 转换信息流
让我们创建一个 LineBreakTransformer 类，该类接受流并根据换行符 (\r\n) 进行分块。该类需要两个方法：transform 和 flush。每次数据流收到新数据时，系统都会调用 transform 方法。它可以将数据加入队列，也可以保存数据供日后使用。当流关闭时，系统会调用 flush 方法，该方法会处理尚未处理的数据。
在 transform 方法中，我们会向 container 添加新数据，然后检查 container 中是否存在换行符。如果有，将其拆分为一个数组，然后遍历行，调用 controller.enqueue() 以将解析的行发送出去。
script.js - LineBreakTransformer.transform()
// CODELAB: Handle incoming chunk
this.container += chunk;
const lines = this.container.split('\r\n');
this.container = lines.pop();
lines.forEach(line => controller.enqueue(line));当流关闭时，我们只需使用 enqueue 清空容器中的所有剩余数据。
script.js - LineBreakTransformer.flush()
// CODELAB: Flush the stream.
controller.enqueue(this.container);最后，我们需要通过新的 LineBreakTransformer 传输传入的数据流。我们的原始输入流仅通过 TextDecoderStream 管道处理，因此我们需要添加一个额外的 pipeThrough 以通过新的 LineBreakTransformer 进行管道处理。
script.js - connect()
// CODELAB: Add code to read the stream here.
let decoder = new TextDecoderStream();
inputDone = port.readable.pipeTo(decoder.writable);
inputStream = decoder.readable
.pipeThrough(new TransformStream(new LineBreakTransformer()));试试看
现在，当您按其中一个 micro:bit 按钮时，输出的数据应单行返回。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 微型 LED 矩阵应该会显示笑脸符号。
- 按下 micro:bit 上的按钮，并验证您是否看到如下内容：
使用 JSONTransformer 转换信息流
我们可以尝试在 readLoop 中将字符串解析为 JSON，但让我们创建一个非常简单的 JSON 转换器，可将数据转换为 JSON 对象。如果数据不是有效的 JSON，只需返回结果即可。
script.js - JSONTransformer.transform
// CODELAB: Attempt to parse JSON content
try {
controller.enqueue(JSON.parse(chunk));
} catch (e) {
controller.enqueue(chunk);
}接下来，流在通过 LineBreakTransformer 后通过 JSONTransformer 传输。这样，我们就可以确保 JSONTransformer 保持简单，因为我们知道 JSON 永远只会以一行的形式发送。
script.js - connect
// CODELAB: Add code to read the stream here.
let decoder = new TextDecoderStream();
inputDone = port.readable.pipeTo(decoder.writable);
inputStream = decoder.readable
.pipeThrough(new TransformStream(new LineBreakTransformer()))
.pipeThrough(new TransformStream(new JSONTransformer()));试试看
现在，当您按任一 micro:bit 按钮时，您应该会看到页面上输出了 [object Object]。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 微型 LED 矩阵应该会显示笑脸符号。
- 按下 micro:bit 上的按钮，并验证您是否看到如下内容：
响应按钮按下操作
如需响应 micro:bit 按钮按下操作，请更新 readLoop 以检查它收到的数据是否为具有 button 属性的 object。然后，调用 buttonPushed 来处理按钮推送。
script.js - readLoop()
const { value, done } = await reader.read();
if (value && value.button) {
buttonPushed(value);
} else {
log.textContent += value + '\n';
}按下 micro:bit 按钮时，LED 矩阵上的显示屏应发生变化。使用以下代码来设置矩阵：
script.js - buttonPushed()
// CODELAB: micro:bit button press handler
if (butEvt.button === 'BTN1') {
divLeftBut.classList.toggle('pressed', butEvt.pressed);
if (butEvt.pressed) {
drawGrid(GRID_HAPPY);
sendGrid();
}
return;
}
if (butEvt.button === 'BTN2') {
divRightBut.classList.toggle('pressed', butEvt.pressed);
if (butEvt.pressed) {
drawGrid(GRID_SAD);
sendGrid();
}
}试试看
现在，当您按任一 micro:bit 按钮时，您的 LED 矩阵应变为笑脸或伤心表情。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 微笑 LED 矩阵上应有微笑。
- 按下微型位上的按钮，确认 LED 矩阵更改。
最后一步是连接断开连接功能，以便在用户完成时关闭端口。
当用户点击“连接/断开连接”按钮时，关闭端口
当用户点击连接/断开连接按钮时，我们需要关闭连接。如果端口已打开，请调用 disconnect() 并更新界面，以表明该网页不再连接到串行设备。
script.js - clickConnect()
// CODELAB: Add disconnect code here.
if (port) {
await disconnect();
toggleUIConnected(false);
return;
}关闭数据流和端口
在 disconnect 函数中，我们需要关闭输入流，关闭输出流，然后关闭端口。要关闭输入流，请调用 reader.cancel()。对 cancel 的调用是异步的，因此我们需要使用 await 来等待它完成：
script.js - disconnect()
// CODELAB: Close the input stream (reader).
if (reader) {
await reader.cancel();
await inputDone;
reader = null;
inputDone = null;
}要关闭输出流，请获取 writer，调用 close() 并等待 outputDone 对象关闭：
script.js - disconnect()
// CODELAB: Close the output stream.
if (outputStream) {
await outputStream.getWriter().close();
await outputDone;
outputStream = null;
outputDone = null;
}最后，关闭串行端口并等待其关闭：
script.js - disconnect()
// CODELAB: Close the port.
await port.close();
port = null;试试看
现在，您可以根据需要随意打开和关闭串行端口。
- 重新加载页面。
- 点击连接按钮。
- 在串行端口选择器对话框中，选择 BBC micro:bit 设备，然后点击 Connect。
- 您应该会在微型 LED 矩阵中看到微笑
- 按断开连接按钮，确认 LED 矩阵已关闭，并且控制台中没有出现错误。
恭喜！您已成功构建自己的第一个使用 Web Serial API 的 Web 应用。
请关注 https://goo.gle/fugu-api-tracker，了解 Web Serial API 的最新动态以及 Chrome 团队正在努力开发的所有其他激动人心的新网络功能。