ARTICLE · 1388511
Android源码第二十二章:USB、Vibrator 与 Lights——外设怎么动?
插上 USB 外设,系统弹出了授权框。点了「允许」,应用却还是收不到一个字节。桌上转接器的蓝灯亮着,应用仍要打开设备、占用接口,才能试着往端点发数据。外设能回出你刚发的那几个字节,这一笔才有来有回。

1. 先发一笔能认出来的数据
Android 作为 USB Host 时,负责枚举外设、为传输排队并发起总线事务。设备可以有多个配置和接口。接口把一种设备功能组织起来,端点是这项功能用来收发数据的地址。从 Host 看,IN 表示设备到 Android,OUT 表示 Android 到设备。Bulk 有错误检测和重试,调度用的是总线剩余带宽,接口本身没有固定延迟保证。Control 走默认控制端点 EP0,常用于查状态和配置。
插画停在转接器。跟做回显时,还要在转接器的另一端接上自有 Linux 测试板。把单一接口的两个 Bulk 端点找出来,先送一笔标准 GET_STATUS,再在工作线程经 OUT 发四字节,经 IN 等测试板送回。只拿返回值来说,GET_STATUS=2 与 OUT=4 已经是两类不同证据。两端日志里的随机四字节也一致,才算这一轮回显完成。 下面摘录完整示例的四次关键调用,省去各次失败检查。传输成功时返回字节数,接口占用返回布尔值。变量查找、授权、超时和释放见第 8 节。 Android USB Host API · UsbDeviceConnection
int ctrl = connection.controlTransfer(0x80, 0, 0, 0, statusBytes, 2, 1500);claimed = connection.claimInterface(intf, false);int sent = connection.bulkTransfer(out, token, token.length, 1500);int n = connection.bulkTransfer(in, response, received, response.length - received, (int) remaining);
能收发数据以后,还可以问谁决定手机当 Host。换角色、振动和电池灯都在图里,但各有自己的入口和观察结果。这些结果各有来源,USB 返回字节,端口报新状态,振动和灯状态则要继续看各自的后端。
2. 先看全局,再沿一个请求走
2.1 整体架构

USB Host 这一列有两条线。fd 是进程文件描述符表中的整数编号。PFD 是 Android 的 ParcelFileDescriptor,用来持有和传递文件描述符。UsbManager 通过 Binder 查设备、申请权限和打开节点,UsbDeviceConnection 拿到 fd 后在应用进程调用 JNI。 裸 USB 的 Control 和 Bulk 不经过端口 IUsb HAL。USB 角色管理才通过 IUsb 配置 Type-C。图中 xHCI、Type-C TCPM、振动参考驱动和 Cuttlefish 虚拟 Lights 分别代表可核对的实现,不能拿其中一列推断另外几列也部署在同一台设备。
2.2 全章时序

