1. 项目概述为什么我们需要在Android中集成i2c-tools在嵌入式开发和Android底层系统调试中I2C总线就像设备间的“神经末梢”负责连接各种传感器、EEPROM、触摸屏控制器等外设。作为一名长期扎根在一线的嵌入式工程师我深知当系统启动异常、某个传感器数据读取失败或者需要验证硬件焊接是否正确时一个趁手的I2C调试工具是多么关键。Android系统本身功能强大但其原生开发环境更侧重于上层应用对于底层硬件的直接探查能力往往被封装起来不够直观。这就是我们今天要讨论的核心将经典的Linux用户空间I2C调试工具集——i2c-tools完整地移植并编译到Android系统中使其成为一个可以在adb shell中直接运行的可执行应用。i2c-tools包含了i2cdetect探测总线上的设备、i2cget读取寄存器、i2cset写入寄存器和i2ctransfer进行复合I2C传输等核心工具它们是硬件工程师和驱动开发者的“瑞士军刀”。想象一下你无需反复修改和刷写内核驱动代码只需在终端输入几条命令就能直接与I2C设备“对话”快速定位问题是出在硬件连接、供电还是驱动配置上这能极大提升调试效率。本篇文章我将基于一个真实的Android BSP板级支持包开发场景手把手带你完成从源码获取、集成到Androidexternal目录、编写Android.bp或Android.mk编译脚本再到最终编译生成可执行文件并推送到设备上运行的全过程。整个过程不仅涉及编译技巧更包含了对Android构建系统Soong/Bazel的理解以及在实际操作中可能遇到的诸多“坑”和解决技巧。无论你是刚接触Android系统开发的工程师还是希望深化对Android构建系统理解的开发者这篇内容都将提供一条清晰的实践路径。2. 核心工具解析i2c-tools 四剑客各显神通在动手集成之前我们必须先理解我们要集成的究竟是什么。i2c-tools不是一个单一的工具而是一个工具集每个工具都有其独特的用途组合使用可以覆盖绝大部分I2C调试场景。2.1 i2cdetect总线侦察兵i2cdetect是你的第一步。它的核心任务是扫描指定的I2C总线找出所有响应设备地址。在硬件调试初期你首先需要确认设备是否成功上电I2C总线SDA SCL的物理连接包括上拉电阻是否正确设备地址是否与预期相符它的工作原理是向总线上每个可能的地址通常为0x03到0x77发送一个“读”或“写”信号并监听是否收到ACK应答信号。在命令行中最常用的格式是i2cdetect -l列出所有I2C总线控制器以及i2cdetect -y bus_num对某条总线进行扫描。注意-y参数表示禁用交互模式直接执行。在脚本中必须使用此参数。扫描结果中UU表示该地址已被内核驱动占用--表示无响应而显示为十六进制数字如3c则表示该地址有设备响应。2.2 i2cget 与 i2cset寄存器的读写器一旦通过i2cdetect找到了设备下一步就是与其寄存器进行交互。i2cget和i2cset就是完成这项基础读写操作的工具。i2cget用于从设备的某个寄存器读取数据。命令格式通常为i2cget -f -y bus chip_address register_address mode。其中-f参数非常重要它强制访问设备即使该设备地址已被内核驱动声明占用。在调试时我们经常需要绕过驱动直接与硬件对话-f标志必不可少。mode指定读取数据的长度如bbyte 8位或wword 16位注意字节序。i2cset用于向设备的某个寄存器写入数据。命令格式为i2cset -f -y bus chip_address register_address value mode。同样-f和-y是常用参数。value是要写入的数据mode同样指定数据格式。这两个工具是验证设备基本功能、配置设备工作模式如设置传感器量程、开关某个功能模块的最直接手段。2.3 i2ctransfer复合传输的多面手i2ctransfer是功能更强大的工具用于执行复杂的、原子性的I2C传输序列。I2C协议支持在一个START信号和STOP信号之间进行多次读写组合。有些设备操作例如读取一个序列号、进行一次校准需要这种复合操作。例如一个常见的操作是先写入设备地址和寄存器地址写操作然后不发送STOP信号而是发送一个重复起始条件Repeated START再发起一个读操作来读取数据。i2ctransfer的语法可以清晰地表达这种序列i2ctransfer -f -y bus w2chip_address reg_addr_high reg_addr_low rlength。这条命令表示在总线bus上向地址chip_address先写入2个字节w2即寄存器地址的高低位然后紧接着读取length个字节的数据。实操心得在调试一些复杂的I2C设备如IMU、环境光传感器时其数据手册中的多字节读取时序往往就是这种复合格式。使用i2ctransfer可以精确地模拟这种时序而i2cget有时可能无法满足要求特别是当设备要求先发送特定命令字再读数据时。因此掌握i2ctransfer是进行深度调试的关键。3. 项目集成在 Android external 目录安家落户Android的源码树有一个固定的目录结构第三方或开源软件的源码通常放置在external/目录下。我们要做的就是把i2c-tools的源码下载到这里并为其编写构建规则让Android的构建系统能够识别并编译它。3.1 源码获取与目录准备首先我们需要获取i2c-tools的源代码。最权威的来源是内核官网的镜像。我们可以使用git克隆或者直接下载稳定版本的tar包。这里以克隆为例cd 你的Android源码根目录 cd external/ git clone https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git克隆完成后你会得到一个i2c-tools/目录。进入该目录你会发现它包含了tools/工具源码、lib/I2C用户空间库、include/等子目录。标准的Linux编译流程是运行make但我们需要适配Android。Android构建系统现在主流是Soong使用Android.bp文件需要明确的构建规则。i2c-tools的源码目录结构可能不完全符合Android的默认期望我们需要对其进行一些整理并创建关键的构建描述文件。一个常见的做法是我们只为tools/目录下的几个核心工具创建编译目标。因此我建议在external/i2c-tools/下创建一个新的Android.bp文件。同时为了保持清晰我们可以把编译所需的源码文件显式地列出来。3.2 编写 Android.bp 构建脚本Android.bp是Soong构建系统的蓝图文件它用类似JSON的语法描述模块及其依赖。我们的目标是生成四个可执行文件i2cdetecti2cgeti2cseti2ctransfer。它们共享一些公共的源码文件。下面是一个详细的Android.bp文件示例我将其拆解说明// 首先编译一个静态库包含所有工具共用的辅助函数。 // 这部分代码通常来自 tools/util.c 等文件。 cc_library_static { name: libi2c-tools-common, vendor_available: true, // 允许在vendor分区使用 srcs: [ tools/util.c, ], cflags: [ -Wall, -Werror, -DANDROID, // 定义Android宏用于条件编译 ], export_include_dirs: [.], // 导出头文件路径 } // 编译 i2cdetect cc_binary { name: i2cdetect, vendor: true, // 标记为vendor模块通常编译到vendor分区 srcs: [ tools/i2cdetect.c, ], static_libs: [ libi2c-tools-common, ], shared_libs: [ libc, libcutils, // 可能用到Android的一些工具函数 ], cflags: [ -Wall, -Werror, -DANDROID, ], } // 编译 i2cget cc_binary { name: i2cget, vendor: true, srcs: [ tools/i2cget.c, ], static_libs: [ libi2c-tools-common, ], shared_libs: [ libc, libcutils, ], cflags: [ -Wall, -Werror, -DANDROID, ], } // 编译 i2cset cc_binary { name: i2cset, vendor: true, srcs: [ tools/i2cset.c, ], static_libs: [ libi2c-tools-common, ], shared_libs: [ libc, libcutils, ], cflags: [ -Wall, -Werror, -DANDROID, ], } // 编译 i2ctransfer cc_binary { name: i2ctransfer, vendor: true, srcs: [ tools/i2ctransfer.c, ], static_libs: [ libi2c-tools-common, ], shared_libs: [ libc, libcutils, ], cflags: [ -Wall, -Werror, -DANDROID, ], }关键点解析cc_library_static我们首先定义了一个静态库libi2c-tools-common。这是因为i2c-tools的各个可执行文件共享一些通用函数如打印帮助信息、解析参数等。将其编译为静态库可以避免代码重复也符合Android的模块化设计思想。cc_binary这是定义可执行文件的目标。每个工具对应一个cc_binary模块。vendor: true这个属性非常重要。它声明该模块属于vendor分区。在Android系统分区化system/vendor/product等之后像i2c-tools这种硬件调试工具通常被归类为供应商vendor提供的功能放置在vendor/bin/下。设置为vendor: true能确保它被正确编译和链接到vendor镜像中。static_libs与shared_libsstatic_libs链接我们上面定义的静态库。shared_libs链接系统动态库libc是C标准库libcutils是Android的一个工具库某些函数如属性获取可能会用到先链上以防编译错误。cflags这里设置了编译标志。-Wall -Werror将警告视为错误有助于保持代码质量。-DANDROID定义了一个宏源码中可能通过#ifdef ANDROID来区分Android和Linux的编译环境用于处理一些平台差异如日志输出Android用ALOG Linux用printf。注意事项原始的i2c-tools源码可能依赖linux/i2c-dev.h等Linux内核头文件。在Android的BSP环境中这些头文件通常由内核模块导出位于bionic/libc/kernel/uapi/linux或供应商提供的kernel-headers中。如果编译时报错找不到i2c-dev.h你需要检查你的Android源码环境是否包含了正确的内核头文件或者可能需要从你的内核源码中手动拷贝必要的头文件到external/i2c-tools/include/linux/目录下并在Android.bp中添加local_include_dirs: [include]。这是集成过程中最常见的“坑”之一。4. 编译与部署生成并推送可执行文件编写好Android.bp后我们就可以利用Android强大的构建系统来编译了。4.1 执行编译命令在Android源码根目录下执行针对特定产品的编译命令。假设你的产品代号TARGET_PRODUCT是my_product并且你想编译eng版本调试版本权限更宽松source build/envsetup.sh lunch my_product-eng然后单独编译我们的i2c-tools模块。模块名就是我们Android.bp里定义的namemake i2cdetect i2cget i2cset i2ctransfer或者如果你想一次性编译所有这四个工具假设它们都在同一个Android.bp里被定义且没有其他同名模块冲突也可以尝试make i2c-tools但更稳妥的做法是逐个指定或者使用mma命令在external/i2c-tools/目录下进行模块编译cd external/i2c-tools mmamma命令会编译当前目录及其子目录下的所有模块。编译成功后你可以在输出目录找到生成的可执行文件。对于vendor: true的模块路径通常类似于out/target/product/my_product/vendor/bin/i2cdetect4.2 推送文件到设备并测试编译出的镜像文件如vendor.img已经包含了这些工具。但为了快速测试我们通常直接通过adb push将可执行文件推送到设备的对应目录。首先确保你的设备已通过USB连接并且adb可以访问。通常需要先adb root获取root权限然后adb remount重新挂载系统分区为可写对于vendor分区有时需要adb disable-verity等操作具体取决于设备和安全策略。更简单和安全的方法是推送到/data/local/tmp/这个临时可执行目录adb root adb remount # 如果失败尝试 adb disable-verity 并重启或直接使用 /data/local/tmp adb push out/target/product/my_product/vendor/bin/i2cdetect /data/local/tmp/ adb push out/target/product/my_product/vendor/bin/i2cget /data/local/tmp/ # ... 推送其他工具 adb shell chmod 755 /data/local/tmp/i2cdetect # 添加执行权限然后进入设备的adb shell进行测试adb shell cd /data/local/tmp ./i2cdetect -l这条命令应该能列出设备上的I2C总线控制器例如i2c-0i2c-1等。接下来尝试扫描一条总线例如i2c-1./i2cdetect -y 1如果总线上有设备你应该能看到对应的地址被显示出来。一个关键的权限问题直接运行i2cget或i2cset操作/dev/i2c-*设备节点时可能会遇到Permission denied错误。这是因为/dev/i2c-*的设备节点默认可能只有root或i2c用户组有读写权限。解决方法有几种在adb shell中先执行su切换到root用户需要设备已root。修改设备的SELinux策略对于eng调试版本可以先setenforce 0临时关闭SELinux强制模式但这不是生产环境的安全做法。在设备的init.rc文件或sepolicy中为你编译的可执行文件或shell添加正确的权限上下文。这是最正规但最复杂的方法通常在产品开发阶段由系统工程师配置。对于快速调试在eng版本的设备上使用root权限是最直接的方式。5. 实战应用与调试技巧实录工具就绪后我们来看几个真实的调试场景展示如何组合运用这些工具。5.1 场景一快速验证光线传感器是否就绪假设我们设计上在I2C总线1上挂载了一个光线传感器地址为0x39。上电后应用层报告无法读取数据。第一步物理连接与供电检查。这步略过假设已用万用表等工具检查过。第二步总线扫描。./i2cdetect -y 1如果输出中0x39位置显示为UU说明内核已有驱动加载并占用了该设备。这是正常情况。如果显示为39说明设备存在但无驱动占用。如果显示为--则可能地址错误、设备未上电、或总线连接问题。第三步读取设备ID寄存器。大多数传感器都有一个只读的“WHO_AM_I”或设备ID寄存器。假设从数据手册得知该传感器在寄存器0x0A存放ID值0x50。./i2cget -f -y 1 0x39 0x0A b如果返回0x50恭喜硬件通信基本正常。如果返回0xff、0x00或错误则需要进一步排查。可能是寄存器地址错误、读写位设置错误I2C协议中地址的最低比特位表示读写0写1读。i2c-tools命令中的地址通常是7位地址工具会自动处理读写位。5.2 场景二配置一个六轴IMU的加速度计量程假设IMU地址为0x68控制加速度计量程的寄存器为0x1C我们需要写入值0x18来设置其为±16g量程。先读后写确认原始值良好的习惯./i2cget -f -y 0 0x68 0x1C b假设读出0x00默认值。写入目标值./i2cset -f -y 0 0x68 0x1C 0x18 b再次读取确认写入成功./i2cget -f -y 0 0x68 0x1C b此时应返回0x18。5.3 场景三读取一个需要复合命令的EEPROM数据某些EEPROM如24C02读取特定地址的数据需要先写入内存地址再发起读操作。假设设备地址0x507位地址要读取从0x0010地址开始的2个字节。使用i2ctransfer可以完美模拟./i2ctransfer -f -y 0 w20x50 0x00 0x10 r2这条命令分解w20x50向地址0x50写入2个字节。0x00 0x10写入的2个字节数据即要读取的EEPROM内部地址0x0010。r2紧接着读取2个字节。 命令执行后会输出两个十六进制数即0x0010和0x0011地址的内容。5.4 常见问题排查表问题现象可能原因排查步骤与解决方案i2cdetect -l无输出I2C总线驱动未加载或未创建/dev/i2c-*节点1. 检查内核配置CONFIG_I2C_CHARDEV是否启用。2. 检查设备树DTS中I2C控制器节点是否正确。3. 在adb shell中检查/dev/目录下是否存在i2c-0i2c-1等设备节点。i2cdetect -y N扫描全为--总线物理问题、设备未上电、总线被占用1. 用示波器或逻辑分析仪检查SCL和SDA波形。2. 确认设备供电电压和电平是否匹配。3. 检查是否有其他驱动如GPIO模拟I2C占用了该总线引脚。扫描显示UU该地址已被内核驱动绑定这是正常现象。如果想用i2c-tools强制访问必须在命令中加上-f参数。注意这可能会干扰正在运行的驱动。Permission denied对/dev/i2c-*设备节点无访问权限1. 在调试版本中使用adb root和su获取root权限。2. 检查设备节点权限ls -l /dev/i2c-*。3. 修改SELinux策略或文件权限需重新编译系统镜像。i2cget/i2cset操作失败但设备存在寄存器地址错误、读写位混淆、设备处于休眠模式1. 仔细核对数据手册的寄存器地址和访问模式读/写。2. 确认设备是否需要先发送特定唤醒命令查看手册的“Power Mode”部分。3. 尝试使用i2ctransfer进行更精确的时序控制。编译时找不到linux/i2c-dev.hAndroid源码缺少内核头文件1. 从你的内核源码include/uapi/linux/下拷贝i2c-dev.h和i2c.h到external/i2c-tools/include/linux/。2. 在Android.bp的cflags中添加-Iexternal/i2c-tools/include。6. 进阶集成到系统镜像与权限配置为了让工具在设备出厂后仍能使用例如在工厂测试环节我们需要将其永久集成到系统镜像中并解决权限问题。6.1 确保编译进镜像我们之前在Android.bp中设置了vendor: true这通常足以让模块在编译vendorimage时被包含进去。你可以通过检查编译日志或直接查看out/target/product/product/vendor/bin/目录下是否存在这些二进制文件来确认。为了确保它们被包含在最终的vendor.img中有时还需要在产品特定的配置文件中声明。例如在device/manufacturer/product/device.mk或vendor.mk文件中添加PRODUCT_PACKAGES \ i2cdetect \ i2cget \ i2cset \ i2ctransferPRODUCT_PACKAGES列表会指示构建系统将这些模块打包进镜像。6.2 配置 SELinux 权限针对Userdebug/Eng版本在Android的强制访问控制MAC体系SELinux下即使有root权限进程也需要有对应的安全上下文domain和权限规则allow rules才能访问特定资源如i2c_device。对于调试工具一个相对简单但非生产环境标准的方法是修改SELinux策略文件。策略文件通常位于device/manufacturer/product/sepolicy/目录下。为工具定义类型在file_contexts文件中为我们的可执行文件打上标签。例如/vendor/bin/i2cdetect u:object_r:i2ctools_exec:s0 /vendor/bin/i2cget u:object_r:i2ctools_exec:s0 /vendor/bin/i2cset u:object_r:i2ctools_exec:s0 /vendor/bin/i2ctransfer u:object_r:i2ctools_exec:s0这表示这些文件的安全上下文是i2ctools_exec。定义域转换在i2ctools.te可能需要新建策略文件中定义当执行这些文件时进程应该进入的域domain并赋予其必要的权限。# 定义类型 type i2ctools, domain; type i2ctools_exec, exec_type, vendor_file_type, file_type; # 从 init shell 或 adb shell 转换到 i2ctools 域 init_daemon_domain(i2ctools) # 或者如果从 adbd 或 shell 启动 domain_auto_trans(shell, i2ctools_exec, i2ctools) domain_auto_trans(adbd, i2ctools_exec, i2ctools) # 允许 i2ctools 域访问 I2C 设备 allow i2ctools i2c_device:chr_file { open read write ioctl }; # 允许一些基本操作 allow i2ctools self:capability { dac_override }; allow i2ctools vendor_file:file { execute read open getattr };这段策略的意思是当一个在shell或adbd域中的进程执行了带有i2ctools_exec标签的文件时其进程域会自动切换到i2ctools。而i2ctools域被允许对i2c_device类型的字符设备进行打开、读、写和IO控制操作。重要警告上述SELinux策略是一个高度简化的示例仅用于调试环境eng/userdebug。在产品user版本中权限必须遵循最小权限原则进行极其严格的配置。直接使用dac_override这类宽泛的权限是非常危险的。在实际产品开发中这项工作应由专业的系统安全工程师完成。6.3 编写一个简单的封装脚本为了方便团队其他成员使用你可以在设备的/vendor/bin/下放置一个简单的shell脚本例如叫i2c-helper.sh里面预先定义好总线号和常用设备地址封装一些常用命令。这样硬件测试人员只需运行./i2c-helper.sh scan或./i2c-helper.sh read_light即可无需记忆复杂的命令格式。集成i2c-tools到Android系统不仅仅是完成一次编译更是建立了一套高效的底层硬件调试通道。它把硬件问题从“盲猜”变成了“可观测”、“可交互”的调试过程。在实际项目中这套工具链帮我节省了无数个小时的驱动调试时间。当你下次再遇到I2C设备通信异常时不妨先别急着翻看内核日志打开adb shell用这几条命令先跟硬件“聊一聊”很可能问题就迎刃而解了。
