了解如何使用 WebAssembly 和 Fugu API 将与外部设备交互的代码移植到 Web。
在之前的一篇博文中,我介绍了如何使用 File System Access API、WebAssembly 和 Asyncify 将使用文件系统 API 的应用移植到 Web 中。现在,我想继续讨论将 Fugu API 与 WebAssembly 集成以及将应用移植到 Web 不丢失重要功能这一主题。
我将介绍如何将与 USB 设备通信的应用移植到 Web 中,方法是将 libusb(一种使用 C 语言编写的热门 USB 库)移植到 WebAssembly(通过 Emscripten)、Asyncify 和 WebUSB 中。
当务之急:演示
移植库时要做的最重要的事情是选择正确的演示,这样做可以展示所移植库的功能,从而使您能够以多种方式对其进行测试,并同时具有视觉吸引力。
我当初选的是数码单反遥控器特别值得一提的是,开源项目 gPhoto2 已经在这一领域拥有足够的时间,足以对各种数码相机进行逆向工程并实现支持。它支持多种协议,但我最感兴趣的是它通过 libusb 执行的 USB 支持。
我将分两部分来介绍构建此演示的步骤。在这篇博文中,我将说明我如何移植 libusb 本身,以及将其他热门库移植到 Fugu API 可能需要哪些技巧。在第二篇帖子中,我将详细介绍如何移植和集成 gPhoto2 本身。
最后,我开发了一个正常运行的 Web 应用,该应用可预览数码单反相机的实时画面,并可通过 USB 控制其设置。在了解技术细节之前,您可以先观看现场演示或预先录制的演示:
关于摄像头特定怪异问题的注意事项
您可能已经注意到,在视频中更改设置需要一段时间。与您可能遇到的大多数其他问题一样,这并非由 WebAssembly 或 WebUSB 的性能所致,而是由 gPhoto2 与为演示选择的特定相机进行互动的方式所致。
Sony a6600 没有提供用于直接设置 ISO、光圈或快门速度等值的 API,而只提供相应命令来按指定的步数增加或减少这些值。更为复杂的是,该 API 也不会返回实际支持的值的列表 - 返回的列表似乎在许多索尼相机型号中经过硬编码。
设置其中一个值时,gPhoto2 只能执行以下操作:
- 朝所选值的方向迈一步(或几步)。
- 请稍等片刻,让相机更新设置。
- 读回相机实际降落的值。
- 检查最后一步,确保既没有跳过期望的值,也没有环绕列表的末尾或开头。
- 重复。
这可能需要一些时间,但如果相机实际支持该值,则会直接到达,如果该值不支持,则停止在最接近的支持值上。
其他相机可能有不同的设置、底层 API 和怪异行为集。请注意,gPhoto2 是一个开源项目,对所有相机型号进行自动或手动测试根本不可行,因此我们随时欢迎您提供详细的问题报告和 PR(但请确保先使用官方 gPhoto2 客户端重现问题)。
关于跨平台兼容性的重要说明
遗憾的是,在 Windows 上,任何“知名”设备(包括数码单反相机)都分配有与 WebUSB 不兼容的系统驱动程序。如果您想在 Windows 上试用演示版,必须使用 Zadig 等工具将已连接的数码单反的驱动程序替换为 WinUSB 或 libusb。此方法对我和许多其他用户都很有效,但使用时需自行承担风险。
在 Linux 上,您可能需要设置自定义权限,以允许通过 WebUSB 使用数码单反相机,不过这取决于您的发行版。
在 macOS 和 Android 上,演示版应开箱即可使用。如果您是在 Android 手机上试用,请务必切换到横屏模式,因为我没有花太多精力使它能够快速响应(欢迎提供 PR!):
![Android 手机已通过 USB-C 数据线连接到佳能相机。](https://web.developers.google.cn/static/articles/porting-libusb-to-webusb/image/android-phone-connected-5bc06721b5e43.jpg?authuser=6&hl=da)
如需深入了解如何跨平台使用 WebUSB 的指南,请参阅“构建支持 WebUSB 的设备”中的“针对具体平台的注意事项”部分。
向 libusb 添加新的后端
现在来了解技术细节。虽然可以提供类似于 libusb 的 shim API(之前他人已完成过该 API),并可以针对该 API 关联其他应用,但这种方法容易出错,并且会使进一步的扩展或维护工作变得更加困难。我想做点正确的事,这样日后或许可以回馈上游并合并到 libusb。
幸运的是,libusb README 中指出:
“libusb 的内部提取方式很有可能移植到其他操作系统中。如需了解详情,请参阅 PORTING 文件。”
libusb 的结构是公共 API 与“后端”分开的。这些后端负责列出、打开、关闭设备,以及通过操作系统的低级别 API 与设备进行实际通信。这也是 libusb 用来抽象化 Linux、macOS、Windows、Android、OpenBSD/NetBSD、Haiku 和 Solaris 之间的不同之处的方式,并且可在所有这些平台上运行。
我要为 Emscripten+WebUSB“操作系统”再添加一个后端。这些后端的实现位于 libusb/os
文件夹中:
~/w/d/libusb $ ls libusb/os
darwin_usb.c haiku_usb_raw.h threads_posix.lo
darwin_usb.h linux_netlink.c threads_posix.o
events_posix.c linux_udev.c threads_windows.c
events_posix.h linux_usbfs.c threads_windows.h
events_posix.lo linux_usbfs.h windows_common.c
events_posix.o netbsd_usb.c windows_common.h
events_windows.c null_usb.c windows_usbdk.c
events_windows.h openbsd_usb.c windows_usbdk.h
haiku_pollfs.cpp sunos_usb.c windows_winusb.c
haiku_usb_backend.cpp sunos_usb.h windows_winusb.h
haiku_usb.h threads_posix.c
haiku_usb_raw.cpp threads_posix.h
每个后端都包含 libusbi.h
标头(具有通用类型和帮助程序),并且需要公开一个类型为 usbi_os_backend
的 usbi_backend
变量。例如,Windows 后端应如下所示:
const struct usbi_os_backend usbi_backend = {
"Windows",
USBI_CAP_HAS_HID_ACCESS,
windows_init,
windows_exit,
windows_set_option,
windows_get_device_list,
NULL, /* hotplug_poll */
NULL, /* wrap_sys_device */
windows_open,
windows_close,
windows_get_active_config_descriptor,
windows_get_config_descriptor,
windows_get_config_descriptor_by_value,
windows_get_configuration,
windows_set_configuration,
windows_claim_interface,
windows_release_interface,
windows_set_interface_altsetting,
windows_clear_halt,
windows_reset_device,
NULL, /* alloc_streams */
NULL, /* free_streams */
NULL, /* dev_mem_alloc */
NULL, /* dev_mem_free */
NULL, /* kernel_driver_active */
NULL, /* detach_kernel_driver */
NULL, /* attach_kernel_driver */
windows_destroy_device,
windows_submit_transfer,
windows_cancel_transfer,
NULL, /* clear_transfer_priv */
NULL, /* handle_events */
windows_handle_transfer_completion,
sizeof(struct windows_context_priv),
sizeof(union windows_device_priv),
sizeof(struct windows_device_handle_priv),
sizeof(struct windows_transfer_priv),
};
通过查看这些属性,我们可以看到该结构体包括后端名称、一组功能、以函数指针形式表示的各种低级别 USB 操作的处理程序,以及要分配用于存储私有设备/上下文/传输级数据的大小。
私有数据字段至少对于存储上述所有内容的操作系统句柄非常有用,因为如果没有句柄,我们将不知道任何给定操作适用于哪个项。在 Web 实现中,操作系统句柄是底层 WebUSB JavaScript 对象。在 Emscripten 中表示和存储这些对象的自然方式是通过 emscripten::val
类,该类作为 Embind(Emscripten 的绑定系统)的一部分提供。
文件夹中的大多数后端使用 C 语言实现,但也有少数后端是在 C++ 中实现的。Embind 仅适用于 C++,因此是为我选择的,我已为私有数据字段添加了 libusb/libusb/os/emscripten_webusb.cpp
和 sizeof(val)
:
#include <emscripten.h>
#include <emscripten/val.h>
#include "libusbi.h"
using namespace emscripten;
// …function implementations
const usbi_os_backend usbi_backend = {
.name = "Emscripten + WebUSB backend",
.caps = LIBUSB_CAP_HAS_CAPABILITY,
// …handlers—function pointers to implementations above
.device_priv_size = sizeof(val),
.transfer_priv_size = sizeof(val),
};
将 WebUSB 对象存储为设备句柄
libusb 提供指向私有数据分配区域的现成指针。为了将这些指针作为 val
实例使用,我添加了一些小型辅助程序,用于就地构造指针,将其检索为引用,然后移出值:
// We store an Embind handle to WebUSB USBDevice in "priv" metadata of
// libusb device, this helper returns a pointer to it.
struct ValPtr {
public:
void init_to(val &&value) { new (ptr) val(std::move(value)); }
val &get() { return *ptr; }
val take() { return std::move(get()); }
protected:
ValPtr(val *ptr) : ptr(ptr) {}
private:
val *ptr;
};
struct WebUsbDevicePtr : ValPtr {
public:
WebUsbDevicePtr(libusb_device *dev)
: ValPtr(static_cast<val *>(usbi_get_device_priv(dev))) {}
};
val &get_web_usb_device(libusb_device *dev) {
return WebUsbDevicePtr(dev).get();
}
struct WebUsbTransferPtr : ValPtr {
public:
WebUsbTransferPtr(usbi_transfer *itransfer)
: ValPtr(static_cast<val *>(usbi_get_transfer_priv(itransfer))) {}
};
同步 C 上下文中的异步 Web API
现在,需要一种方式来处理 libusb 需要同步操作的异步 WebUSB API。为此,我可以使用 Asyncify,具体来说就是通过 val::await()
使用其 Embind 集成。
我还想正确处理 WebUSB 错误并将其转换为 libusb 错误代码,但 Embind 目前没有办法处理 C++ 端的 JavaScript 异常或 Promise
拒绝。这个问题可以解决,方法是在 JavaScript 端捕获遭拒,并将结果转换为现在可以从 C++ 端安全解析的 { error, value }
对象。我结合使用 EM_JS
宏和 Emval.to{Handle, Value}
API 来实现此目的:
EM_JS(EM_VAL, em_promise_catch_impl, (EM_VAL handle), {
let promise = Emval.toValue(handle);
promise = promise.then(
value => ({error : 0, value}),
error => {
const ERROR_CODES = {
// LIBUSB_ERROR_IO
NetworkError : -1,
// LIBUSB_ERROR_INVALID_PARAM
DataError : -2,
TypeMismatchError : -2,
IndexSizeError : -2,
// LIBUSB_ERROR_ACCESS
SecurityError : -3,
…
};
console.error(error);
let errorCode = -99; // LIBUSB_ERROR_OTHER
if (error instanceof DOMException)
{
errorCode = ERROR_CODES[error.name] ?? errorCode;
}
else if (error instanceof RangeError || error instanceof TypeError)
{
errorCode = -2; // LIBUSB_ERROR_INVALID_PARAM
}
return {error: errorCode, value: undefined};
}
);
return Emval.toHandle(promise);
});
val em_promise_catch(val &&promise) {
EM_VAL handle = promise.as_handle();
handle = em_promise_catch_impl(handle);
return val::take_ownership(handle);
}
// C++ struct representation for {value, error} object from above
// (performs conversion in the constructor).
struct promise_result {
libusb_error error;
val value;
promise_result(val &&result)
: error(static_cast<libusb_error>(result["error"].as<int>())),
value(result["value"]) {}
// C++ counterpart of the promise helper above that takes a promise, catches
// its error, converts to a libusb status and returns the whole thing as
// `promise_result` struct for easier handling.
static promise_result await(val &&promise) {
promise = em_promise_catch(std::move(promise));
return {promise.await()};
}
};
现在,我可以对从 WebUSB 操作返回的任何 Promise
使用 promise_result::await()
,并单独检查其 error
和 value
字段。
例如,从 libusb_device_handle
检索表示 USBDevice
的 val
,调用其 open()
方法,等待结果,并返回错误代码作为 libusb 状态代码,如下所示:
int em_open(libusb_device_handle *handle) {
auto web_usb_device = get_web_usb_device(handle->dev);
return promise_result::await(web_usb_device.call<val>("open")).error;
}
设备枚举
当然,libusb 需要先检索可用设备列表,然后才能打开任何设备。后端必须通过 get_device_list
处理程序实现此操作。
问题在于,与其他平台不同,出于安全考虑,无法枚举网络上所有已连接的 USB 设备。相反,该流程分为两部分。首先,Web 应用通过 navigator.usb.requestDevice()
请求具有特定属性的设备,然后用户手动选择想要公开的设备,或者拒绝权限提示。之后,应用会通过 navigator.usb.getDevices()
列出已批准且已连接的设备。
起初,我尝试直接在 get_device_list
处理程序的实现中使用 requestDevice()
。不过,显示包含已连接设备列表的权限提示被视为敏感操作,必须由用户互动(例如点击页面上的按钮)触发,否则始终会返回被拒绝的 promise。libusb 应用往往希望在应用启动时列出已连接的设备,因此不能选择使用 requestDevice()
。
因此,我不得不将 navigator.usb.requestDevice()
的调用留给最终开发者,并且只公开 navigator.usb.getDevices()
中已获批准的设备:
// Store the global `navigator.usb` once upon initialisation.
thread_local const val web_usb = val::global("navigator")["usb"];
int em_get_device_list(libusb_context *ctx, discovered_devs **devs) {
// C++ equivalent of `await navigator.usb.getDevices()`.
// Note: at this point we must already have some devices exposed -
// caller must have called `await navigator.usb.requestDevice(...)`
// in response to user interaction before going to LibUSB.
// Otherwise this list will be empty.
auto result = promise_result::await(web_usb.call<val>("getDevices"));
if (result.error) {
return result.error;
}
auto &web_usb_devices = result.value;
// Iterate over the exposed devices.
uint8_t devices_num = web_usb_devices["length"].as<uint8_t>();
for (uint8_t i = 0; i < devices_num; i++) {
auto web_usb_device = web_usb_devices[i];
// …
*devs = discovered_devs_append(*devs, dev);
}
return LIBUSB_SUCCESS;
}
大多数后端代码都采用类似上面所示的方式使用 val
和 promise_result
。数据传输处理代码中还有一些其他有趣的小窍门,但是对于本文而言,这些实现细节不太重要。如果您感兴趣,请务必在 GitHub 上查看代码和相关注释。
将事件循环移植到 Web
关于 libusb 端口,我想讨论的另一方面是事件处理。如前一篇文章所述,系统语言(如 C)中的大多数 API 都是同步的,事件处理也不例外。它通常通过无限循环来实现,该循环从一组外部 I/O 源“轮询”(尝试读取数据或阻止执行,直到有可用的数据),当至少有一个外部 I/O 源响应时,将其作为事件传递给相应的处理程序。处理程序完成后,该控件将返回到循环,然后暂停以进行另一轮询。
在网络上使用这种方法存在几个问题。
首先,WebUSB 不会且无法公开底层设备的原始句柄,因此无法直接轮询这些句柄。其次,libusb 会将 eventfd
和 pipe
API 用于其他事件,以及处理没有原始设备句柄的操作系统上的传输,但 Emscripten 目前不支持 eventfd
;pipe
虽然受支持,但目前不符合规范且无法等待事件。
最后,最大的问题是网络有自己的事件循环。此全局事件循环可用于任何外部 I/O 操作(包括 fetch()
、计时器或在本示例中为 WebUSB),并且每当相应的操作完成时,它都会调用事件或 Promise
处理程序。执行另一个嵌套的无限事件循环将阻止浏览器的事件循环继续进行,这意味着不仅界面将无响应,而且代码也永远不会收到其在等待的完全相同的 I/O 事件的通知。这通常会导致死锁,当我尝试在演示中使用 libusb 时也是如此。页面冻结了。
与其他阻塞 I/O 一样,如需将此类事件循环移植到 Web,开发者需要找到一种方法来运行这些循环,而不会阻塞主线程。一种方法是重构应用,以便在单独的线程中处理 I/O 事件,并将结果传递回主线程。另一种方式是使用 Asyncify 暂停循环并以非阻塞方式等待事件。
我不想对 libusb 或 gPhoto2 进行重大更改,而且我已经使用 Asyncify 进行 Promise
集成,因此这是我选择的路径。为了模拟 poll()
的阻塞变体,对于初始概念验证,我使用了如下所示的循环:
#ifdef __EMSCRIPTEN__
// TODO: optimize this. Right now it will keep unwinding-rewinding the stack
// on each short sleep until an event comes or the timeout expires.
// We should probably create an actual separate thread that does signaling
// or come up with a custom event mechanism to report events from
// `usbi_signal_event` and process them here.
double until_time = emscripten_get_now() + timeout_ms;
do {
// Emscripten `poll` ignores timeout param, but pass 0 explicitly just
// in case.
num_ready = poll(fds, nfds, 0);
if (num_ready != 0) break;
// Yield to the browser event loop to handle events.
emscripten_sleep(0);
} while (emscripten_get_now() < until_time);
#else
num_ready = poll(fds, nfds, timeout_ms);
#endif
它的作用是:
- 调用
poll()
以检查后端是否已报告任何事件。如果有,则循环停止。否则,Escripten 的poll()
实现将立即返回0
。 - 调用
emscripten_sleep(0)
。此函数在后台使用 Asyncify 和setTimeout()
,并在此处用于将控制权交还给主浏览器事件循环。这样一来,浏览器就可以处理任何用户互动和 I/O 事件,包括 WebUSB。 - 检查指定的超时是否已过期,如果未过期,则继续循环。
正如评论所提到的,此方法并不是最优的,因为它使用 Asyncify 保存和恢复整个调用堆栈,即使目前没有要处理的 USB 事件(大多数时候)也是如此,并且 setTimeout()
在现代浏览器中的时长下限为 4 毫秒。尽管如此,它仍然非常出色,在概念验证期间可以通过数码单反相机生成 13-14 FPS 的直播视频。
后来,我决定利用浏览器事件系统对其进行改进。可以通过多种方式进一步改进此实现,但目前我选择直接在全局对象上发出自定义事件,而无需将它们与特定的 libusb 数据结构相关联。我已通过基于 EM_ASYNC_JS
宏的以下等待和通知机制做到了这一点:
EM_JS(void, em_libusb_notify, (void), {
dispatchEvent(new Event("em-libusb"));
});
EM_ASYNC_JS(int, em_libusb_wait, (int timeout), {
let onEvent, timeoutId;
try {
return await new Promise(resolve => {
onEvent = () => resolve(0);
addEventListener('em-libusb', onEvent);
timeoutId = setTimeout(resolve, timeout, -1);
});
} finally {
removeEventListener('em-libusb', onEvent);
clearTimeout(timeoutId);
}
});
每当 libusb 尝试报告事件(例如数据传输完成)时,都会使用 em_libusb_notify()
函数:
void usbi_signal_event(usbi_event_t *event)
{
uint64_t dummy = 1;
ssize_t r;
r = write(EVENT_WRITE_FD(event), &dummy, sizeof(dummy));
if (r != sizeof(dummy))
usbi_warn(NULL, "event write failed");
#ifdef __EMSCRIPTEN__
em_libusb_notify();
#endif
}
同时,em_libusb_wait()
部分用于在收到 em-libusb
事件或超时过期时从 Asyncify 休眠模式中“唤醒”:
double until_time = emscripten_get_now() + timeout_ms;
for (;;) {
// Emscripten `poll` ignores timeout param, but pass 0 explicitly just
// in case.
num_ready = poll(fds, nfds, 0);
if (num_ready != 0) break;
int timeout = until_time - emscripten_get_now();
if (timeout <= 0) break;
int result = em_libusb_wait(timeout);
if (result != 0) break;
}
由于休眠和唤醒次数显著减少,此机制修复了之前基于 emscripten_sleep()
的实现的效率问题,并将 DSLR 演示吞吐量从 13-14 FPS 提高到 30+ FPS,足以实现流畅的实时 Feed。
构建系统和首个测试
后端完成后,我必须将其添加到 Makefile.am
和 configure.ac
。这里唯一有趣的一点是特定于 Emscripten 的标志修改:
emscripten)
AC_SUBST(EXEEXT, [.html])
# Note: LT_LDFLAGS is not enough here because we need link flags for executable.
AM_LDFLAGS="${AM_LDFLAGS} --bind -s ASYNCIFY -s ASSERTIONS -s ALLOW_MEMORY_GROWTH -s INVOKE_RUN=0 -s EXPORTED_RUNTIME_METHODS=['callMain']"
;;
首先,Unix 平台上的可执行文件通常没有文件扩展名。但是,Escripten 会根据您请求的扩展程序生成不同的输出。我使用 AC_SUBST(EXEEXT, …)
将可执行扩展程序更改为 .html
,以便软件包中的任何可执行文件(测试和示例)都能成为 HTML,并使用 Emscripten 的默认 shell(负责加载和实例化 JavaScript 和 WebAssembly)。
其次,由于我正在使用 Embind 和 Asyncify,我需要启用这些功能 (--bind -s ASYNCIFY
),以及通过链接器参数允许动态内存增长 (-s ALLOW_MEMORY_GROWTH
)。遗憾的是,库无法向链接器报告这些标记,因此每个使用此 libusb 端口的应用都必须将相同的链接器标记添加到其构建配置中。
最后,如前所述,WebUSB 需要通过用户手势完成设备枚举。libusb 示例和测试假定它们可以在启动时枚举设备,并在不做任何更改的情况下失败并报错。因此,我不得不停用自动执行功能 (-s INVOKE_RUN=0
),并采用手动 callMain()
方法 (-s EXPORTED_RUNTIME_METHODS=...
)。
完成上述所有操作后,我就可以使用静态网络服务器提供生成的文件、初始化 WebUSB,并借助开发者工具手动运行这些 HTML 可执行文件。
看起来没什么大不了的,但是,在将库移植到新平台时,能够首次生成有效输出的阶段是非常令人兴奋的!
使用端口
如上文所述,端口依赖于一些目前需要在应用的关联阶段启用的 Emscripten 功能。如果您想在自己的应用中使用此 libusb 端口,则需要执行以下操作:
- 下载最新的 libusb,并将其作为 build 的一部分归档,或将其作为 git 子模块添加到项目中。
- 在
libusb
文件夹中运行autoreconf -fiv
。 - 运行
emconfigure ./configure –host=wasm32 –prefix=/some/installation/path
以初始化项目以进行交叉编译,并设置要将构建后的工件放入哪个路径。 - 运行
emmake make install
。 - 指向您的应用或更高级别的库,以在先前选择的路径下搜索 libusb。
- 将以下标志添加到应用的链接参数中:
--bind -s ASYNCIFY -s ALLOW_MEMORY_GROWTH
。
该库目前存在一些限制:
- 不支持取消转移。这是 WebUSB 的限制,而 libusb 本身缺少跨平台传输取消功能。
- 不支持等时传输。按照现有传输模式的实现作为示例来添加该模式应该不难,但这也是一种比较少见的模式,我没有任何设备可以测试它,因此目前我仍不支持该模式。如果您有此类设备,并且希望为图书馆做贡献,欢迎您提供相关支持!
- 前面提到了跨平台限制。这些限制是由操作系统施加的,因此除了要求用户替换驱动程序或权限外,我们在这里无法做很多事情。但是,如果要移植 HID 或串行设备,您可以按照 libusb 示例进行操作,并将一些其他库移植到另一个 Fugu API。例如,您可以将 C 库 hidapi 移植到 WebHID,并避免所有与低层级 USB 访问相关的问题。
总结
在这篇博文中,我展示了如何借助 Emscripten、Asyncify API 和 Fugu API,利用一些集成技巧将 libusb 等低级库移植到 Web 中。
移植如此基本且广泛使用的低级别库尤其值得关注,因为反过来,这也有助于将更高级别的库甚至整个应用引入到 Web 中。由此带来的体验将以前局限于一两个平台的用户以及各类设备和操作系统开放,只需点击一下链接就能获得这些体验。
在下一篇博文中,我将详细介绍构建 Web gPhoto2 演示所涉及的步骤,该演示不仅会检索设备信息,还会广泛使用 libusb 的传输功能。同时,我希望 libusb 示例很鼓舞人心,并且愿意尝试演示、使用库本身,或者甚至将另一个广泛使用的库也移植到其中一个 Fugu API 中。