图的前半段可当作 USB 排障顺序。先确认枚举,等授权结果,打开后再看工作线程里的 Control 和 Bulk。一次传输结束后,应用释放本轮占用的接口并关闭连接。后半段的三个场景分别由端口管理请求、应用振动请求和系统电池状态触发,彼此没有先后依赖。
3. 枚举与授权发生在打开之前
3.1 USB 节点先进入 UsbHostManager
遇到一个外设,Linux 主机先在 hub 层枚举、分配设备号并登记设备,随后 Android 的 ueventd 处理设备事件并为 usbfs 准备 /dev/bus/usb/BBB/DDD 节点。Android 的 UsbService host thread 在 UsbHostManager 启动,进入 JNI 的 monitorUsbHostBus()。usb_host_run() 先用 inotify 监听,再扫描已有节点。它能收到新插入的设备,也能发现服务启动之前已经存在的节点。Native 打开节点读取描述符,把地址、类信息和原始描述符交给 usbDeviceAdded()。Java 侧按限制和描述符建出 UsbDevice,并记录设备指纹。 Linux 枚举 · Android 节点处理 · Host 线程与枚举 · Native 枚举回调 · inotify 与初扫
// com_android_server_UsbHostManager.cpp,保留监听入口。static void android_server_UsbHostManager_monitorUsbHostBus(JNIEnv*, jobject thiz) { struct usb_host_context* context = usb_host_init(); if (!context) return; usb_host_run(context, usb_device_added, usb_device_removed, nullptr, (void*)thiz);}
应用的 getDeviceList() 读的是 Framework 已经登记的设备快照。 新节点出现和 Framework 登记之间有一个时序窗口。开启 Host 授权功能的配置还会过滤未获得系统 Host 授权的条目,应用对单个设备的授权仍要另外检查。列表为空时,先查当前数据角色、OTG 或透传能力,以及设备是否进入系统的过滤范围。能列出来只说明 UsbDevice 已经建立。
3.2 授权回调交回设备,应用再复核权限
UsbManager.requestPermission() 将设备、包名和 PendingIntent 经 IUsbManager 交给 UsbService。每用户权限管理器先按实际调用者复核。已有权限可直接发送结果。需要弹窗时转到 SystemUI,允许后 SystemUI 先登记授权,再回送 EXTRA_DEVICE 与 EXTRA_PERMISSION_GRANTED。示例的广播接收器在应用主线程收到结果,再用 hasPermission() 检查一遍,才把传输交给工作线程。应用主动申请的是当前连接的临时访问,设备拔掉时服务会清理临时记录。相机类设备还有应用相机权限等限制。 请求分支 · SystemUI 授权 · 回填结果
// UsbUserPermissionManager.requestPermission(),压缩为本实验的普通 USB 设备分支。if (hasPermission(device, fingerprint, packageName, pid, uid)) { intent.putExtra(UsbManager.EXTRA_DEVICE, device); intent.putExtra(UsbManager.EXTRA_PERMISSION_GRANTED, true); pi.send(mContext, 0, intent); // 省略 CanceledException 的处理 return;}// 已按设备类别检查额外权限后,再请求用户确认。requestPermissionDialog(device, null, mUsbUserSettingsManager.canBeDefault(device, packageName), packageName, pi, uid);
示例读取系统回填的字段,因此使用限定到本包、随机 action、单次使用的可变 PendingIntent。Android 13 及以上动态接收器注册为不对其他应用导出。广播里报「允许」之后,仍可能刚好拔线。 服务端打开时会再按当前设备和调用者检查,所以这里还要处理 openDevice() == null。 PendingIntent 回填分支 · 打开时复验
4. Binder 交出 fd,应用自己向 Linux 传输
4.1 一次打开,沿途各有关闭责任
系统服务通过设备地址从 mDevices 查出对象和指纹,核对访问权限后进入 nativeOpenDevice()。服务 JNI 用 libusbhost 打开节点,先 dup() 出供返回使用的 fd,再关闭最初的 usb_device。它把保留下来的 fd 包成 ParcelFileDescriptor。Binder 先取得源 fd 指向的文件引用,再把引用安装到接收进程的 fd 表,接收端的 fd 编号由自己的表分配。这次 Binder 返回值的标志会让服务端 PFD 在写入 Parcel 后关闭自身的副本。 服务端检查 · 服务 JNI 返回 PFD · Binder 取得文件引用 · 接收端安装 fd · PFD 的返回值标志
// com_android_server_UsbHostManager.cpp,非空 device 和有效 fd 的成功分支。int fd = usb_device_get_fd(device);int newFD = dup(fd);usb_device_close(device);jobject fileDescriptor = jniCreateFileDescriptor(env, newFD);// 省略 fileDescriptor 创建失败时的清理。return env->NewObject(gParcelFileDescriptorOffsets.mClass, gParcelFileDescriptorOffsets.mConstructor, fileDescriptor);
在 App 端,回复 Parcel 先管理 Binder 安装的 fd,反序列化再为临时 PFD 复制一份。UsbManager.openDevice() 拿到这个 PFD 后创建 Java UsbDeviceConnection。JNI 在应用内再次复制 fd,usb_device_new() 把这个 fd 存到应用自己的 Native 对象。Java 调用返回前会关闭临时 PFD,连接继续持有新 fd。把 getFileDescriptor() 给 Native 库用时,它是借出的整数,连接关闭后它不能继续代表那个设备。 Parcel 读出 PFD 的独立 fd · 客户端 openDevice · App JNI 新建与关闭
// android_hardware_UsbDeviceConnection_open(),App JNI。int fd = jniGetFDFromFileDescriptor(env, fileDescriptor);fd = fcntl(fd, F_DUPFD_CLOEXEC, 0);if (fd < 0) return JNI_FALSE;// deviceNameStr 由同方法对 Java 字符串取值。struct usb_device* device = usb_device_new(deviceNameStr, fd);if (device) env->SetLongField(thiz, field_context, (jlong)device);else close(fd);

