struct bmi2_dev 是 BMI270（IMU 惯性测量单元）传感器驱动的核心设备配置结构体，相当于传感器的 "控制中枢"------ 它整合了传感器识别、硬件通信、功能配置、状态存储、算法补偿等全流程的关键参数，是驱动程序与硬件交互的核心数据载体，适配不同硬件平台（如 STM32、Linux）和芯片变体。
cpp
/*! @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_id |
uint8_t |
芯片 ID（标识符）作用：驱动初始化时读取该值，验证是否正确识别到 BMI270（而非 BMI260 / 其他芯片），是硬件身份校验的关键。 | 不同 BMI2 系列芯片有固定 ID（如 BMI270 的 chip_id 为 0x24），读取失败则说明通信异常或硬件错误。 |
intf_ptr |
void * |
接口通用指针作用：关联用户自定义的硬件接口描述符（如 I2C 的 HAL 句柄、SPI 的设备文件描述符、总线号 / 设备地址），实现驱动与底层硬件的解耦，提高可移植性。 | 例：STM32 中可指向I2C_HandleTypeDef，Linux 中可指向 SPI 设备的 fd，驱动读写时通过该指针访问具体硬件参数。 |
info |
uint8_t |
警告 / 信息状态存储作用：记录非致命的运行警告（如参数配置不合法、通信轻微异常、配置未生效等），供用户排查问题（不影响传感器基本运行）。 | 区别于 "错误码"，仅用于提示（如配置值超出硬件范围时标记为 0x01）。 |
intf |
enum bmi2_intf |
通信接口类型作用：指定传感器与主控的通信方式（枚举值：BMI2_INTF_I2C/BMI2_INTF_SPI），驱动根据该值选择对应的通信协议逻辑。 |
核心区分 I2C/SPI，两种接口的读写时序、地址格式不同，需通过该参数适配。 |
intf_rslt |
BMI2_INTF_RETURN_TYPE |
接口操作返回结果作用：存储最近一次读写操作的错误码（如成功、I2C 超时、SPI 通信失败、寄存器地址错误），是定位通信层问题的核心。 | 自定义类型（通常为 int8_t），0 表示成功，负数表示错误（如 - 1 = 超时，-2 = 地址错误）。 |
dummy_byte |
uint8_t |
哑字节（占位 / 填充）作用：适配 SPI/I2C 接口切换的协议时序，SPI 读操作时需发送 1 个无用字节满足时序（I2C 无需使用）。 | SPI 读流程：先发送寄存器地址 → 发送 dummy_byte → 接收数据，该参数用于填充这一步的无用字节。 |
resolution |
uint8_t |
FOC（力传感 / 数据分辨率）配置作用：设置加速度计 / 陀螺仪的测量分辨率（如 16 位 / 14 位），分辨率越高，数据精度越高，但可能降低输出速率。 | FOC（Force-sensing Omni-directional Controller）是 BMI270 的力传感特性，该参数也服务于该功能的精度配置。 |
read_write_len |
uint16_t |
单次读写长度作用：指定单次通信的最大 / 默认字节数（如读取加速度计 X/Y/Z 轴数据需 6 字节），避免单次读写过长导致超时，优化通信效率。 | 例：设置为 6 则单次读取 3 轴加速度计数据，设置为 8 则可同时读取加速度计 + 温度数据。 |
load_status |
uint8_t |
配置文件加载状态作用：记录传感器固件 / 校准数据 / 功能配置文件的加载状态（0 = 未加载，1 = 加载中，2 = 加载完成，3 = 加载失败）。 | 配置文件是传感器正常工作的基础，该参数用于跟踪加载流程，失败时需重新加载。 |
config_file_ptr |
const uint8_t * |
配置文件缓冲区指针作用：指向存储传感器配置数据（固件参数、校准系数、功能配置表）的内存地址，驱动从该地址读取数据并写入传感器寄存器完成初始化。 | 配置文件通常是芯片厂商提供的二进制文件，包含出厂校准、算法参数等关键数据。 |
page_max |
uint8_t |
寄存器最大页号作用：BMI270 的寄存器按 "页" 划分（如页 0 = 基础配置，页 1 = 中断配置），该参数限制驱动访问的页范围，防止越界。 | 例：BMI270 最大页号为 0x05，访问 0x06 则触发错误。 |
input_sens |
uint8_t |
输入型功能最大数量作用：限制 "原始数据类功能"（如加速度计、陀螺仪、温度原始数据）的配置上限，避免超出硬件能力。 | 输入功能：作为算法的原始输入，而非最终输出（如步数、姿态角）。 |
out_sens |
uint8_t |
输出型功能最大数量作用：限制 "算法处理后功能"（如步数、敲击检测、姿态角）的配置上限，管理硬件资源分配。 | 输出功能：传感器内部算法处理后直接输出的结果，需占用硬件算力 / 内存。 |
aux_man_en |
uint8_t |
辅助通信手动使能作用：使能 / 禁用 BMI270 的辅助接口（可连接磁力计等外部传感器），1 = 使能，0 = 禁用。 | 辅助接口用于扩展传感器功能（如 IMU + 磁力计实现 9 轴融合）。 |
aux_man_rd_burst_len |
uint8_t |
辅助通信突发读取长度作用：配置通过辅助接口读取外部传感器数据时的单次 "突发读取" 字节数，优化通信效率（减少多次小批量读取）。 | 例：设置为 10 则单次读取外部磁力计 10 字节数据，而非分 10 次读 1 字节。 |
feat_config |
const struct bmi2_feature_config * |
功能输入配置数组指针作用：指向各功能的基础配置结构体（如加速度计量程 ±2g/±8g、陀螺仪采样率 100Hz/1000Hz、低通滤波参数）。 | 每个数组元素对应一个功能（如加速度计），驱动通过该指针加载初始化配置。 |
feat_output |
const struct bmi2_feature_config * |
功能输出配置数组指针作用：指向各功能的输出参数配置（如数据输出格式、中断触发条件、输出速率）。 | 例：配置步数检测功能的输出为 "每 10 步触发一次中断"。 |
remap |
struct bmi2_axes_remap |
轴重映射结构体作用：解决传感器物理安装与逻辑轴不一致的问题（如倒装 / 侧装），重新映射 X/Y/Z 轴的方向 / 顺序，让输出数据与实际物理坐标系一致。 | 无需修改上层算法，仅通过该结构体适配硬件安装姿态。 |
sens_en_stat |
uint64_t |
传感器使能状态标志（位域）作用：用 64 位的每 1bit 表示一个功能的使能状态（如 bit0 = 加速度计使能，bit1 = 陀螺仪使能，bit2 = 步数检测使能）。 | 64 位可支持大量功能（如 BMI270 的 20 + 种功能），快速查询 / 修改功能启用状态。 |
read |
bmi2_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) |
write |
bmi2_write_fptr_t |
写函数指针作用：指向用户实现的 "向传感器寄存器写数据" 的函数，原理同read。 |
是驱动与硬件写操作的核心接口，适配 STM32/Linux 等不同平台的底层写逻辑。 |
delay_us |
bmi2_delay_fptr_t |
微秒级延迟函数指针作用：指向用户实现的微秒延迟函数（如 STM32 的HAL_Delay_us、Linux 的usleep），用于寄存器写入后等待数据生效。 |
传感器部分寄存器写入后需几十微秒延迟，否则读取数据会错误。 |
gyr_cross_sens_zx |
int16_t |
陀螺仪交叉灵敏度补偿值（Z 轴对 X 轴）作用：修正陀螺仪轴间干扰（如 X 轴旋转时 Z 轴检测到微小信号），提高陀螺仪测量精度。 | 出厂校准值，驱动读取后用于数据补偿，是硬件精度优化的关键。 |
gyro_en : 1 |
uint8_t（位域） |
陀螺仪使能标志（仅 1 位）作用：专门用于 CRT（连续旋转跟踪）功能的使能 / 中止，位域设计节省内存。 | 1=CRT 功能中陀螺仪使能，0 = 禁用；仅占 1bit，比普通 uint8_t 节省 7bit 内存。 |
aps_status |
uint8_t |
高级省电模式（APS）状态作用：存储 APS 模式当前状态（0 = 禁用，1 = 模式 1，2 = 模式 2），CRT 功能的运行策略会根据 APS 状态调整（如低功耗下降低采样率）。 | APS 是 BMI270 的低功耗特性，平衡功耗与性能。 |
variant_feature |
uint16_t |
变体特性使能标志作用：使能特定芯片变体的专属功能（如部分 BMI270 支持 CRT，基础版不支持），每 1bit 对应一个变体功能。 | 适配不同批次 / 版本的 BMI270，提高驱动兼容性。 |
config_size |
uint16_t |
配置文件大小作用：记录config_file_ptr指向的配置文件总字节数，驱动加载时确认读取长度，避免越界或读取不完整。 |
配置文件通常为几百字节，该值是加载完整性校验的关键。 |
get_wakeup_config |
bmi2_wake_up_fptr_t |
获取唤醒配置函数指针作用：指向读取 "唤醒功能配置" 的函数（如唤醒阈值、唤醒源、唤醒延迟）。 | 例：查询 "加速度计阈值超过 2g 时唤醒主控" 的当前配置。 |
set_wakeup_config |
bmi2_wake_up_fptr_t |
设置唤醒配置函数指针作用：指向配置唤醒功能的函数，用于自定义唤醒条件（如设置唤醒阈值为 1.5g）。 | BMI270 的低功耗核心功能，主控休眠时由传感器唤醒。 |
get_tap_config |
bmi2_tap_fptr_t |
获取敲击配置函数指针作用：指向读取 "轻敲 / 双击检测" 配置的函数（如检测阈值、时间窗口、轴选择）。 | 例：查询双击检测的时间间隔是否为 500ms。 |
set_tap_config |
bmi2_tap_fptr_t |
设置敲击配置函数指针作用：指向配置敲击检测的函数，自定义敲击识别规则。 | 智能穿戴设备常用功能（如双击亮屏）的核心配置接口。 |
map_int |
struct bmi2_map_int * |
中断映射结构体指针作用：指向 "功能 - 中断引脚" 映射关系（如敲击检测映射到 INT1，步数计数映射到 INT2）。 | 管理传感器 2 个中断引脚的功能分配，适配不同应用场景。 |
sens_int_map |
uint8_t |
最大中断映射数量作用：限制可映射到中断引脚的功能总数（如最多 8 个），防止超出硬件能力。 | BMI270 硬件仅支持有限的中断映射，该参数避免配置越界。 |