了解如何使用 WebAssembly 和 Fugu API 将与外部设备交互的代码移植到 Web 中。
在之前的一篇博文中,我展示了如何使用 File System Access API、WebAssembly 和 Asyncify 将使用文件系统 API 的应用移植到 Web 端。现在,我想继续介绍将 Fugu API 与 WebAssembly 集成以及在不丢失重要功能的情况下将应用移植到 Web 的相同主题。
我会展示如何通过将 libusb(用 C 语言编写的常用 USB 库)移植到 WebAssembly(通过 Emscripten)、Asyncify 和 WebUSB 将与 USB 设备通信的应用移植到网络。
当务之急:演示
在移植库时,要做的最重要的事情是选择合适的演示,这种演示可以展示已移植的库的功能,使您能够通过多种方式对其进行测试,同时在视觉上具有吸引力。
我当时的想法是 DSLR 遥控器。值得一提的是,开源项目 gPhoto2 在这个领域已经存在足够长的时间,能够进行逆向工程,并实现对各种数码相机的支持。它支持多种协议,但我最感兴趣的协议是通过 libusb 执行的 USB 支持。
我将分两部分介绍构建此演示的步骤。在这篇博文中,我将介绍如何移植 libusb 本身,以及将其他热门库移植到 Fugu API 的技巧。在第二篇博文中,我将详细介绍如何移植和集成 gPhoto2。
最后,我构建了一个正常运行的 Web 应用,它可以预览数码单反相机中的实时 Feed 并通过 USB 控制其设置。在了解技术详情之前,您可以随意观看直播或预先录制的演示:
<ph type="x-smartling-placeholder">关于相机特定怪异的注意事项
您可能已经注意到,更改设置需要一段时间。与您可能遇到的大多数其他问题一样,这并非由 WebAssembly 或 WebUSB 的性能导致,而是由 gPhoto2 与为演示选择的特定相机交互的方式。
Sony a6600 不提供直接设置 ISO、光圈或快门速度等值的 API,而是仅提供按指定步数增加或减少值的命令。让情况变得更加复杂:它也不会返回实际支持值的列表,返回的列表似乎在许多索尼相机型号中进行了硬编码。
设置其中某个值时,gPhoto2 没有其他选择,只能:
- 朝所选值的方向迈步(几步)。
- 稍等片刻,等待相机更新设置。
- 读回相机实际着陆的值。
- 检查最后一步,确保没有跳过所需的值,也没有位于列表的末尾或开头。
- 重复。
这可能需要一些时间,但如果相机实际支持该值,该值就会到达,如果不支持,则会停止在最接近的支持值处。
其他摄像头可能会有一组不同的设置、底层 API 和怪异。请注意,gPhoto2 是一个开源项目,对现有的所有相机模型进行自动或手动测试根本不可行,因此欢迎您随时提交详细的问题报告和 PR(但请务必先通过官方 gPhoto2 客户端重现问题)。
关于跨平台兼容性的重要说明
遗憾的是,在 Windows 上,任何“已知”设备(包括数码单反相机)会分配到与 WebUSB 不兼容的系统驱动程序。如果您想在 Windows 上试用此演示版,则必须使用 Zadig 等工具将连接的 DSLR 的驱动程序替换为 WinUSB 或 libusb。这种方法对我和许多其他用户都很有效,但您应自行承担使用风险。
在 Linux 上,您可能需要设置自定义权限才能允许通过 WebUSB 访问您的数码单反相机,不过这取决于您的发行版。
在 macOS 和 Android 上,该演示应该可以直接使用。如果您正在 Android 手机上试用此功能,请务必切换到横屏模式,因为我没有太多精力打造自适应模式(欢迎公关!):
<ph type="x-smartling-placeholder">![Android 手机通过 USB-C 数据线连接到 Canon 相机。](https://web.developers.google.cn/static/articles/porting-libusb-to-webusb/image/android-phone-connected-5bc06721b5e43.jpg?authuser=7&hl=ro)
如需关于跨平台使用 WebUSB 的更深入的指南,请参阅“针对具体平台的注意事项”“构建支持 WebUSB 的设备”部分。
向 libusb 添加新后端
现在我们来了解技术细节。虽然可以提供类似于 libusb 的 shim API(之前已由其他人进行过)并将其他应用链接到该 API,但这种方法容易出错,并且会使进一步的扩展或维护更加困难。我想用正确的方式,以便日后向上游贡献并合并到 libusb 中。
幸运的是,libusb 自述文件中显示了以下内容:
“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 上的代码和注释。
将事件循环移植到网页中
我想讨论的另外一个 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()
以检查后端是否已报告任何事件。如果有,循环停止。否则,Emscripten 的poll()
实现将立即返回0
。 - 调用
emscripten_sleep(0)
。此函数在后台使用 Asyncify 和setTimeout()
,并且在这里用于将控制权交还给主浏览器事件循环。这样,浏览器就可以处理任何用户互动和 I/O 事件,包括 WebUSB。 - 检查指定的超时是否到期,如果没有,继续循环。
正如评论中提到的,这种方法并不是最优的,因为即使没有 USB 事件需要处理(大多数时候),它也一直使用 Asyncify 来节省和恢复整个调用堆栈,并且 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()
的实现的效率问题,并将数码单反演示吞吐量从 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 平台上的可执行文件通常没有文件扩展名。不过,Emscripten 会生成不同的输出,具体取决于您请求的扩展程序。我使用 AC_SUBST(EXEEXT, …)
将可执行扩展程序更改为 .html
,以便软件包中的任何可执行文件(测试和示例)都成为采用 Emscripten 的默认 shell(负责加载和实例化 JavaScript 和 WebAssembly)的 HTML。
其次,由于我使用的是 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 本身缺少跨平台传输取消功能。
- 不支持等时传输。通过以现有传输模式的实现为例,添加它应该并不困难,但它也是一种罕见的模式,我没有任何设备进行测试,因此目前我仍将其保留为不受支持状态。如果您有此类设备,并且希望为库做贡献,欢迎 PR!
- 前面提到了跨平台限制。这些限制是由操作系统施加的,除了要求用户覆盖驱动程序或权限之外,我们在这里能做的不多。不过,如果您要移植 HID 或串行设备,则可以按照 libusb 示例,将一些其他库移植到另一个 Fugu API。例如,您可以将 C 库 hidapi 移植到 WebHID,并回避与低级别 USB 访问相关的问题。
总结
在这篇博文中,我展示了如何在 Emscripten、Asyncify 和 Fugu API 的帮助下,通过一些集成技巧,甚至像 libusb 这样的低级库移植到网络。
移植如此广泛且必不可少的低级别库特别有用,因为这反过来又可以将更高级别的库甚至整个应用引入 Web 中。这种体验以前只能面向一两个平台的用户、各类设备和操作系统开放,现在只需点击链接即可使用。
在下一篇博文中,我将详细介绍构建网络 gPhoto2 演示所需的步骤。该演示不仅会检索设备信息,还会广泛使用 libusb 的传输功能。同时,希望您能从 libusb 示例中获得启发,并尝试该演示、试用该库本身,或者将另一个广泛使用的库移植到其中一个 Fugu API 中。