Amfitrack用户指南

套件包装说明

```

Amfitrack 数据包与结构体说明 (Package Description)

本页面详细描述了系统接收的各个数据包 (Package) 及其包含的具体内容与结构体定义。

一、 核心数据包 (Measurement Packages)

1. Sensor Package (传感器数据包)

包含位置信息、IMU 数据及传感器状态。PayloadType == 0x1A

struct lib_AmfiProt_Amfitrack_Sensor_Measurement_t

成员名称 数据类型 描述 (Description)
pose lib_AmfiProt_Amfitrack_Pose_24b_t 位置和姿态信息 (Position and orientation)
sensor_status uint8_t 传感器状态，解析参考 sensorStatus 结构
source_id uint8_t 接收到的发射源 ID (Received source ID)
calculation_id uint16_t 计算序列号 ID (Calculation ID)
imu_data lib_AmfiProt_Amfitrack_IMU_16b_t 惯性传感器数据 (IMU data)
magneto_data lib_AmfiProt_Amfitrack_magneto_16b_t 磁力计数据 (Magnetometer data)
temperature uint8_t 磁力计温度 (Magnetometer temperature)
sensor_state uint8_t 当前传感器状态 (参考 SensorState_t)
metal_distortion uint8_t 金属畸变程度 (0 = 畸变最小 | 255 = 畸变最大)
gpio_state uint16_t GPIO 状态
rssi int8_t 接收信号强度指示 (RSSI)
frame_id lib_AmfiProt_Amfitrack_FrameID_24b_t 帧序列号 ID (Frame ID)
Warning: doxygenenum: Cannot find enum “SensorState_t” in doxygen xml output for project “amfitrack” from directory: ../output/xml

2. Source Package (发射源数据包)

包含线圈电流、IMU 数据及状态信息。PayloadType == 0x24

struct lib_AmfiProt_Amfitrack_Source_Measurement_t

成员名称 数据类型 描述 (Description)
current_coil_x_in_mA
current_coil_y_in_mA
current_coil_z_in_mA		 float X / Y / Z 轴线圈电流 (单位: mA)
imu_data lib_AmfiProt_Amfitrack_IMU_16b_t IMU 数据
magneto_data lib_AmfiProt_Amfitrack_magneto_16b_t 磁力计测量数据
temperature uint8_t 磁力计温度
source_status uint8_t 发射源状态 (TODO)
source_state uint8_t 发射源运行状态位标：
Bit 1 == Phase modulation (相位调制)
Bit 2 == Frequency tune (频率调谐)
Bit 3 == Current tune (电流调谐)
Bit 4 == Crosstalk calibration (串扰校准)
Bit 5 == Offset coil enabled (偏置线圈启用)
rssi int8_t 接收信号强度指示 (RSSI)
frame_id lib_AmfiProt_Amfitrack_FrameID_24b_t 帧 ID (Frame ID)
voltage_coil_x_in_V
voltage_coil_y_in_V
voltage_coil_z_in_V		 float X / Y / Z 轴线圈电压 (单位: V)
voltage_boost_in_V float 内部升压电压 (Boost voltage)

3. Source Calibration (发射源校准数据包)

包含发射端底层频率与相位补偿参数。PayloadType == 0x23

struct lib_AmfiProt_Amfitrack_Source_Calibration_t

成员名称 数据类型 描述 (Description)
frequency_x_in_Hz
frequency_y_in_Hz
frequency_z_in_Hz		 float X / Y / Z 轴线圈共振频率 (单位: Hz)
calibration_source_coil_x
calibration_source_coil_y
calibration_source_coil_z		 float X / Y / Z 轴线圈强度校准值
phase_modulation_offset_x
phase_modulation_offset_y
phase_modulation_offset_z		 float X / Y / Z 轴线圈相位调制偏移量（供 Sensor 接收端解算使用）

二、 内部结构体定义 (Members Reference)

1. Pose 数据 (位置与姿态)

struct lib_AmfiProt_Amfitrack_Pose_24b_t

成员名称 类型 解析说明与转换公式
position_x[3]
position_y[3]
position_z[3]		 uint8_t 原始数据 LSB = 0.01mm。
转换为米 (m)：Value / 100000
orientation_x[3]
orientation_y[3]
orientation_z[3]
orientation_w[3]		 uint8_t 原始数据 LSB = 1/1000000。
转换为单位四元数 (Unit Quaternion)：Value / 1000000

2. IMU 数据 (惯性传感器)

struct lib_AmfiProt_Amfitrack_IMU_16b_t

成员名称 类型 解析说明与转换公式
acceleration_X
acceleration_Y
acceleration_Z		 int16_t 4000mg 全量程。
转换为重力加速度 (g)：Value × 4 / (2^15 - 1)
rotation_X
rotation_Y
rotation_Z		 int16_t LSB = 70mdeg/s。
转换为弧度每秒 (rad/sec)：Value × 0.070 × (PI / 180)

3. Sensor Status (传感器运行状态)

struct sensorStatus

成员名称 类型 描述及枚举值
batteryLevel uint8_t 电池电量：0 == 满电 (Full), 1 == 正常 (OK), 2 == 低电量 (Low), 3 == 严重不足 (Critical)
batteryCharging bool 是否正在充电 (True / False)
SourceConnected bool 是否已连接到发射源 (True / False)
BFieldStatus uint8_t 磁场跟踪状态码：
0 == 正常跟踪 (Tracking)
1 == 跟踪不稳定 (Uncertain tracking)
2 == 丢失跟踪 (No tracking)
3 == 磁场过弱 (B field too low)
4 == 磁场过弱 / 异常状态 (B field too low)
5 == 发射线圈故障 (Source coil defect)
6 == 接收线圈故障 (Sensor coil defect)
Sync bool 是否接收到同步信号输入 (True / False)
```