1. AndroidAccessory 库概述AndroidAccessoryAA库是专为嵌入式微控制器设计的 USB 主机侧协议栈用于与运行 Android 系统的移动设备建立直接、免驱动的通信通道。该库并非标准 USB 类设备如 CDC ACM 或 HID而是基于 Google 在 Android 3.1Honeycomb MR1中引入的Android Open Accessory (AOA) 协议实现。AOA 协议的核心思想是将 Android 设备置于“配件模式”Accessory Mode由外部 MCU 作为 USB 主机发起控制Android 设备则降级为受控的 USB 设备——这一角色反转彻底规避了 Android 端对通用 USB 驱动的依赖使开发者无需 root、无需定制 ROM、无需安装 APK 即可实现双向数据交换。本库为原始 Arduino 官方AndroidAccessory库的深度修改版本Modified AndroidAccessory Library其工程价值在于在保留 AOA 协议兼容性的前提下剥离了 Arduino 框架强耦合重构为面向裸机Bare-metal与 RTOS如 FreeRTOS环境的可移植 C 模块同时强化了错误恢复机制、USB 描述符动态配置能力并显式支持 STM32F1/F4/H7 等主流 Cortex-M 平台的 HAL/LL 库集成路径。它不提供 Android 端 SDK仅专注 MCU 侧协议解析与状态机管理是构建工业手持终端、车载诊断仪、智能外设桥接器等场景的关键中间件。1.1 AOA 协议工作原理AOA 协议本质是建立在标准 USB 2.0 架构之上的应用层握手协议。其启动流程严格遵循以下六步时序初始枚举MCU 以默认 USB 设备身份接入 Android 手机VID0x18D1, PID0x2D00Android 内核识别为未知设备AOA 查询Android 端通过GET_PROTOCOL控制请求bRequest51查询设备是否支持 AOAMCU 必须返回协议版本v1.0 → 0x0100v2.0 → 0x0200描述符交换若支持Android 发送SEND_IDENTIFER请求bRequest52携带制造商名、型号名、描述、版本、URI、序列号共 6 个 UTF-8 字符串各≤255 字节模式切换触发Android 发送START_ACCESSORY请求bRequest53MCU 收到后必须立即断开 USB 连接物理复位或软件断连重枚举为配件MCU 重新上电/复位以新 VID/PID0x18D1/0x2D01和自定义字符串描述符再次枚举Android 内核识别为合法配件并加载android_accessory内核模块数据通道激活Android 为该设备创建/dev/usb_accessory节点APP 通过UsbManager.openAccessory()获取文件描述符后续通信走 Bulk IN/OUT 端点端点地址由描述符指定通常为 EP1 IN / EP2 OUT。此流程的关键工程约束在于步骤 4 的断连必须在 100ms 内完成否则 Android 端超时放弃且重枚举时的描述符字符串长度必须与步骤 3 中声明的完全一致否则内核拒绝加载。1.2 修改版库的核心增强点原始 Arduino 库存在三大工程缺陷硬编码字符串制造商/型号等字段写死于 Flash无法运行时配置无错误隔离USB 总线错误如 NAK、STALL导致状态机卡死阻塞式传输read()/write()直接轮询端点状态占用 CPU 且无法与 RTOS 任务协同。本修改版通过以下设计解决增强维度实现方案工程价值动态描述符提供aa_set_string_descriptor()API支持 RAM 中维护字符串缓冲区支持设备序列号绑定、固件版本透传、多型号共用 BIN状态机硬化引入AA_STATE_ERROR独立状态所有 USB 错误SETUP STALL、BULK TIMEOUT触发状态回退避免因手机热插拔、USB 线缆抖动导致永久离线非阻塞 I/Oaa_available()/aa_read()/aa_write()仅操作内部环形缓冲区底层由 USB ISR 填充/清空可安全在 FreeRTOS 任务中调用CPU 占用率 5%HAL 解耦USB 底层抽象为aa_usb_driver_t接口含init()/ep_write()/ep_read()等纯虚函数一行代码切换 STM32 HAL_USB_FS / LL_USB / GD32 USBFS2. 硬件接口与平台适配2.1 USB 物理层要求AOA 协议强制要求USB OTGOn-The-Go功能这意味着 MCU 必须具备双角色 USB PHY既可作 Device 也可作 HostID 引脚检测电路用于判别插入的是 A 型插头Host还是 B 型插头DeviceVBUS 供电管理AOA 模式下 MCU 为主机需向 Android 设备提供 5V500mA。典型合规芯片包括STM32F407VG内置 USB OTG FS PHYID 引脚为 PA9VBUS 检测引脚为 PA10STM32H743VI双 USB OTGFSHS支持硬件 OTG 协议栈NXP i.MX RT1064USB HS PHY 外置 USB3320 PHY 方案。⚠️ 注意STM32F103 等无原生 OTG 的芯片需外挂 USB PHY如 SMSC USB3317并自行实现 OTG 协议本库不提供此类方案支持。2.2 STM32 HAL 集成示例以 STM32F407 开发板为例HAL 层初始化关键代码如下// aa_hal_driver.c - USB 驱动适配层 #include AndroidAccessory.h #include usbd_core.h #include usbd_desc.h #include usbd_ctlreq.h static USBD_HandleTypeDef hUsbDeviceFS; static uint8_t usb_rx_buffer[64]; static uint8_t usb_tx_buffer[64]; // 实现 aa_usb_driver_t 接口 static const aa_usb_driver_t hal_usb_driver { .init hal_usb_init, .ep_write hal_usb_ep_write, .ep_read hal_usb_ep_read, .ep_stall hal_usb_ep_stall, .get_setup_packet hal_usb_get_setup_packet, }; static int hal_usb_init(void) { // 初始化 USB Device 外设非 HostAOA 初始阶段为 Device __HAL_RCC_USB_OTG_FS_CLK_ENABLE(); hUsbDeviceFS.pData NULL; hUsbDeviceFS.Instance USB_OTG_FS; hUsbDeviceFS.Init.dev_endpoints 4; hUsbDeviceFS.Init.speed USBD_SPEED_FULL; hUsbDeviceFS.Init.phy_itface USBD_PHY_EMBEDDED; if (USBD_Init(hUsbDeviceFS, FS_Desc, DEVICE_FS) ! USBD_OK) { return -1; } USBD_RegisterClass(hUsbDeviceFS, USBD_CUSTOM_CLASS); USBD_Start(hUsbDeviceFS); return 0; } static int hal_usb_ep_write(uint8_t ep_num, uint8_t *buf, uint16_t len) { return USBD_LL_Transmit(hUsbDeviceFS, ep_num, buf, len); } // ... 其他函数实现在main.c中注册驱动并启动int main(void) { HAL_Init(); SystemClock_Config(); // 注册 USB 驱动 aa_set_usb_driver(hal_usb_driver); // 配置 AOI 字符串运行时可变 aa_set_string_descriptor(AA_STRING_MANUFACTURER, Shenzhen Embedded Tech); aa_set_string_descriptor(AA_STRING_MODEL, SmartBridge v2.1); aa_set_string_descriptor(AA_STRING_DESCRIPTION, Industrial USB-AOA Bridge); // 启动 AndroidAccessory 状态机 aa_begin(); while (1) { aa_task(); // 必须周期性调用处理 USB 事件 HAL_Delay(1); // 1ms tick } }2.3 FreeRTOS 任务封装为适配实时系统推荐创建专用 USB 任务// FreeRTOS 任务函数 void usb_accessory_task(void const * argument) { aa_begin(); for(;;) { // 每毫秒执行一次状态机 aa_task(); // 检查是否有数据到达 if (aa_available() 0) { uint8_t buffer[64]; int len aa_read(buffer, sizeof(buffer)); if (len 0) { // 解析 Android 发来的命令例如 JSON 格式指令 parse_android_command(buffer, len); } } // 向 Android 发送传感器数据每 100ms 一次 if (xTaskGetTickCount() % 100 0) { uint8_t sensor_data[] {0x01, 0x23, 0x45, 0x67}; aa_write(sensor_data, sizeof(sensor_data)); } osDelay(1); } } // 创建任务 osThreadDef(usb_acc_task, usb_accessory_task, osPriorityNormal, 0, 256); osThreadCreate(osThread(usb_acc_task), NULL);3. 核心 API 详解3.1 状态机控制 API函数签名参数说明返回值典型调用时机void aa_begin(void)无参数初始化内部状态机、缓冲区、USB 驱动voidmain()中首次调用void aa_task(void)无参数执行单次状态机迭代处理 SETUP、IN/OUT 事务、错误恢复void必须在主循环或 RTOS 任务中周期调用aa_state_t aa_get_state(void)无参数返回当前状态AA_STATE_NONE,AA_STATE_IDLE,AA_STATE_ACCESSORY枚举值调试时检查连接状态int aa_is_connected(void)无参数等价于aa_get_state() AA_STATE_ACCESSORY0/1判断是否已进入配件模式状态流转图简化AA_STATE_NONE ↓ aa_begin() AA_STATE_IDLE → [收到 GET_PROTOCOL] → AA_STATE_WAITING_PROTOCOL ↓ [返回协议版本] AA_STATE_WAITING_IDENT → [收到 SEND_IDENT] → AA_STATE_WAITING_START ↓ [收到 START_ACCESSORY 断连重枚举] AA_STATE_ACCESSORY → [USB 数据收发] → 持续运行 ↓ [USB 总线错误] AA_STATE_ERROR → [自动尝试恢复] → AA_STATE_IDLE3.2 数据通信 API函数签名参数说明返回值注意事项int aa_available(void)无参数返回接收缓冲区中待读取字节数≥0非阻塞始终立即返回int aa_read(uint8_t *buf, int len)buf: 存储数据的缓冲区len: 最大读取长度实际读取字节数若len 缓冲区剩余数据只读取可用部分int aa_write(const uint8_t *buf, int len)buf: 待发送数据len: 数据长度实际写入字节数底层使用 DMA 时需确保buf地址 4 字节对齐void aa_flush(void)清空发送缓冲区丢弃未发出的数据void用于紧急中断数据流如设备复位前清理队列缓冲区设计细节接收缓冲区1024 字节环形缓冲区由 USB IN 端点 ISR 自动填充发送缓冲区512 字节环形缓冲区由aa_write()写入由 USB OUT 端点 ISR 自动提交缓冲区大小可通过#define AA_RX_BUFFER_SIZE 2048在AndroidAccessory.h中调整。3.3 描述符与配置 API函数签名参数说明返回值使用约束void aa_set_string_descriptor(uint8_t index, const char *str)index: 字符串索引AA_STRING_MANUFACTURER0,MODEL1...str: UTF-8 字符串void必须在aa_begin()前调用且str生命周期需持续有效void aa_set_protocol_version(uint16_t version)version: 协议版本0x0100或0x0200void默认为0x0100v2.0 支持音频通道但本库未实现void aa_set_endpoint_config(uint8_t in_ep, uint8_t out_ep, uint16_t max_packet)in_ep: Bulk IN 端点地址如0x81out_ep: Bulk OUT 端点地址如0x02max_packet: 最大包长通常 64void必须在aa_begin()前调用决定 USB 描述符内容字符串长度限制AOA 协议规定每个字符串最大 255 字节UTF-8 编码超出部分被截断。实际工程中建议控制在 64 字节内避免 Android 端解析异常。4. 典型应用场景与代码实例4.1 工业传感器数据透传场景STM32H7 采集温湿度传感器SHT30数据通过 AOA 实时上传至 Android APP。// 伪代码传感器采集与上报 void sensor_upload_task(void const * argument) { sht30_init(); // 初始化传感器 for(;;) { float temp, humi; if (sht30_read(temp, humi) 0) { // 构造二进制协议帧[TYPE:1B][TEMP:4B][HUMI:4B][CRC:2B] uint8_t frame[12]; frame[0] 0x01; // SENSOR_DATA memcpy(frame[1], temp, 4); memcpy(frame[5], humi, 4); uint16_t crc calculate_crc16(frame, 9); memcpy(frame[9], crc, 2); // 仅在已连接时发送 if (aa_is_connected()) { aa_write(frame, sizeof(frame)); } } osDelay(1000); // 每秒上报一次 } }Android 端 APP 可通过UsbAccessory的getInputStream()读取该二进制流无需任何权限声明。4.2 Android 指令控制外设场景Android APP 发送 LED 控制指令JSON 格式MCU 解析后驱动 GPIO。// 解析函数精简版 void parse_android_command(uint8_t *data, int len) { // 查找 JSON 起始位置跳过可能的乱码 char *json_start memchr(data, {, len); if (!json_start) return; // 解析 {led:on} 或 {led:off} cJSON *root cJSON_Parse(json_start); if (!root) return; cJSON *led_obj cJSON_GetObjectItem(root, led); if (led_obj led_obj-valuestring) { if (strcmp(led_obj-valuestring, on) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); } else if (strcmp(led_obj-valuestring, off) 0) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); } } cJSON_Delete(root); }此方案替代了传统蓝牙串口BLE UART方案规避了 Android 12 对BLUETOOTH_CONNECT权限的强制要求。4.3 固件升级桥接器利用 AOA 的高带宽理论 480Mbps实际约 20MB/s实现 Android APP 向 MCU 推送固件Android APP 将.bin文件分片每片 1024 字节添加序列号与 CRCMCU 接收后缓存至外部 SPI Flash收到{cmd:upgrade,crc:0xABCD}指令后校验整包 CRC校验通过则跳转至 Bootloader 执行擦写。此方案比 DFUDevice Firmware Upgrade更简单无需 USB DFU 类描述符无需特殊 Bootloader纯应用层协议。5. 故障排查与性能优化5.1 常见连接失败原因现象根本原因解决方案Android 无任何提示设备不识别MCU 未正确拉低 ID 引脚OTG 检测失败用万用表测量 ID 引脚电压确认为 0VA 型插头显示“USB 设备不受支持”VID/PID 不为0x18D1/0x2D00或0x18D1/0x2D01检查 USB 描述符中的idVendor/idProduct字段连接后立即断开循环重连SEND_IDENTIFER中字符串长度与实际不符使用aa_set_string_descriptor()后用strlen()验证长度 ≤255数据接收乱码Android 端未调用openAccessory()获取文件描述符确保 APP 在UsbManager.ACTION_USB_ACCESSORY_ATTACHED广播中响应5.2 性能调优关键点中断优先级USB IRQ 优先级必须高于其他外设如 UART、SPI建议设为NVIC_PRIORITYGROUP_4下的最高级0DMA 配置启用 USB PMAPacket Memory Area的双缓冲模式避免 IN/OUT 端点冲突缓冲区对齐aa_write()的buf参数地址需 4 字节对齐否则 HAL 层触发 HardFault时钟精度USB FS 要求 48MHz 时钟误差 ±0.25%必须使用 HSE外部晶振而非 HSI验证方法在aa_task()中添加计时戳若单次执行 500μs需检查是否有长耗时操作如未优化的浮点运算混入。6. 安全边界与工程约束6.1 协议层安全限制AOA 协议本身不提供加密与认证所有数据明文传输。在工业场景中必须额外实现应用层 AES-128 加密Android APP 与 MCU 共享密钥对aa_write()数据加密指令白名单机制MCU 端硬编码允许的指令集如仅接受{cmd:led}忽略所有未知 JSON key速率限制在aa_read()后添加if (xTaskGetTickCount() - last_cmd_time 100) return;防止指令洪泛攻击。6.2 硬件资源占用实测STM32F407资源类型占用量说明Flash12.4 KB含 USB 协议栈、状态机、环形缓冲区管理RAM2.1 KB1024B RX 512B TX 状态变量 栈空间CPU168MHz峰值 8.2%连续传输aa_task()单次耗时 14μs1ms 周期下占比极低USB 端点4 个端点EP0~EP3EP0控制、EP1IN、EP2OUT、EP3可选中断此资源占用证明该库可在 256KB Flash / 64KB RAM 的低成本 MCU 上稳定运行满足绝大多数嵌入式需求。