google adk install Python环境安装教程

Google ADK（Android Open Accessory Development Kit，安卓配件开发套件）用于让外部硬件（如微控制器开发板、传感器集线器或 PC 控制端）通过 USB 与 Android 设备建立标准化通信。在上位机开发与调试过程中，借助 Python 快速建立 ADK 通信客户端是常见的方案。本文围绕 Google ADK 相关 Python 模块及底层 USB 依赖的安装、环境配置与通信验证展开，提供清晰的操作流程与排错参考。

图 1：Google ADK 通信架构与 Python 上位机协议层层级图

一、安装前的环境准备

Google ADK 在主机端通信的核心机制是基于 Android Open Accessory (AOA) 协议，依赖底层的通用 USB 访问接口。在搭建 Python 环境前，系统必须满足以下两项基础条件：

• Python 解释器：建议使用 Python 3.8 至 Python 3.11 版本，避免使用部分过于老旧的 2.x 版本。
• 底层 libusb 原生动态库：Python 的 USB 访问模块（如 PyUSB）仅提供高层封装，底层必须有系统级的 libusb 支持。

各操作系统底层依赖安装

在 Linux（如 Ubuntu / Debian）系统中，需提前安装开发头文件和 libusb 运行库：

sudo apt-get update
sudo apt-get install -y python3-dev python3-pip libusb-1.0-0-dev

在 macOS 系统中，可通过 Homebrew 安装：

brew install libusb

在 Windows 环境下，通常需使用 Zadig 工具为接入的 Android Accessory 设备指定 WinUSB 或 libusb-win32 驱动，确保 Python 能够直接访问 USB 端点。

二、创建隔离虚拟环境与安装步骤

为防止依赖冲突与权限污染，强烈建议在独立的虚拟环境中安装相关依赖。完整的操作流程包含四个阶段：创建虚拟环境、升级包管理工具、安装核心依赖包、验证模块加载。

图 2：Python 虚拟环境搭建与 ADK 依赖安装全流程步骤

步骤 1：创建并激活 Python 虚拟环境

在工程目录下执行以下命令：

# 创建名为 adk_env 的虚拟环境
python3 -m venv adk_env

# Linux / macOS 激活环境
source adk_env/bin/activate

# Windows 激活环境 (PowerShell)
# .\adk_env\Scripts\Activate.ps1

步骤 2：升级基础构建工具

python -m pip install --upgrade pip setuptools wheel

步骤 3：安装 PyUSB 及 ADK 依赖包

Google ADK 交互通常由 pyusb 作为总线支撑，配合社区维护的 google-adk 包或项目专用的 AOA Python 驱动脚本进行接入。执行：

pip install pyusb

若使用特定的 ADK 封装库，可通过对应仓库或本地源码包安装：

pip install google-adk

说明：若官方源缺少最新 wheel，可以从源码目录使用 pip install . 方式完成本地编译安装。

三、AOA 协议模式与 USB 握手流程

Google ADK 工作于 Android Open Accessory 协议之上。当 Android 设备通过 USB 插入电脑或控制器时，默认处于标准 MTP/ADB 状态，需要通过两阶段握手转入 Accessory 模式。

图 3：Android Open Accessory 握手转入模式的时序过程

四、编写验证脚本检验环境有效性

安装完成后，编写一个简短的 Python 测试脚本 verify_adk.py，用以核验 PyUSB 与底层动态库是否正确链接，以及是否能探测到总线上的设备：

import usb.core
import usb.util
import sys

def verify_usb_backend():
    print("--- 检查 libusb 与 PyUSB 后端绑定 ---")
    try:
        # 尝试查找任意连接的 USB 设备
        dev = usb.core.find(find_all=True)
        device_list = list(dev)
        print(f"成功加载 USB 后端！当前系统已枚举 USB 设备数量: {len(device_list)}")
        
        # 遍历排查是否存在 Google/Android 相关设备 (VendorID 0x18D1)
        found_android = False
        for d in device_list:
            if d.idVendor == 0x18d1:
                print(f"发现 Android 设备: VendorID=0x{d.idVendor:04x}, ProductID=0x{d.idProduct:04x}")
                found_android = True
        if not found_android:
            print("提示：当前未检测到 VendorID=0x18D1 的 Android 设备，请连接手机并打开 USB 调试。")
    except usb.core.NoBackendError:
        print("错误：未找到可用的 libusb 后端，请检查系统底层驱动或库路径！", file=sys.stderr)
    except Exception as e:
        print(f"出现异常: {e}", file=sys.stderr)

if __name__ == "__main__":
    verify_usb_backend()

运行该脚本查看控制台输出：

python verify_adk.py

若能够输出已枚举设备数量且未抛出 NoBackendError，说明 Python 访问底层 USB 的基础环境已完全搭建成功。

五、常见问题与权限配置对照

在实际连接与调试过程中，常会遇到权限不足或找不到后端的问题。下表总结了典型报错及具体处理方式：

图 4：Google ADK Python 环境常见错误与解决策略对照总结

按照上述步骤完成 Python 解释器、底层 libusb 与通信库的部署后，即可在 Python 脚本中基于 AOA 握手与端点读写逻辑，构建稳定的 Google ADK 数据交互应用。