左边是打开时传递的文件引用。右边每一笔 I/O 使用的是应用长期持有的 fd,Java 数组、JNI 缓冲区和内核传输缓冲区各自有独立职责。服务交付的是经过授权的文件引用。传输时的业务字节从 App 直接进入 Linux。
4.2 Control 和 Bulk 用同一个 fd,各给内核一组参数
UsbDeviceConnection 的 Java 方法先检查数组范围。App JNI 在调用者线程进入 libusbhost。Control 把方向、请求、wValue、wIndex 和长度装进 USBDEVFS_CONTROL 的参数结构。Bulk 则传端点地址、缓冲区、长度和超时。IN 的应用数组由 JNI 在读成功后按实际字节数写回,OUT 的应用数组先复制到 JNI 传入的缓冲区。 Java Control 与 Bulk · JNI Bulk 参数与拷贝 · libusbhost 的两个 ioctl
// libusbhost/usbhost.c,usb_device_bulk_transfer()。struct usbdevfs_bulktransfer ctrl;memset(&ctrl, 0, sizeof(ctrl));ctrl.ep = endpoint;ctrl.len = length;ctrl.data = buffer;ctrl.timeout = timeout;return ioctl(device->fd, USBDEVFS_BULK, &ctrl);
ioctl 是用户态通过打开的文件向驱动发命令的系统调用。这里的命令告诉 usbfs 要做哪类 USB 事务,参数说明本次请求的端点、缓冲区和超时。设备接口被占用时,claimInterface(intf, false) 可以失败。示例保持 false,避免分离系统已经绑定的驱动。若只做标准设备级 GET_STATUS,请求对象是设备本身,示例在占用数据接口之前发出。
4.3 Linux 等 URB 完成,原工作线程才拿到结果
usbdev_ioctl 按 USBDEVFS_CONTROL 或 USBDEVFS_BULK 分发。Control 走 EP0 的 setup,Bulk 校验寻址和接口后准备数据缓冲区。两条同步路径最终交给 usbfs_start_wait_urb()。URB(USB Request Block) 是 Linux USB 栈表示一次传输的请求对象,里面有 pipe、缓冲区、实际长度、状态和完成函数。 usbfs ioctl · EP0 请求 · Bulk 校验、缓冲与写回
// drivers/usb/core/devio.c,usbfs_start_wait_urb() 的核心动作。DECLARE_COMPLETION_ONSTACK(ctx);urb->context = &ctx;urb->complete = usbfs_blocking_completion;rc = usb_submit_urb(urb, GFP_KERNEL);if (unlikely(rc)) return rc;expire = timeout ? msecs_to_jiffies(timeout) : MAX_SCHEDULE_TIMEOUT;rc = wait_for_completion_killable_timeout(&ctx, expire);if (rc <= 0) usb_kill_urb(urb); // 节选,后续根据完成竞争处理状态。
Host Controller Driver 通过 .urb_enqueue 接手。以 xHCI 为例,xhci_urb_enqueue() 把 Control 或 Bulk 转成控制器能读的传输描述符(TRB),放入传输环,再写门铃寄存器提醒控制器取走。总线事务结束后,中断处理读取 Transfer Event,把完成的 URB 交回 USB 栈。usbfs 的完成函数这时才唤醒等结果的线程。 HCD 入队和回调 · xHCI 入队 · TRB 与门铃 · IRQ 与回交
Bulk IN 成功后,收到的字节从内核拷到 JNI,再按返回长度写回 Java 数组。等待超时或被中断时,usbfs 会尝试取消尚未完成的 URB。如果取消前事务刚好完成,就按实际状态返回。Java 公共接口的负值表示失败,无法单独用来还原内核的具体错误码。 usbfs 等待的成功与失败路径
4.4 热拔插不会替应用把长连接关好
拔线后 usbfs 的新请求可能失败,阻塞中的传输也可能被终止。Android 的 USB 枚举监听移除对应登记项并清理临时授权。USB 设备生命期与 App 连接句柄的生命期分开。 应用仍需释放成功 claim 的接口并关连接。若业务在长时间接收,应监听拔出并将停止安排到同一 I/O 执行路径,避免关闭与一次调用争抢。示例用有限超时和 finally 收尾。异步传输可走 UsbRequest.queue() 和 requestWait(),USB 请求入队和等待结果须配套。 断开清理 · UsbRequest 文档

