了解如何使用 WebAssembly 和 Fugu API 将与外部设备交互的代码移植到 Web 上。
在之前的一篇博文中,我展示了如何使用 File System Access API、WebAssembly 和 Asyncify 将使用文件系统 API 的应用移植到 Web 端。现在,我想继续探讨同一主题,即将 Fugu API 与 WebAssembly 集成,并在不丢失重要功能的情况下将应用移植到 Web 上。
我将介绍如何通过将 libusb(一种用 C 语言编写的热门 USB 库)移植到 WebAssembly(通过 Emscripten)、Asyncify 和 WebUSB,将与 USB 设备通信的应用移植到 Web 平台。
先解决重点问题:演示
在移植库时,要做的最重要的事情是选择合适的演示,这种演示可以展示已移植的库的功能,使您能够通过多种方式对其进行测试,同时在视觉上具有吸引力。
我选择的方案是数码单反遥控器。特别是,开源项目 gPhoto2 已在此领域深耕多年,能够对各种数字相机进行逆向工程并实现对它们的支持。它支持多种协议,但我最感兴趣的是 USB 支持,它通过 libusb 执行此支持。
我将分两个部分介绍构建此演示的步骤。在本博文中,我将介绍如何移植 libusb 本身,以及可能需要使用哪些技巧才能将其他常用库移植到 Fugu API。在第二篇博文中,我将详细介绍如何移植和集成 gPhoto2。
最后,我得到了一个可用的 Web 应用,该应用可以预览来自 DSLR 的实时画面,并可以通过 USB 控制其设置。在了解技术细节之前,您可以随时观看直播或预录制的演示:
关于相机专用问题的说明
您可能已经注意到,视频中更改设置需要一段时间。与您可能遇到的大多数其他问题一样,这并非由 WebAssembly 或 WebUSB 的性能导致,而是由 gPhoto2 与为演示选择的特定相机交互的方式。
Sony a6600 未公开用于直接设置 ISO、光圈或快门速度等值的 API,而是仅提供按指定步数增减这些值的命令。让情况变得更加复杂:它也不会返回实际支持值的列表,返回的列表似乎在许多索尼相机型号中进行了硬编码。
设置其中某个值时,gPhoto2 没有其他选择,只能:
- 朝着所选值的方向迈出一步(或几步)。
- 稍等片刻,等待相机更新设置。
- 读回相机实际着陆的值。
- 检查上一步是否跳过了所需值,也未绕过列表的开头或结尾。
- 重复。
这可能需要一些时间,但如果相机实际支持该值,则会达到该值;如果不支持,则会在最接近的支持值处停止。
其他摄像头可能具有不同的设置、底层 API 和怪癖。请注意,gPhoto2 是一个开源项目,我们根本无法对所有摄像头型号进行自动或手动测试,因此我们非常欢迎您提供详细的问题报告和 PR(但请务必先使用官方 gPhoto2 客户端重现问题)。
关于跨平台兼容性的重要说明
遗憾的是,在 Windows 上,所有“众所周知”的设备(包括数码单反相机)都会分配一个系统驱动程序,该驱动程序与 WebUSB 不兼容。如果您想在 Windows 上试用此演示版,则必须使用 Zadig 等工具将连接的 DSLR 的驱动程序替换为 WinUSB 或 libusb。这种方法对我和许多其他用户都很有效,但您应自行承担使用风险。
在 Linux 上,您可能需要设置自定义权限,才能允许通过 WebUSB 访问您的 DSLR,但这取决于您的发行版本。
在 macOS 和 Android 上,该演示应该开箱即用。如果您正在 Android 手机上试用此功能,请务必切换到横屏模式,因为我没有太多精力打造自适应模式(欢迎公关!):
如需关于跨平台使用 WebUSB 的更深入的指南,请参阅“构建支持 WebUSB 的设备”中的“针对具体平台的注意事项”部分。
向 libusb 添加了新后端
接下来,我们来看看技术细节。虽然您可以提供类似于 libusb 的 shim 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
现在,需要一种处理异步 WebUSB API 的方法,因为 libusb 期望同步操作。为此,我可以使用 Asyncify,或者更具体地说,可以使用其通过 val::await()
进行的 Embind 集成。
我也想正确处理 WebUSB 错误并将其转换为 libusb 错误代码,但 Embind 目前无法处理来自 C++ 端的 JavaScript 异常或 Promise
拒绝情况。您可以通过在 JavaScript 端捕获拒绝并将结果转换为 { error, value }
对象来解决此问题,现在,您可以从 C++ 端安全地解析该对象。我通过结合使用 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
处理程序实现此操作。
难点在于,与其他平台不同,出于安全考虑,您无法在 Web 上枚举所有已连接的 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 源“轮询”(尝试读取数据或阻塞执行,直到有数据可用),并且当其中至少有一个源响应时,将其作为事件传递给相应的处理脚本。处理程序完成后,控件将返回到循环,并暂停以进行另一次轮询。
在网络上,这种方法存在几个问题。
首先,WebUSB 不会且无法公开底层设备的原始句柄,因此不能直接轮询这些句柄。其次,libusb 使用 eventfd
和 pipe
API 处理其他事件,以及在没有原始设备句柄的操作系统上处理传输,但 Emscripten 目前不支持 eventfd
,虽然 pipe
受支持,但目前不符合规范,无法等待事件。
最后,最大的问题是,Web 有自己的事件循环。此全局事件循环用于任何外部 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()
以检查后端是否已报告任何事件。如果有,循环会停止。否则,Emscripten 对poll()
的实现将立即返回0
。 - 调用
emscripten_sleep(0)
。此函数在后台使用 Asyncify 和setTimeout()
,并在这里用于将控制权交还给主浏览器事件循环。这样,浏览器便可以处理任何用户互动和 I/O 事件,包括 WebUSB。 - 检查指定的超时时间是否已过,如果未过,则继续循环。
正如评论中所提到的,这种方法并不理想,因为即使没有要处理的 USB 事件(大多数情况下),它也会一直使用 Asyncify 保存-恢复整个调用堆栈,并且 setTimeout()
本身在现代浏览器中的最短时长为 4 毫秒。不过,在概念验证中,它还是能很好地从 DSLR 生成 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,足以实现流畅的实时画面。
构建系统和第一个测试
后端完成后,我必须将其添加到 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 平台上的可执行文件通常没有文件扩展名。不过,Emscripten 会根据您请求的扩展程序生成不同的输出。我使用 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=...
)。
完成所有这些操作后,我就可以使用静态 Web 服务器提供生成的文件、初始化 WebUSB,并借助 DevTools 手动运行这些 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 本身缺少跨平台传输取消功能。
- 不支持等时传输。按照现有传输模式的实现作为示例,添加该模式应该不难,但它也是一种比较少见的模式,我没有任何设备可以用于对其进行测试,因此目前将其设为不受支持。如果您有此类设备,并且希望为该库做出贡献,欢迎提交 PR!
- 前面提到了跨平台限制。这些限制是由操作系统施加的,除了要求用户覆盖驱动程序或权限之外,我们在这里能做的不多。不过,如果您要移植 HID 或串行设备,则可以按照 libusb 示例,将一些其他库移植到另一个 Fugu API。例如,您可以将 C 库 hidapi 移植到 WebHID,从而完全避免与低级别 USB 访问相关的问题。
总结
在这篇博文中,我展示了如何在 Emscripten、Asyncify 和 Fugu API 的帮助下,通过一些集成技巧,甚至像 libusb 这样的低级库移植到网络。
移植如此广泛且必不可少的低级别库特别有用,因为这反过来又可以将更高级别的库甚至整个应用引入 Web 中。这种体验以前只能面向一两个平台的用户、各类设备和操作系统开放,现在只需点击链接即可使用。
在下一篇博文中,我将详细介绍构建网络 gPhoto2 演示所需的步骤。该演示不仅会检索设备信息,还会广泛使用 libusb 的传输功能。与此同时,希望 libusb 示例能给您带来启发,并希望您能试用演示版、玩转该库本身,甚至还能将另一个广泛使用的库移植到 Fugu API 之一。