BMI270应用笔记1：BMI270结构体详解

struct bmi2_dev是 BMI270IMU 惯性测量单元传感器驱动的核心设备配置结构体相当于传感器的 “控制中枢”—— 它整合了传感器识别、硬件通信、功能配置、状态存储、算法补偿等全流程的关键参数是驱动程序与硬件交互的核心数据载体适配不同硬件平台如 STM32、Linux和芯片变体。/*! name Structure to define BMI2 sensor configurations */ struct bmi2_dev { /*! Chip id of BMI2 */ uint8_t chip_id; /*! The interface pointer is used to enable the user * to link their interface descriptors for reference during the * implementation of the read and write interfaces to the * hardware. */ void *intf_ptr; /*! To store warnings */ uint8_t info; /*! Type of Interface */ enum bmi2_intf intf; /*! To store interface pointer error */ BMI2_INTF_RETURN_TYPE intf_rslt; /*! For switching from I2C to SPI */ uint8_t dummy_byte; /*! Resolution for FOC */ uint8_t resolution; /*! User set read/write length */ uint16_t read_write_len; /*! Store load status value */ uint8_t load_status; /*! Pointer to the configuration data buffer address */ const uint8_t *config_file_ptr; /*! To define maximum page number */ uint8_t page_max; /*! To define maximum number of input sensors/features */ uint8_t input_sens; /*! To define maximum number of output sensors/features */ uint8_t out_sens; /*! Indicate manual enable for auxiliary communication */ uint8_t aux_man_en; /*! Defines manual read burst length for auxiliary communication */ uint8_t aux_man_rd_burst_len; /*! Array of feature input configuration structure */ const struct bmi2_feature_config *feat_config; /*! Array of feature output configuration structure */ const struct bmi2_feature_config *feat_output; /*! Structure to maintain a copy of the re-mapped axis */ struct bmi2_axes_remap remap; /*! Flag to hold enable status of sensors */ uint64_t sens_en_stat; /*! Read function pointer */ bmi2_read_fptr_t read; /*! Write function pointer */ bmi2_write_fptr_t write; /*! Delay function pointer */ bmi2_delay_fptr_t delay_us; /*! To store the gyroscope cross sensitivity value */ int16_t gyr_cross_sens_zx; /* gyro enable status, used as a flag in CRT enabling and aborting */ uint8_t gyro_en : 1; /* advance power saving mode status, used as a flag in CRT enabling and aborting */ uint8_t aps_status; /* used as a flag to enable variant specific features like crt */ uint16_t variant_feature; /* To store hold the size of config file */ uint16_t config_size; /*! Function pointer to get wakeup configurations */ bmi2_wake_up_fptr_t get_wakeup_config; /*! Function pointer to set wakeup configurations */ bmi2_wake_up_fptr_t set_wakeup_config; /*! Function pointer to get tap configurations */ bmi2_tap_fptr_t get_tap_config; /*! Function pointer to set tap configurations */ bmi2_tap_fptr_t set_tap_config; /*! Array of feature interrupts configuration structure */ struct bmi2_map_int *map_int; /*! To define maximum number of interrupts */ uint8_t sens_int_map; };成员名类型核心意义 作用补充说明chip_iduint8_t芯片 ID标识符作用驱动初始化时读取该值验证是否正确识别到 BMI270而非 BMI260 / 其他芯片是硬件身份校验的关键。不同 BMI2 系列芯片有固定 ID如 BMI270 的 chip_id 为 0x24读取失败则说明通信异常或硬件错误。intf_ptrvoid *接口通用指针作用关联用户自定义的硬件接口描述符如 I2C 的 HAL 句柄、SPI 的设备文件描述符、总线号 / 设备地址实现驱动与底层硬件的解耦提高可移植性。例STM32 中可指向I2C_HandleTypeDefLinux 中可指向 SPI 设备的 fd驱动读写时通过该指针访问具体硬件参数。infouint8_t警告 / 信息状态存储作用记录非致命的运行警告如参数配置不合法、通信轻微异常、配置未生效等供用户排查问题不影响传感器基本运行。区别于 “错误码”仅用于提示如配置值超出硬件范围时标记为 0x01。intfenum bmi2_intf通信接口类型作用指定传感器与主控的通信方式枚举值BMI2_INTF_I2C/BMI2_INTF_SPI驱动根据该值选择对应的通信协议逻辑。核心区分 I2C/SPI两种接口的读写时序、地址格式不同需通过该参数适配。intf_rsltBMI2_INTF_RETURN_TYPE接口操作返回结果作用存储最近一次读写操作的错误码如成功、I2C 超时、SPI 通信失败、寄存器地址错误是定位通信层问题的核心。自定义类型通常为 int8_t0 表示成功负数表示错误如 - 1 超时-2 地址错误。dummy_byteuint8_t哑字节占位 / 填充作用适配 SPI/I2C 接口切换的协议时序SPI 读操作时需发送 1 个无用字节满足时序I2C 无需使用。SPI 读流程先发送寄存器地址 → 发送 dummy_byte → 接收数据该参数用于填充这一步的无用字节。resolutionuint8_tFOC力传感 / 数据分辨率配置作用设置加速度计 / 陀螺仪的测量分辨率如 16 位 / 14 位分辨率越高数据精度越高但可能降低输出速率。FOCForce-sensing Omni-directional Controller是 BMI270 的力传感特性该参数也服务于该功能的精度配置。read_write_lenuint16_t单次读写长度作用指定单次通信的最大 / 默认字节数如读取加速度计 X/Y/Z 轴数据需 6 字节避免单次读写过长导致超时优化通信效率。例设置为 6 则单次读取 3 轴加速度计数据设置为 8 则可同时读取加速度计 温度数据。load_statusuint8_t配置文件加载状态作用记录传感器固件 / 校准数据 / 功能配置文件的加载状态0 未加载1 加载中2 加载完成3 加载失败。配置文件是传感器正常工作的基础该参数用于跟踪加载流程失败时需重新加载。config_file_ptrconst uint8_t *配置文件缓冲区指针作用指向存储传感器配置数据固件参数、校准系数、功能配置表的内存地址驱动从该地址读取数据并写入传感器寄存器完成初始化。配置文件通常是芯片厂商提供的二进制文件包含出厂校准、算法参数等关键数据。page_maxuint8_t寄存器最大页号作用BMI270 的寄存器按 “页” 划分如页 0 基础配置页 1 中断配置该参数限制驱动访问的页范围防止越界。例BMI270 最大页号为 0x05访问 0x06 则触发错误。input_sensuint8_t输入型功能最大数量作用限制 “原始数据类功能”如加速度计、陀螺仪、温度原始数据的配置上限避免超出硬件能力。输入功能作为算法的原始输入而非最终输出如步数、姿态角。out_sensuint8_t输出型功能最大数量作用限制 “算法处理后功能”如步数、敲击检测、姿态角的配置上限管理硬件资源分配。输出功能传感器内部算法处理后直接输出的结果需占用硬件算力 / 内存。aux_man_enuint8_t辅助通信手动使能作用使能 / 禁用 BMI270 的辅助接口可连接磁力计等外部传感器1 使能0 禁用。辅助接口用于扩展传感器功能如 IMU 磁力计实现 9 轴融合。aux_man_rd_burst_lenuint8_t辅助通信突发读取长度作用配置通过辅助接口读取外部传感器数据时的单次 “突发读取” 字节数优化通信效率减少多次小批量读取。例设置为 10 则单次读取外部磁力计 10 字节数据而非分 10 次读 1 字节。feat_configconst struct bmi2_feature_config *功能输入配置数组指针作用指向各功能的基础配置结构体如加速度计量程 ±2g/±8g、陀螺仪采样率 100Hz/1000Hz、低通滤波参数。每个数组元素对应一个功能如加速度计驱动通过该指针加载初始化配置。feat_outputconst struct bmi2_feature_config *功能输出配置数组指针作用指向各功能的输出参数配置如数据输出格式、中断触发条件、输出速率。例配置步数检测功能的输出为 “每 10 步触发一次中断”。remapstruct bmi2_axes_remap轴重映射结构体作用解决传感器物理安装与逻辑轴不一致的问题如倒装 / 侧装重新映射 X/Y/Z 轴的方向 / 顺序让输出数据与实际物理坐标系一致。无需修改上层算法仅通过该结构体适配硬件安装姿态。sens_en_statuint64_t传感器使能状态标志位域作用用 64 位的每 1bit 表示一个功能的使能状态如 bit0 加速度计使能bit1 陀螺仪使能bit2 步数检测使能。64 位可支持大量功能如 BMI270 的 20 种功能快速查询 / 修改功能启用状态。readbmi2_read_fptr_t读函数指针作用指向用户实现的 “从传感器寄存器读数据” 的函数驱动不直接实现硬件读操作适配不同平台。函数原型示例int8_t (*bmi2_read_fptr_t)(uint8_t dev_addr, uint8_t reg_addr, uint8_t *data, uint16_t len, void *intf_ptr)writebmi2_write_fptr_t写函数指针作用指向用户实现的 “向传感器寄存器写数据” 的函数原理同read。是驱动与硬件写操作的核心接口适配 STM32/Linux 等不同平台的底层写逻辑。delay_usbmi2_delay_fptr_t微秒级延迟函数指针作用指向用户实现的微秒延迟函数如 STM32 的HAL_Delay_us、Linux 的usleep用于寄存器写入后等待数据生效。传感器部分寄存器写入后需几十微秒延迟否则读取数据会错误。gyr_cross_sens_zxint16_t陀螺仪交叉灵敏度补偿值Z 轴对 X 轴作用修正陀螺仪轴间干扰如 X 轴旋转时 Z 轴检测到微小信号提高陀螺仪测量精度。出厂校准值驱动读取后用于数据补偿是硬件精度优化的关键。gyro_en : 1uint8_t位域陀螺仪使能标志仅 1 位作用专门用于 CRT连续旋转跟踪功能的使能 / 中止位域设计节省内存。1CRT 功能中陀螺仪使能0 禁用仅占 1bit比普通 uint8_t 节省 7bit 内存。aps_statusuint8_t高级省电模式APS状态作用存储 APS 模式当前状态0 禁用1 模式 12 模式 2CRT 功能的运行策略会根据 APS 状态调整如低功耗下降低采样率。APS 是 BMI270 的低功耗特性平衡功耗与性能。variant_featureuint16_t变体特性使能标志作用使能特定芯片变体的专属功能如部分 BMI270 支持 CRT基础版不支持每 1bit 对应一个变体功能。适配不同批次 / 版本的 BMI270提高驱动兼容性。config_sizeuint16_t配置文件大小作用记录config_file_ptr指向的配置文件总字节数驱动加载时确认读取长度避免越界或读取不完整。配置文件通常为几百字节该值是加载完整性校验的关键。get_wakeup_configbmi2_wake_up_fptr_t获取唤醒配置函数指针作用指向读取 “唤醒功能配置” 的函数如唤醒阈值、唤醒源、唤醒延迟。例查询 “加速度计阈值超过 2g 时唤醒主控” 的当前配置。set_wakeup_configbmi2_wake_up_fptr_t设置唤醒配置函数指针作用指向配置唤醒功能的函数用于自定义唤醒条件如设置唤醒阈值为 1.5g。BMI270 的低功耗核心功能主控休眠时由传感器唤醒。get_tap_configbmi2_tap_fptr_t获取敲击配置函数指针作用指向读取 “轻敲 / 双击检测” 配置的函数如检测阈值、时间窗口、轴选择。例查询双击检测的时间间隔是否为 500ms。set_tap_configbmi2_tap_fptr_t设置敲击配置函数指针作用指向配置敲击检测的函数自定义敲击识别规则。智能穿戴设备常用功能如双击亮屏的核心配置接口。map_intstruct bmi2_map_int *中断映射结构体指针作用指向 “功能 - 中断引脚” 映射关系如敲击检测映射到 INT1步数计数映射到 INT2。管理传感器 2 个中断引脚的功能分配适配不同应用场景。sens_int_mapuint8_t最大中断映射数量作用限制可映射到中断引脚的功能总数如最多 8 个防止超出硬件能力。BMI270 硬件仅支持有限的中断映射该参数避免配置越界。