5. Type-C 换角色走另一条控制链
在「USB 偏好设置」看到「此设备控制 USB」,关注的是端口数据角色。数据角色是 Host 或 Device,电源角色是 Source 或 Sink。有些设备能独立切换,有些只能切换支持的组合。IUsb 负责端口配置与状态,Gadget HAL 另管 Android 作为设备时暴露哪些功能。 ADB、MTP 或 USB 网络的配置不等价于 Android Host 上的 Bulk。
系统入口 UsbPort.setRoles() 需要 MANAGE_USB,服务重查权限。端口管理器核对支持的组合,某些配置会改 port mode,支持独立切换时可分开交给 HAL;Framework 模拟端口只改变模拟状态。对于真实 AIDL 路径,UsbPortAidl 将目标包装成 PortRole 并带事务 ID。示例 USB HAL 的 switchRole() 将角色映射到 /sys/class/typec/<port>/data_role、power_role 或 port_type。非 mode 分支写入后还会读回比较。 权限入口 · 支持组合与切换分支 · AIDL 封装 · 参考 USB HAL
// Usb::switchRole(),参考 AIDL HAL 的非 mode 分支,节选步骤。fp = fopen(filename.c_str(), "w");if (fp != nullptr) { int ret = fputs(convertRoletoString(in_role).c_str(), fp); fclose(fp); if ((ret != EOF) && ReadFileToString(filename, &written)) { written = Trim(written); extractRole(&written); roleSwitch = (written == convertRoletoString(in_role)); }}// HAL 通过 notifyRoleSwitchStatus() 报结果,状态更新走另外的回调。
Linux Type-C class 的 data_role_store() 解析 sysfs 输入,校验端口可切换后调用 dr_set。启用 TCPM 的后端可进入 tcpm_dr_set(),受连接、PD 能力等条件约束。TCPM 的角色变更过程还会更新 mux 与 Type-C 状态。更下游是否连到 DWC3 等控制器,要看对应设备的 port/role-switch 注册和绑定。Framework 的 notifyRoleSwitchStatus() 只记录结果。供上层观察的端口变化由 notifyPortStatusChange() 走 Handler 更新状态。确认新数据角色要看新的端口状态。 要证明 Android 已能作为 Host 传输,还需重新枚举并实际收发。 Linux Type-C class · TCPM data role · Framework 状态回程
6. 振动完成和灯状态,各有自己的后端
6.1 VibratorManager 从效果走到驱动
应用用默认 Vibrator,提交一个 120 ms 的 VibrationEffect。应用需要 manifest 的 VIBRATE 权限。服务检查权限和策略,再安排对应会话和 VibrationThread。one-shot 的时长进入 VibratorController,由 HAL wrapper 选择可用路径。
谁负责报告完成,要看对应 HAL 的能力。当前 Framework 可按 flag 走旧 Native 管理器或新版 VintfHalVibrator。以新版分支为例,带 CAP_ON_CALLBACK 的 AIDL HAL 走 JNI 建立回调,身份由 vibratorId、vibrationId、stepId 串起。无该能力时,调用 on(ms, null) 成功后由 Framework 按时长安排回传。应用调用返回只是提交路径走完。系统判断结束、芯片完成和手摸到振动是三种不同的观察。 服务与分支 · VibrationThread · AIDL 能力和回调
特定设备怎么接到驱动?Pixel 7 Panther 的 Android 13 产品选用了 CS40L26 AIDL HAL。HAL 找到具备 EV_FF 能力的 /dev/input/event*,把时长写到周期 effect 的 replay.length,再用 EVIOCSFF 更新 effect。播放通过 write() 提交 EV_FF 输入事件,code 是 effect ID,value=1 表示开始。取消用同 ID 送 value=0。 Panther 产品配置 · HAL 更新 effect · 设备 ioctl 与写入
// Hardware.h,setFFEffect()。HAL 已准备 effect 与 timeoutMs。if (((*effect).replay.length != timeoutMs) || (ioctl(fd, EVIOCSFF, effect) < 0)) { return false;}return true;
更新成功后,HAL 调用另一个方法 setFFPlay()。这次写的是带 effect 编号的播放事件,evdev 从它区分开始和停止。
// Hardware.h,setFFPlay(),节选。struct input_event play = { .type = EV_FF, .code = static_cast<uint16_t>(index), .value = value,};return write(fd, (const void*)&play, sizeof(play)) == sizeof(play);
内核 evdev 和 input force feedback core 把请求分到驱动注册的 upload、playback。驱动的工作队列写 DSP 的时长与 mailbox,开始触觉输出。收到 DSP 完成消息后,驱动可以更新数字状态并通知 sysfs。参考 HAL 的异步任务等待 HAPTIC 和 STOPPED,然后调用 onComplete()。这份实现没有把 STOPPED 的轮询结果作为是否调用回调的条件。Framework 用会话和 step 标识接住完成并回收执行状态,普通应用的 vibrate() 没有这一层完成回调。 evdev · input FF · 驱动注册 · DSP 时长与触发 · 完成消息 · 状态通知 · HAL 等待和回调 · Framework 会话回程
这是本地 Framework 的 AIDL 入口与公开 Pixel 参考后端的接口对照。两边版本分开,具体芯片固件与真机配置未验证。像 Goldfish 这类采用 AIDL 示例振动 HAL 的配置,也可以通过软件计时收到完成事件。它不涉及 CS40L26 物理执行器。 示例 HAL 的计时完成
6.2 Lights 从系统电池策略走到虚拟灯更新
Android 框架的 BatteryService 根据电量和充电状态通过内部 LogicalLight 选择颜色或关灯。LightsService 维护逻辑灯和已请求的状态,把 HwLightState 传给 ILights.setLightState()。公开的 LightsManager 设备灯访问由 CONTROL_DEVICE_LIGHTS 保护,服务也不会把系统保留的 BATTERY 灯暴露给普通会话。示例 App 的「振动」按钮不会顺带控制这颗灯。 BatteryService 电池灯 · LightsService 与 HAL · 权限定义
// LightsService.java,AIDL 分支中的状态映射。HwLightState lightState = new HwLightState();lightState.color = color;lightState.flashMode = (byte) mode;lightState.flashOnMs = onMS;lightState.flashOffMs = offMS;lightState.brightnessMode = (byte) brightnessMode;mVintfLights.get().setLightState(mHwLight.id, lightState);
用 Cuttlefish 举例。在启用 lights server 的配置里,Guest HAL 提供一盏 BATTERY 型虚拟灯。它保存完整 HwLightState,但事件队列只投递 id、color、type。主机连上 Guest vsock 服务后先收到 START,随后收到按「4 字节小端长度 + JSON」封装的 UPDATE。采用标准 AF_VSOCK 的配置时,Guest 把发送包交给 virtio-vsock 的 TX virtqueue。Linux QEMU 的 vhost-vsock 后端取描述符、检查 CID,再送到 Host AF_VSOCK。
Host WebRTC observer 使用 Guest CID 和配置端口建立连接。活跃会话可把状态送到浏览器,前端这一版只有 console.debug。可见的实验终点是虚拟灯状态被上报,观察不到物理灯亮度。 要追真机 LED 和 PWM/I²C,需要从该机 HAL 使用的节点和内核绑定继续查。 Cuttlefish Lights HAL · Guest vsock 协议 · Host 开关和端口 · Guest 内核 transport · Host vhost-vsock · Host WebRTC · 浏览器消息处理
继续找其他外设可以从接口实际使用者入手。Consumer IR 看 ConsumerIrService.transmit() 选用的 HAL。串口看 SerialService.openSerialPort() 如何核对配置中的设备路径及返回 PFD。HDMI 的 CEC 控制由 HdmiCecController 的 HAL wrapper 发送消息,连接显示链还有另外的交接。找到产品所选实例或节点后,再往对应内核驱动查。 Consumer IR · 串口服务 · HDMI CEC
7. 跟做一次 USB 回显
7.1 先用普通应用看入口,再准备 USB 后端
Android Studio 新建 Java 的 Empty Views Activity,包名用 com.example.chapter22,minSdk 31,compileSdk 用 33 或更高。把第 8 节完整代码放进 app/src/main/java/com/example/chapter22/MainActivity.java,保留模板里的 Activity 声明。在 AndroidManifest.xml 的 <manifest> 内、<application> 外增加这两行。编译并运行,模拟器可先看能否取得 USB Host 功能以及振动请求日志。没有匹配外设时,界面给出缺设备提示,回显实验仍未开始。
<uses-feature android:name="android.hardware.usb.host" android:required="false" /><uses-permission android:name="android.permission.VIBRATE" />
回显需要能作为 USB Host 的 Android 真机,数据线与适配器,以及一块自己可控制、具备 UDC(USB Device Controller)的 Linux 测试板。也可用已经验证能把同一个 Gadget 转给 Android Guest 的环境,普通 Emulator 实例不能自动满足这一条件。使用无线 ADB 观测 Android,避免拿实验中的同一个 USB 口同时做调试和 Host。开发电脑上的 SERIAL 是 adb devices -l 看到的 Android 设备序列号。 getprop ro.build.fingerprint 与 uname -r 留作匹配镜像和内核的证据。设备 dumpsys 可先用下面的方式保存。
adb devices -lSERIAL='你的 Android adb 序列号'adb -s "$SERIAL" shell getprop ro.build.fingerprintadb -s "$SERIAL" shell uname -radb -s "$SERIAL" shell pm list features | rg 'android.hardware.usb.host'adb -s "$SERIAL" shell dumpsys usbadb -s "$SERIAL" logcat -v threadtime -s Chapter22:I
7.2 在专用 Gadget 板启动回显端
检查这块板的 UDC 可用且未被其他 Gadget 占用。已经通过 ConfigFS 或镜像配置启用其他外设模式的板,先确认其测试配置。先把第 8.2 节的脚本保存到测试板当前目录,在 Android 上装好应用并打开界面。以下命令在测试板本机终端运行。 g_serial use_acm=0 选择 generic serial 功能,预期 0525:a4a6 和 /dev/ttyGS0。默认的 ACM 选项有另一套接口结构。若 g_serial 已加载或内建,不能靠再运行 modprobe 改参数。先核实板端当前就是单端口 generic serial,在 Android 上确认 VID/PID 后再试。 Gadget Serial 文档 · 固定内核的 g_serial 配置
ls /sys/class/udcsudo modprobe g_serial use_acm=0 n_ports=1 && test -c /dev/ttyGS0
接线后,等 Android 的 dumpsys usb 或应用确认出现测试 Gadget,再在测试板启动回显脚本。节点检查失败时先修正测试板配置。
test -c /dev/ttyGS0 && sudo python3 ./外设回显.py /dev/ttyGS0
看到 ready 后,在 30 秒内点「USB GET_STATUS + 4 字节回显」。首次弹出授权框时,允许后本轮会自动发送。如果授权时脚本已经超时,重新启动回显脚本,再点一次按钮。每轮运行一个回显进程,保留完整的 Android 和测试板日志。设备上只连一个符合 ID 的测试外设。如果四字节没有匹配,先从失败所在阶段排查。
7.3 用判据区分卡在哪层
| GET_STATUS length=2 | ||
拔掉外设后重启一轮,观察列表是否更新、旧连接是否失败,以及重插后地址或授权是否需要重新取得。测试结束退出回显进程并拔线,只在本轮确实加载了专用板的 g_serial、并确认没有其他用途时卸载。不要对手机或日常工作板改 USB 角色、写 sysfs 或解除内核绑定来凑一份日志。
Vibrator 和 Lights 另做观察。按「振动 120 ms」后,保留日志并在匹配环境检查 adb shell dumpsys vibrator_manager,若设备服务名称有差异可先用 adb shell dumpsys -l 查。系统记录可以区分策略、设备能力与执行状态。触觉证据需要匹配硬件另测。Lights 在专用 Cuttlefish 上,先确认 ro.boot.vsock_lights_port 已配置,检查 adb shell dumpsys lights,打开本机 WebRTC 页面开发者控制台的 Verbose 日志,比对前后两轮 VIRTUAL_DEVICE_LIGHTS_UPDATE 消息的 id、light_type、color。没有启动 observer 或没有活跃会话时,浏览器无日志不构成失败。下面的 battery shell 操作只用于测试实例,并会暂时覆盖系统读取的电池状态。
adb devices -lCF_SERIAL='你的 Cuttlefish adb 序列号'adb -s "$CF_SERIAL" shell dumpsys lightsadb -s "$CF_SERIAL" shell dumpsys batteryadb -s "$CF_SERIAL" shell getprop ro.boot.vsock_lights_port# 在专用无既有电池覆盖的测试实例上固定电量,实验后恢复硬件输入。adb -s "$CF_SERIAL" shell cmd battery unplugadb -s "$CF_SERIAL" shell cmd battery set level 50adb -s "$CF_SERIAL" shell cmd battery set status 2# 将充电灯作为对照起点,再观察放电时的变化。adb -s "$CF_SERIAL" shell cmd battery set status 3# 记录浏览器状态后再执行下一条。adb -s "$CF_SERIAL" shell cmd battery set status 2adb -s "$CF_SERIAL" shell dumpsys lights# 留下第二次浏览器状态,随后恢复本轮改变的电池输入。adb -s "$CF_SERIAL" shell cmd battery reset
这里的 status 3 是放电,2 是充电。用固定电量对照两次状态,根据当前产品策略预期颜色有变化。LightsService 可能跳过相同状态,浏览器刚连接还可能先收到观察端缓存。以执行两次切换后同一灯 ID 的两种实际颜色为准。 相同灯状态的过滤
如果 dumpsys lights 没有 BATTERY 类型,先核对产品和 HAL 服务实例。这组示例做了 SDK 静态编译,未在实体 Android 设备、Gadget 板或 Cuttlefish 上实跑。 Android Framework、参考 HAL 和 Kernel 的固定来源见下文,设备驱动和固件须再与自己的构建对应。
8. 完整示例
8.1 Android 应用
MainActivity 把授权与 UI 留在主线程,把 GET_STATUS、claim 和 Bulk 收发放到一条工作线程。日志先记设备地址和端点,OUT 返回时立刻记长度及本轮随机值。IN 按实际长度接续,失败记录已收字节,设备掉线或超时返回后仍会进入 finally。
package com.example.chapter22;import android.app.Activity;import android.app.PendingIntent;import android.content.BroadcastReceiver;import android.content.Context;import android.content.Intent;import android.content.IntentFilter;import android.content.pm.PackageManager;import android.hardware.usb.UsbConstants;import android.hardware.usb.UsbDevice;import android.hardware.usb.UsbDeviceConnection;import android.hardware.usb.UsbEndpoint;import android.hardware.usb.UsbInterface;import android.hardware.usb.UsbManager;import android.os.Build;import android.os.Bundle;import android.os.SystemClock;import android.os.VibrationEffect;import android.os.Vibrator;import android.os.VibratorManager;import android.util.Log;import android.widget.Button;import android.widget.LinearLayout;import android.widget.TextView;import java.security.SecureRandom;import java.util.Arrays;import java.util.Locale;import java.util.UUID;import java.util.concurrent.ExecutorService;import java.util.concurrent.Executors;public class MainActivity extends Activity { private static final String TAG = "Chapter22"; private static final int VID = 0x0525; private static final int PID = 0xa4a6; private final ExecutorService worker = Executors.newSingleThreadExecutor(); private final SecureRandom random = new SecureRandom(); private final String permissionAction = "com.example.chapter22.USB." + UUID.randomUUID(); private UsbManager usb; private String pendingAddress; private Button probe; private TextView status; private boolean destroyed; private final BroadcastReceiver permissionResult = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { if (!permissionAction.equals(intent.getAction()) || pendingAddress == null) return; UsbDevice result = readDevice(intent); String address = pendingAddress; pendingAddress = null; if (result == null || !address.equals(result.getDeviceName()) || !intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false) || !usb.hasPermission(result)) { finishProbe("permission denied, device detached, or invalid result"); return; } runProbe(result); } }; @SuppressWarnings("deprecation") private static UsbDevice readDevice(Intent intent) { if (Build.VERSION.SDK_INT >= 33) { return intent.getParcelableExtra(UsbManager.EXTRA_DEVICE, UsbDevice.class); } return intent.getParcelableExtra(UsbManager.EXTRA_DEVICE); } @Override protected void onCreate(Bundle state) { super.onCreate(state); usb = getSystemService(UsbManager.class); LinearLayout layout = new LinearLayout(this); layout.setOrientation(LinearLayout.VERTICAL); probe = new Button(this); probe.setText("USB GET_STATUS + 4 字节回显"); probe.setOnClickListener(v -> findAndRequest()); layout.addView(probe); Button vibration = new Button(this); vibration.setText("振动 120 ms"); vibration.setOnClickListener(v -> vibrateOnce()); layout.addView(vibration); status = new TextView(this); layout.addView(status); setContentView(layout); IntentFilter filter = new IntentFilter(permissionAction); if (Build.VERSION.SDK_INT >= 33) { registerReceiver(permissionResult, filter, Context.RECEIVER_NOT_EXPORTED); } else { registerReceiver(permissionResult, filter); } } private void findAndRequest() { if (usb == null || !getPackageManager().hasSystemFeature(PackageManager.FEATURE_USB_HOST)) { finishProbe("this device does not advertise USB Host"); return; } UsbDevice target = null; for (UsbDevice device : usb.getDeviceList().values()) { if (device.getVendorId() != VID || device.getProductId() != PID) continue; if (target != null) { finishProbe("connect only one matching test gadget"); return; } target = device; } if (target == null) { finishProbe("owned test gadget 0525:a4a6 not found"); return; } probe.setEnabled(false); if (usb.hasPermission(target)) { runProbe(target); } else { pendingAddress = target.getDeviceName(); Intent result = new Intent(permissionAction).setPackage(getPackageName()); PendingIntent callback = PendingIntent.getBroadcast(this, 0, result, PendingIntent.FLAG_MUTABLE | PendingIntent.FLAG_ONE_SHOT); try { usb.requestPermission(target, callback); } catch (RuntimeException error) { pendingAddress = null; callback.cancel(); finishProbe("request failed: " + error.getClass().getSimpleName()); } } } private void runProbe(UsbDevice device) { worker.execute(() -> { String result; try { result = exchange(device); } catch (RuntimeException error) { result = "transfer failed: " + error.getClass().getSimpleName(); } String message = result; runOnUiThread(() -> { if (!destroyed) finishProbe(message); }); }); } private String exchange(UsbDevice device) { if (device.getInterfaceCount() != 1 || device.getConfigurationCount() != 1) { return "expected a single-interface gadget"; } UsbInterface intf = device.getInterface(0); if (intf.getAlternateSetting() != 0 || intf.getEndpointCount() != 2) { return "expected alternate 0 with one bulk IN and one bulk OUT"; } UsbEndpoint in = null; UsbEndpoint out = null; for (int i = 0; i < intf.getEndpointCount(); i++) { UsbEndpoint ep = intf.getEndpoint(i); if (ep.getType() != UsbConstants.USB_ENDPOINT_XFER_BULK) continue; if (ep.getDirection() == UsbConstants.USB_DIR_IN) in = ep; else out = ep; } if (in == null || out == null) return "bulk endpoint pair not found"; UsbDeviceConnection connection = usb.openDevice(device); if (connection == null) return "open failed after permission"; boolean claimed = false; try { byte[] statusBytes = new byte[2]; int ctrl = connection.controlTransfer(0x80, 0, 0, 0, statusBytes, 2, 1500); Log.i(TAG, "GET_STATUS length=" + ctrl); if (ctrl != statusBytes.length) return "GET_STATUS incomplete: " + ctrl; claimed = connection.claimInterface(intf, false); if (!claimed) return "interface busy or unavailable"; Log.i(TAG, String.format(Locale.ROOT, "device=%s interface=%d OUT=0x%02x IN=0x%02x", device.getDeviceName(), intf.getId(), out.getAddress(), in.getAddress())); byte[] token = new byte[4]; random.nextBytes(token); int sent = connection.bulkTransfer(out, token, token.length, 1500); Log.i(TAG, "OUT=" + sent + " tx=" + hex(token)); if (sent != token.length) return "OUT incomplete: " + sent; byte[] response = new byte[token.length]; long deadline = SystemClock.elapsedRealtime() + 3000; int received = 0; while (received < response.length) { long remaining = deadline - SystemClock.elapsedRealtime(); if (remaining <= 0) return "IN deadline after " + received + " bytes"; int n = connection.bulkTransfer(in, response, received, response.length - received, (int) remaining); if (n < 0) return "IN failed: " + n + " after " + received + " bytes"; received += n; } return "OUT=" + sent + " IN=" + received + " tx=" + hex(token) + " rx=" + hex(response) + " match=" + Arrays.equals(token, response); } finally { try { if (claimed) Log.i(TAG, "release=" + connection.releaseInterface(intf)); } finally { connection.close(); } } } private static String hex(byte[] bytes) { StringBuilder text = new StringBuilder(); for (byte b : bytes) text.append(String.format(Locale.ROOT, "%02x", b & 0xff)); return text.toString(); } private void vibrateOnce() { Vibrator vibrator = getSystemService(VibratorManager.class).getDefaultVibrator(); if (!vibrator.hasVibrator()) { Log.i(TAG, "no default vibrator"); return; } vibrator.vibrate(VibrationEffect.createOneShot(120, VibrationEffect.DEFAULT_AMPLITUDE)); Log.i(TAG, "vibration requested: 120ms"); } private void finishProbe(String message) { probe.setEnabled(true); status.setText(message); Log.i(TAG, message); } @Override protected void onDestroy() { destroyed = true; unregisterReceiver(permissionResult); worker.shutdown(); super.onDestroy(); }}
8.2 Gadget 侧回显
脚本只在本轮接收四字节并原样写回,退出时恢复串口属性。重开进程再测下一轮,避免把上一轮残留数据当成本轮响应。
"""在专用 Linux USB Gadget 上,回送当前连接收到的四字节。"""import osimport selectorsimport sysimport termiosimport timeimport ttyfd = os.open(sys.argv[1], os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)previous = termios.tcgetattr(fd)try: tty.setraw(fd) with selectors.DefaultSelector() as poller: poller.register(fd, selectors.EVENT_READ) print("ready for 4 bytes", flush=True) deadline = time.monotonic() + 30 token = bytearray() while len(token) < 4: remaining = deadline - time.monotonic() if remaining <= 0 or not poller.select(remaining): raise TimeoutError("no complete token; start a fresh run") try: chunk = os.read(fd, 4 - len(token)) except BlockingIOError: continue if not chunk: raise EOFError("USB serial disconnected") token.extend(chunk) poller.modify(fd, selectors.EVENT_WRITE) remaining = deadline - time.monotonic() if remaining <= 0 or not poller.select(remaining): raise TimeoutError("gadget output unavailable") if os.write(fd, token) != len(token): raise IOError("short write; start a fresh run") print("echo=" + token.hex(), flush=True)finally: try: termios.tcsetattr(fd, termios.TCSANOW, previous) finally: os.close(fd)
9. 回到那个亮着的灯
再看到转接器亮着,先翻这次传输的日志。确认设备地址和端点,再把 Android 的 tx、rx 和板端的 echo 对上。如果四字节一致,才有本轮数据走完的证据。换角色、振动和灯也有各自的观察终点,分别去看端口新状态、触觉输出和后端收到的灯状态。
参考资料
• Android USB Host 实操
• UsbDeviceConnection API
• Android USB HAL
• Linux Gadget Serial
• AOSP UsbHostManager.openDevice
• App UsbDeviceConnection JNI
• Linux usbfs 的 URB 同步等待
• AOSP AIDL USB 端口实现
• 振动 HAL 接口
• Cuttlefish Lights HAL
• 完整 Android 示例
• Linux Gadget 回显脚本














































































