Proxmark5 天线控制器 I2C 寄存器编程手册：从从机协议到 `hw ant_pm5` 实战

Proxmark5 天线控制器 I2C 寄存器编程手册从从机协议到hw ant_pm5实战【免费下载链接】proxmark3Iceman Fork - Proxmark3项目地址: https://gitcode.com/GitHub_Trending/pr/proxmark3本文面向需要与 Proxmark5PM5天线控制器通过 I2C 总线通信的主机侧Host / 集成开发者系统讲解该控制器的从机地址、寄存器模型、通信时序、频率 / LED / Q 值控制逻辑与互斥约束并结合本仓库的客户端命令hw ant_pm5与固件端CMD_ANT_CONTROL_*实现帮助读者完成从底层寄存器操作到上层命令调用的完整对接。1. 控制器概览一个标准的 I2C 从机Proxmark5 主板上的天线控制器ANT Controller本质上是一个工作在I2C 从机slave模式下的独立小芯片负责直接驱动天线相关的控制线。主机PM5 主控以及经由其转发的上位机只需读写少量 I2C 寄存器即可完成对天线的全部控制与状态查询。其能力总结如下能力说明工作频率五档可选125 kHz / 134 kHz / 250 kHz / 375 kHz / 500 kHzLED 指示HF高频LED 与 LF低频LED可各自独立控制开关Q 值高 Q / 低 Q 两档切换该控制器的设计文档见 PM5_ANT_Controller_RM.md它与 PM5_Button_Controller_RM.md按键控制器、PM5_RGB_Controller_RM.mdRGB 控制器共同构成 PM5 平台的外设控制器家族——三者的 I2C 通信模型高度一致从机地址 寄存器指针 先写地址后读写的约定但寄存器语义各自不同。本文聚焦天线控制器本身。2. I2C 通信基础2.1 从机地址项目值7 位从机地址0x518 位写地址0xA20x51 1 | 08 位读地址0xA30x51 1 | 1固件端源码中直接以0x51作为从机地址参与 I2C 事务并在左移一位后传入底层驱动。见 armsrc/appmain.cuint8_t addr 0x51; // TODO DXL define move to header? uint8_t cmd payload-reg_type 0 ? 0x01 : 0x02; bool isok I2C_BufferWrite(payload-data, 1, cmd, addr 1);其中addr 1即0xA2写地址而读事务中底层驱动会将其| 1得到0xA3读地址与手册中的 8 位地址完全吻合。2.2 通信速率手册明确建议将 I2C 时钟速率控制在10 kHz 左右过高的速率可能导致通信失败。这一点与 PM5 系列其他控制器如 RGB 控制器的推荐一致属于该外设族共有的时序约束。2.3 通信模型寄存器操作遵循先写寄存器地址再读/写数据的寄存器指针register pointer约定进行任何寄存器操作前必须先执行一次写操作告知从机接下来要操作哪个寄存器读操作先执行一次仅携带 1 字节寄存器地址的写操作再发起读事务写操作单次写事务中第 1 字节为寄存器地址后续字节为该寄存器的数据。仓库底层驱动 armsrc/i2c.c 完整实现了这一模型I2C_BufferWritearmsrc/i2c.c先发送device_address 0xFE写地址再发送device_cmd寄存器地址随后逐字节发送数据读路径I2C_BufferReadRawarmsrc/i2c.c则先发写地址 寄存器地址然后repeated START切换到读地址device_address | 1再逐字节读取末字节以 NACK 结束。3. 寄存器映射总览地址名称访问权限数据长度说明0x00非法寄存器默认——上电默认地址不可读作为地址写入亦被拒绝0x01IO 数据寄存器读 / 写1 字节直接读写天线控制线的原始电平底层直通接口0x02IO 映射寄存器读 / 写1 字节频率 / LED / Q 值的逻辑控制推荐使用0xFE设备标识寄存器只读8 字节设备身份签名0xFF固件版本寄存器只读2 字节主版本号 次版本号值得注意的是固件端对0x01/0x02的选择正是通过reg_type字段完成的reg_type 0对应0x01IO 数据寄存器reg_type 1对应0x02IO 映射寄存器见 armsrc/appmain.c。这也是客户端hw ant_pm5命令-m开关的语义来源。4. 寄存器详解4.10x00— 非法寄存器是上电后的默认当前寄存器地址在写入有效寄存器地址之前任何读操作都会被拒绝NACK将0x00作为寄存器地址写入同样被拒绝。4.20x01— IO 数据寄存器读 / 写1 字节直接读写天线控制 IO 组的 8 位原始电平读返回当前 8 根控制线的实时状态写直接设置这 8 根控制线不经过0x02的仲裁与约束逻辑这 8 位在逻辑上覆盖与0x02相同的控制信号集合频率选择、Q 值、HF/LF LED但位序属于硬件实现细节官方不保证公开⚠️ 该寄存器是底层直通接口常规控制请使用0x02⚠️ 除非调试目的不要操作该寄存器否则当天线硬件改版后写入不兼容的数据可能引发异常。联动关系说明写0x02会同时更新内部逻辑映射与实际控制线写0x01只直接改变实际控制线不会回写内部逻辑映射。若混用两者随后读0x02可能返回与0x01写入值不一致的旧值。4.30x02— IO 映射寄存器读 / 写1 字节8 位映射如下位含义取值7125 kHz 使能1 使能 / 0 禁用6134 kHz 使能1 使能 / 0 禁用5250 kHz 使能1 使能 / 0 禁用4375 kHz 使能1 使能 / 0 禁用3500 kHz 使能1 使能 / 0 禁用2HF LED1 亮 / 0 灭1LF LED1 亮 / 0 灭0Q 值1 高 Q / 0 低 Q约束条件详见第 6 节。该位映射在 PM5 平台的用户文档中亦被直接引用见 Getting_Started_With_PM5.md8bit map: 125 134 250 375 500 HFLED LFLED Q (lsb)即从最高位bit7到最低位bit0依次为 125k / 134k / 250k / 375k / 500k / HF LED / LF LED / Q与手册完全一致。4.40xFE— 设备标识寄存器只读8 字节返回固定 8 字节身份签名0x70 0x6D 0x35 0x5F 0x61 0x6E 0x74 0x78用途主机读取后与期望值比对确认当前连接的确实是本天线控制器而非其他 I2C 设备环形读取读完第 8 字节后继续读会回绕到第 1 字节。4.50xFF— 固件版本寄存器只读2 字节第 1 字节主版本号第 2 字节次版本号当前版本v1.2主 1 / 次 2用途主机可据此做版本适配与问题定位读完第 2 字节后继续读会回绕到第 1 字节。5. 操作方法5.1 写寄存器START | write address 0xA2 | ACK | register address | ACK | data | ACK | STOP主机发送START主机发送 8 位写地址0xA2从机回复ACK主机发送寄存器地址1 字节从机回复ACK主机发送数据本控制器每个可写寄存器的数据体均为 1 字节从机回复ACK主机发送STOP。若向只读寄存器0xFE/0xFF或非法地址写入从机会以NACK终止通信。5.2 读寄存器读操作分为设地址与读数据两个阶段设地址: START | write address 0xA2 | ACK | register address | ACK | STOP 读数据: START | read address 0xA3 | ACK | data0 | ACK | ... | dataN | NACK | STOP主机发送START随后发送写地址0xA2从机回复ACK主机发送寄存器地址1 字节从机回复ACK主机发送STOP或切换为repeated START主机发送START随后发送读地址0xA3从机回复ACK从机依次发送数据字节主机对中间每个字节回复ACK对最后一个字节回复NACK以结束主机发送STOP。在单次读事务中从机会连续发送数据0xFE最多 8 字节、0xFF2 字节、0x01/0x021 字节由主机以NACK主动结束。仓库驱动I2C_BufferReadRawarmsrc/i2c.c正是按上述两阶段实现的先I2C_SendByte(device_address 0xFE)I2C_SendByte(device_cmd)设地址再I2C_Start()后发送device_address | 1切换读方向循环I2C_ReadByte()读取数据并在len 0时调用I2C_NoAck()发送末字节 NACK——与手册第 5.2 节的时序一一对应。5.3 操作示例操作字节序列设置 125 kHz、HF LED 亮、低 Q写0x020x840b10000100设置 250 kHz、双 LED 亮、低 Q写0x020x260b00100110读固件版本写地址0xFF然后读 2 字节5.4 在 PM5 上通过hw ant_pm5操作主机侧开发者可以直接使用客户端内置命令完成上述寄存器操作无需自行实现 I2C 时序。命令定义见 client/src/cmdhw.chw ant_pm5 --set u8_data写入IO 数据寄存器0x01hw ant_pm5 -m --set u8_data写入IO 映射寄存器0x02。命令执行流程为先发送CMD_ANT_CONTROL_READ0x0171定义见 include/pm3_cmd.h读取当前寄存器值再在用户提供数据时发送CMD_ANT_CONTROL_WRITE0x0170写入新值。例如将天线切换为 250 kHz 双 LED 亮 低 Q等价于写0x02 0x26即hw ant_pm5 -m --set 0x26固件端在 armsrc/appmain.c 中处理这两个命令初始化 I2CI2C_init(true)后依据reg_type选择0x01或0x02通过I2C_BufferWrite/I2C_BufferReadRaw完成与从机地址0x51的通信并将结果以PM3_SUCCESS/PM3_EFAILED状态返回客户端。整套链路客户端命令 → USB/网络命令帧 → 固件 I2C 主控 → 天线控制器从机可直接用于集成与自动化测试。6. 寄存器互斥与约束条件频率位互斥0x02bit7~bit3同一时刻最多允许 1 个位置 1若同时置多个位优先级按频率从低到高125k → 134k → 250k → 375k → 500k若 5 个位全为 0则自动使能 125 kHz作为兜底。Q 值与频率联动0x02bit0高 Q 仅在频率为125 kHz 或 134 kHz时生效频率为 125/134 且 bit0 1 → 高 Q其余所有情况其他频率或 bit0 0均被强制为低 Q。该约束在 PM5 用户文档中有明确的安全动机高 Q 只允许在 125 kHz / 134 kHz 下使用是为了防止过高的谐振电压损坏设备见 Getting_Started_With_PM5.md。只读寄存器保护0xFE与0xFF只读向其写入数据会被拒绝NACK 并终止通信。非法地址保护0x00不是有效寄存器读写均被拒绝。7. 通信与寄存器默认值总结上电默认125 kHz 低 Q 双 LED 灭0x02默认值0x80设备标识8 字节签名0x70 6D 35 5F 61 6E 74 78标识本设备为多频率、全功能天线控制器固件版本主 1 / 次 2v1.2多字节寄存器回绕0xFE8 字节与0xFF2 字节读至末尾后回绕到首字节寄存器地址跨事务保持STOP后寄存器地址依然保留直到下一次写事务重置它因此连续读同一寄存器时只需写一次地址0x01与0x02不同步0x01是直通物理控制线0x02是经过仲裁的逻辑映射详见 4.2。8. 流程图8.1 上电初始化流程8.2 IO 映射更新流程8.3 I2C 通信处理流程注无论当前处于哪个处理阶段只要检测到 STOPSCL 为高时 SDA 上升立即返回空闲状态。8.4 写寄存器时序8.5 读寄存器时序以读固件版本为例9. 集成要点速查首次对接先验身份上电后建议先读0xFE8 字节校验签名0x70 6D 35 5F 61 6E 74 78再读0xFF获取固件版本避免与其他 I2C 设备混淆、便于版本适配常规控制只用0x02频率、双 LED、Q 值全部通过 IO 映射寄存器控制0x01仅在底层调试时使用遵守频率互斥写0x02时频率位bit7~bit3至多置 1 位全 0 时自动回退 125 kHz多位置 1 时按 125k → 134k → 250k → 375k → 500k 的低频优先仲裁高 Q 有条件bit0 1 且频率为 125/134 kHz 才生效其余情况强制低 Q——这是防止谐振过压损坏硬件的安全设计速率控制在 10 kHz 左右避免高速通信失败地址跨事务保留连续读同一寄存器时无需重复写地址但切换寄存器前必须先写一次新地址PM5 上直接使用命令hw ant_pm5 -m --set data写映射寄存器、hw ant_pm5 --set data写 IO 数据寄存器命令实现与寄存器语义一一对应可作为集成验证与自动化的快捷通道。以上要点与全部寄存器语义、时序均可在仓库中交叉验证协议文档见 PM5_ANT_Controller_RM.md客户端命令实现见 client/src/cmdhw.c固件端命令处理见 armsrc/appmain.cI2C 底层驱动见 armsrc/i2c.c命令字定义见 include/pm3_cmd.h。【免费下载链接】proxmark3Iceman Fork - Proxmark3项目地址: https://gitcode.com/GitHub_Trending/pr/proxmark3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考