简介面向嵌入式开发者和电子爱好者的 STM32F103HMC5883L 三轴磁力计程序包可解决地磁测量、电子罗盘与姿态参考系统中的传感器驱动和方位解算问题。压缩包共 201 个文件大小 3.32MB涵盖 .c/.h 源代码、.uvproj/.uvopt 工程配置、编译生成的 .hex/.axf/.map 固件与调试文件以及部分 .bak 备份方便在 Keil MDK 中直接编译烧录和追溯修改。目前已有 3129 人学习浏览程序核心包括 I2C 总线初始化、HMC5883L 寄存器读写、XYZ 三轴磁场数据转换与基于 atan2 的角度计算并涉及数据格式和标度因子处理覆盖从原始数据到最终航向角的完整链路。同时包含 STM32 标准外设库相关源码帮助理解芯片时钟、GPIO 与通信外设的配置方法整体目录结构清晰可直接作为传感器应用开发的基础模板。1. 从“走不直的小车”说起STM32F103 HMC5883L 到底解决了什么如果你的轮式机器人走直线时总往一边偏编码器计数正确、电机转速一致可实际轨迹还是画歪问题多半不在轮子上而在“你不知道车头朝向哪里”。STM32F103 HMC5883L 这种组合就是给嵌入式系统补上一只“电子罗盘眼”HMC5883L 是一颗 I2C 接口的三轴磁力计能感知地磁场在三个轴上的分量配合 STM32F103 做数学运算就能在几十行代码内输出当前航向角。它解决的不是“走多快”而是“朝哪走”适合做 AGV 小车导航、机器人底盘闭环、手持设备指向、气象站风向标等场景。新手可以用它第一次跑通 I2C 传感器驱动熟手则能用它快速验证一套低成本的航向参考方案。2. HMC5883L 的寄存器与 I2C 驱动先让芯片吐出原始数据2.1 关键寄存器一览增益、采样率、模式选错了会怎样HMC5883L 是一颗很简单的外设寄存器总共就那么十几个真正每次都要打交道的不到五个。我当初读完数据手册第一反应是“这芯片比 IMU 好伺候多了”但实际调的时候发现寄存器配置选不对后面算出来的角度全是玄学。先看三个必须配置的控制寄存器寄存器地址位域作用常用值配置寄存器 A0x00AVG[7:5] 采样平均次数DO[4:2] 数据输出速率MS[1:0] 测量模式决定噪声水平和刷新率0x70 8次平均 15Hz 正常测量配置寄存器 B0x01GN[7:5] 增益设置决定量程与分辨率0x20 ±1.3Ga1090 LSB/Gauss模式寄存器0x02MD[1:0] 工作模式连续测量、单次测量、空闲0x00 连续测量模式配置寄存器 A 里最容易被忽略的是采样平均次数。8 次平均能明显压低输出噪声但代价是等效输出频率变低如果做航向控制15Hz 的输出率配上 8 次平均是大多数情况下的稳妥选择。配置寄存器 B 的增益决定了测量范围增益越高分辨率越好但越容易饱和。HMC5883L 的量程从 ±0.88Ga 到 ±8.1Ga 共 8 档室内环境如果周围有电机、变压器或铁架±0.88Ga 那一档很容易把输出顶到 32767 附近。2.2 为什么先放弃 STM32F103 的硬件 I2C这是我在这个项目上踩的第一个坑。STM32F103 的硬件 I2C 外设用起来让人头大事件标志的状态机逻辑复杂很多人照着参考代码写完后发现主设备偶尔卡在忙标志上只能复位外设。我做了几年嵌入式在这颗芯片上从来不用硬件 I2C 接传感器而是用 GPIO 软件模拟 I2C。原因有三个一是软件 I2C 时序完全可控出了问题可以通过逻辑分析仪直接量引脚波形二是引脚可以随便映射到任意 GPIO画 PCB 时不用为了 I2C 功能复用绕线三是 HMC5883L 的 I2C 时钟最高支持 400kHz而软件模拟跑 100kHz 完全够用逻辑简单反而更可靠。软件 I2C 的电气连接有个硬性要求SCL 和 SDA 两根线都要接上拉电阻到 3.3V典型值 4.7kΩ。HMC5883L 的 VCC 供电范围是 2.16V 到 3.6V跟 STM32F103 的 3.3V 电平可以直接对接。原理图里把传感器的 VCC 单独加一颗 100nF 去耦电容靠近芯片引脚放比什么软件滤波都管用。2.3 可复用的软件 I2C 驱动代码初始化与读写下面这套代码是我在多个项目里复用的模板 GPIO 用 PB6/PB7你也可以随意换引脚。关键在于 SDA 线在输出和输入之间切换所以我把读引脚和写引脚都做了宏定义。/* 软件 I2C 引脚定义根据实际原理图修改 */ #define I2C_SCL_GPIO GPIOB #define I2C_SCL_PIN GPIO_Pin_6 #define I2C_SDA_GPIO GPIOB #define I2C_SDA_PIN GPIO_Pin_7 #define SCL_H() GPIO_SetBits(I2C_SCL_GPIO, I2C_SCL_PIN) #define SCL_L() GPIO_ResetBits(I2C_SCL_GPIO, I2C_SCL_PIN) #define SDA_H() GPIO_SetBits(I2C_SDA_GPIO, I2C_SDA_PIN) #define SDA_L() GPIO_ResetBits(I2C_SDA_GPIO, I2C_SDA_PIN) #define SDA_READ() GPIO_ReadInputDataBit(I2C_SDA_GPIO, I2C_SDA_PIN) /* 延时函数模拟 I2C 在 100kHz 左右SCL 半周期约 5us */ static void i2c_delay(void) { volatile uint32_t i 8; while (i--); } /* I2C 起始条件SCL 高电平时SDA 产生下降沿 */ static void i2c_start(void) { SDA_H(); SCL_H(); i2c_delay(); SDA_L(); i2c_delay(); SCL_L(); } /* I2C 停止条件SCL 高电平时SDA 产生上升沿 */ static void i2c_stop(void) { SDA_L(); SCL_H(); i2c_delay(); SDA_H(); i2c_delay(); } /* 写一个字节高位先出每写完一位拉低 SCL */ static void i2c_write_byte(uint8_t dat) { for (int i 0; i 8; i) { if (dat 0x80) { SDA_H(); } else { SDA_L(); } dat 1; SCL_H(); i2c_delay(); SCL_L(); i2c_delay(); } } /* 读一个字节ack 参数0 表示主设备发 ACK1 表示发 NACK */ static uint8_t i2c_read_byte(uint8_t ack) { uint8_t dat 0; GPIO_InitTypeDef gpio; /* 把 SDA 切到输入模式 */ gpio.GPIO_Pin I2C_SDA_PIN; gpio.GPIO_Mode GPIO_Mode_IN_FLOATING; GPIO_Init(I2C_SDA_GPIO, gpio); for (int i 0; i 8; i) { SCL_H(); i2c_delay(); dat (dat 1) | (SDA_READ() ? 1 : 0); SCL_L(); i2c_delay(); } /* 切回输出模式发送应答位 */ gpio.GPIO_Mode GPIO_Mode_Out_PP; gpio.GPIO_Speed GPIO_Speed_50MHz; GPIO_Init(I2C_SDA_GPIO, gpio); if (ack) { SDA_H(); } else { SDA_L(); } SCL_H(); i2c_delay(); SCL_L(); SDA_H(); i2c_delay(); return dat; }这段代码的逻辑要点起始和停止条件必须严格按照 I2C 时序来做SCL 高电平期间 SDA 的变化才算起始/停止否则会被从设备忽略。i2c_read_byte 里读最后一个字节时要回 NACK告诉从设备“不用再发了”否则从设备会一直拉着 SDA 不放导致总线恢复不过来。紧接着是 HMC5883L 的初始化函数。我把寄存器配置和自检放在一起返回 0 代表设备正常#define HMC5883L_ADDR_W 0x3C /* 器件地址 0x1E 左移一位写操作 */ #define HMC5883L_ADDR_R 0x3D /* 读操作 */ uint8_t hmc5883l_init(void) { /* 写入配置寄存器 A8次平均、15Hz输出率、正常测量 */ uint8_t reg_a 0x70; /* 写入配置寄存器 B±1.3Ga 量程1090 LSB/Gauss */ uint8_t reg_b 0x20; /* 模式寄存器连续测量 */ uint8_t mode 0x00; uint8_t id_a, id_b, id_c; /* 读识别寄存器 0x0A~0x0C正常芯片应读到 H 4 3 */ hmc5883l_read_bytes(0x0A, id_a, 1); hmc5883l_read_bytes(0x0B, id_b, 1); hmc5883l_read_bytes(0x0C, id_c, 1); if (id_a ! H || id_b ! 4 || id_c ! 3) { return 1; /* 设备不存在或地址不对 */ } hmc5883l_write_reg(0x00, reg_a); hmc5883l_write_reg(0x01, reg_b); hmc5883l_write_reg(0x02, mode); return 0; }初始化函数里先读识别寄存器这一步值得保留。很多时候芯片没反应不是焊接问题而是你买到的物料是兼容芯片识别寄存器内容和 HMC5883L 不一样读出来不对就能立刻知道“此芯片非彼芯片”。如果返回 1不要急着查代码先用万用表量传感器 VCC 和 GND再量 SCL/SDA 是否被拉低到 0。读三轴原始数据的核心逻辑放在下面。HMC5883L 的数据寄存器从 0x03 开始连续 6 个字节依次是 X 高、X 低、Y 高、Y 低、Z 高、Z 低全部是有符号 16 位整数uint8_t hmc5883l_read_raw(int16_t *mx, int16_t *my, int16_t *mz) { uint8_t buf[6]; uint8_t reg 0x03; /* 先发器件写地址和寄存器地址 */ i2c_start(); i2c_write_byte(HMC5883L_ADDR_W); if (i2c_wait_ack()) { i2c_stop(); return 1; } i2c_write_byte(reg); i2c_wait_ack(); /* 重新发送起始条件切换为读模式 */ i2c_start(); i2c_write_byte(HMC5883L_ADDR_R); i2c_wait_ack(); /* 连读 6 字节最后一字节回 NACK */ for (int i 0; i 6; i) { buf[i] i2c_read_byte(i 5 ? 1 : 0); } i2c_stop(); *mx (int16_t)((buf[0] 8) | buf[1]); *my (int16_t)((buf[2] 8) | buf[3]); *mz (int16_t)((buf[4] 8) | buf[5]); return 0; }这段代码里 i2c_start 用了两次第二次叫“重复起始条件”。有些从设备对“先停止再起始”的写法兼容性不好重复起始是标准 I2C 协议推荐的做法。数据拼接时一定要先读高字节HMC5883L 的数据寄存器是高字节在前搞反了算出来的角度会在某个象限突然翻转。3. 从原始数据到航向角atan2、磁偏角和坐标系对齐3.1 航向角公式为什么用 atan2 而不是 atan拿到三轴原始数据以后求航向角的核心是一行公式heading atan2(Y, X)。这里 X 是传感器 X 轴方向的地磁分量Y 是 Y 轴分量。用 atan2 而不是 atan 的原因是 atan2 能根据 X 和 Y 的符号自动判断角度落在哪个象限输出范围是 -180° 到 180°省去手动补象限角的麻烦。但这里有一个前提条件传感器在 PCB 上的安装方向必须和你的设备坐标系对齐。如果芯片的 Y 轴朝着车头而你想让 0° 表示车头朝北公式就要改成 atan2(X, Y)否则会出现“车头朝北显示 90°”这种方向错位。我一般先在代码里写死一个方向定义注释/* 安装约定HMC5883L 的 X 轴朝车头右侧Y 轴朝车头前方Z 轴朝上 */实际项目里经常出现 PCB 转 90° 安装的与其在硬件上别扭不如在软件里做个轴交换把读到的 X 赋给公式里的 Y或者把 Y 取反再代入。这个操作放在读原始数据的下一行别改驱动层。3.2 输出平滑与一阶低通滤波HMC5883L 即使设置了 8 次平均静止时的输出也会有少量抖动算出的航向角在 0.1° 到 0.3° 之间跳。如果你的电机在转这个抖动会被放大到几度。最简单的处理是加一阶低通滤波float heading_filtered 0.0f; uint8_t first_sample 1; float lowpass_heading(float new_heading, float alpha) { if (first_sample) { heading_filtered new_heading; first_sample 0; } else { heading_filtered alpha * new_heading (1.0f - alpha) * heading_filtered; } return heading_filtered; }alpha 取 0.2 到 0.4 之间比较常见。alpha 越大响应越快噪声也越大alpha 越小越平滑但转向时会有明显滞后。还有一个容易被忽视的细节航向角在 359° 和 0° 之间切换时直接做低通会把 359° 和 1° 平均成 180°这是完全错误的。处理办法是先算两个角度的差值如果差值大于 180°把新值加 360° 再滤波float diff new_heading - heading_filtered; if (diff 180.0f) new_heading - 360.0f; if (diff -180.0f) new_heading 360.0f;我见过不止一个人在这个边界上翻车小车原地顺时针转一圈显示的角度从 0° 平滑到 359°中间某处突然跳回 180°其实就是 360° 跨越没有处理。3.3 磁偏角补正与完整航向角计算地磁北极和地理北极不是同一个点不同城市的磁偏角差异能到 10° 以上。以国内为例东部地区磁偏角在 -4° 到 -8° 之间西偏西部某些区域可能到 5° 左右。这个值可以在公开的地磁模型网站按经纬度查或者用设备在当地实测校准得到。磁偏角补正的符号规则简单记如果查到的磁偏角是西偏declination 为负例如 -5°你需要把传感器读到的角度减去 5° 的绝对值如果是东偏则加上。用代码表示#define DECLINATION_DEG -5.0f /* 示例值当地西偏 5° */ float calc_heading(int16_t mx, int16_t my) { float heading atan2((float)my, (float)mx) * 180.0f / 3.14159265f; if (heading 0) { heading 360.0f; } heading DECLINATION_DEG; if (heading 0) heading 360.0f; if (heading 360.0f) heading - 360.0f; return heading; }这个函数输出 0° 到 360° 的角度0° 表示车头指向地理北。如果你只需要相对方向比如控制小车保持某个航向角磁偏角可以暂时不补因为控制量是差值偏角会抵消掉。但如果你要把角度和地图坐标对应磁偏角必须加上不然导航路径会整体旋转一个角度。4. 校准是精度的一半圆规画圆法与椭圆修正4.1 硬铁校准原理与操作步骤未校准的 HMC5883L 直接测会发现一个典型现象把设备水平转一圈输出的 X 和 Y 组成一个圆心不在原点的圆。这个偏移来自电路板上的走线磁场、螺丝、电池等固定磁性物体它们叠加在真实地磁场上产生一个恒定偏置叫硬铁误差。校准的目的就是把圆心拉回原点。常见做法是“圆规画圆法”保持设备水平慢慢绕垂直轴转至少一整圈期间连续采样 X 和 Y记录最大值最小值然后int16_t x_min 32767, x_max -32768; int16_t y_min 32767, y_max -32768; /* 旋转过程中持续采样每采一次更新极值 */ void cal_update(int16_t mx, int16_t my) { if (mx x_min) x_min mx; if (mx x_max) x_max mx; if (my y_min) y_min my; if (my y_max) y_max my; } /* 旋转结束后计算偏移量 */ int16_t cal_offset_x (x_max x_min) / 2; int16_t cal_offset_y (y_max y_min) / 2;校准时的操作细节会影响精度旋转速度要慢保证每 10° 至少采到一个点设备必须保持水平倾斜超过 10° 会导致椭圆明显变形算出来的偏移全是错的旋转过程中人和附近不要有大块金属移动否则会把干扰当成本底。采集完成后把 cal_offset_x 和 cal_offset_y 存进 STM32F103 的内部 Flash上电时读出来每次读原始数据后先减掉偏移再做后续计算。4.2 软铁校准当圆变成椭圆硬铁校完以后如果数据点组成的是椭圆而不是正圆说明存在软铁误差即某些方向上的地磁被附近的铁磁性材料“放大”或“压缩”了。软铁误差用圆规画圆法处理不了需要做椭圆拟合得出长短轴比例再按比例缩放各轴。对大多数小车项目软铁误差影响不大可以忽略但如果你的 PCB 上传感器旁边有大面积铺铜、屏蔽罩或者铁质外壳就必须处理。工程上最简单的近似做法是校完硬铁后把旋转采集得到的 X 轴极差和 Y 轴极差的比值作为缩放因子/* 假设硬铁偏移已校正raw 是减去 offset 后的值 */ float scale_x (float)(y_max - y_min) / (float)(x_max - x_min); float corrected_x raw_x * scale_x;这个近似做法假设椭圆长短轴与传感器 XY 轴对齐实际中轴有夹角的话效果会打折扣。要求高的话需要用最小二乘法做椭圆拟合求出旋转角和比例矩阵那一套线性代数实现起来偏重对入门项目性价比不高。先把硬铁校正好通常能把航向精度从 ±15° 提升到 ±3° 以内这就足够用了。4.3 校准参数的存储与流水线验证偏移量算出来以后怎么存是个工程问题。常见做法有两种直接存在 STM32F103 内部 Flash 的最后一个扇区或者用一个外接 EEPROM。前者不需要额外芯片但要注意 Flash 擦写寿命约 1 万次校准不会频繁做所以没问题。/* 用内部 Flash 存储校准参数放在最后一个扇区 */ #define CAL_FLASH_ADDR 0x0800F800 /* 以 64KB Flash 的芯片为例 */ typedef struct { int16_t offset_x; int16_t offset_y; float scale_x; uint16_t crc; } cal_param_t;存之前算一个简单的 CRC读出来以后校验 CRC不对就说明 Flash 里没有有效参数需要触发校准流程。我习惯把“进入校准模式”做成一个独立函数串口收到特定指令后LED 闪烁提示操作者开始旋转设备旋转完成后自动把参数算好并存档。这一步看起来简单但在现场调试时非常好用不用每次改代码重新烧录。校准做完的验证方法也是固定的装好设备旋转一周把计算出的航向角通过串口发给上位机画成曲线应该是一条接近直线的斜坡斜率为正、从 0° 走到 360°。如果曲线在某处出现台阶或反向说明校准或轴方向定义有问题别急着调参数先检查安装方向。5. HMC5883L 的常见坑与排查从读不到设备到角度漂移5.1 I2C 总线上找不到设备地址确认没问题但通信失败现象初始化函数返回 1逻辑分析仪上 SCL 有波形SDA 也有应答信号但识别寄存器读出来的不是H、4、3。原因最常见的是供电问题。HMC5883L 的 VCC 如果低于 2.16V芯片不会工作而 STM32F103 的 3.3V LDO 输出如果带载能力不足上电瞬间会被拉低。另外有些兼容芯片的识别寄存器内容和原厂不一样读出来是别的值但功能正常。解决第一步用万用表量 VCC 对地电压确保 3.3V 稳定第二步把 I2C 速度降到 50kHz 左右再试有些兼容芯片对时序要求更严格第三步是确认焊接这类 LGA 封装的传感器引脚在芯片底部虚焊非常隐蔽用放大镜仔细检查或者热风枪重新吹一遍。如果上拉电阻没焊SDA 会被从设备拉死表现为总线一直忙。5.2 角度在某几个方向突然跳变数据接近 ±32767现象设备旋转时航向角大体正确但转到某个方向会突然跳到异常值或者原始数据 X、Y 中有某个值长时间停在 32767 附近。原因这是磁饱和。地磁场强度大约 0.5 到 0.6 Gauss但周围如果有电机、喇叭、电流较大的导线局部磁场能轻松超过 1 Gauss。配置寄存器 B 选的高增益档比如 ±0.88Ga分辨率高但余量太小信号一饱和输出就被钳位了。解决把配置寄存器 B 改成 0x20±1.3Ga或更低增益档。具体判断方法是把串口打印的原始数据转成 Gauss读到的 LSB 数除以 1090±1.3Ga 档的灵敏度。如果最大值乘以灵敏度接近满量程就换下一档。这个坑的隐蔽之处在于不是所有方向都饱和只在设备转到某个角度时才触发很容易被误判成校准问题。5.3 电机一转数据就乱静止时正常现象设备静止时航向角稳定电机一启动角度开始随机漂移甚至会来回跳几十度。原因电机电刷或 PWM 驱动产生的变化磁场干扰了传感器。HMC5883L 本身没有屏蔽设计对临近的交变磁场非常敏感。解决硬件上把传感器尽量远离电机和功率线传感器下方 PCB 不要走大电流回路电源加一颗磁珠再加 10uF 和 100nF 电容组合。软件上在电机 PWM 输出期间暂停采样等 PWM 关断后再读配合前面说的低通滤波效果立竿见影。如果电机必须持续转采样时刻避开 PWM 周期内的开关瞬间也能明显改善。5.4 上电后第一次读到的数据是全 0 或明显错误现象程序跑起来后前几组数据全是 0过几百毫秒才恢复正常或者复位后读到一组乱码再读就正常了。原因HMC5883L 上电后需要最多 5ms 的稳定时间连续测量模式下也有“首个数据点可能不完整”的问题。你如果在模式寄存器写完后立刻读数据读到的可能是芯片内部状态还没稳定时的垃圾值。解决初始化函数末尾加一个 50ms 延时或者读数据之前先轮询状态寄存器 0x09 的第 0 位该位置 1 才表示新数据就绪uint8_t status; do { hmc5883l_read_bytes(0x09, status, 1); } while ((status 0x01) 0);这个轮询操作对连续测量模式尤其重要因为连续模式的数据更新是异步的不带 DRDY 判断直接读有可能读到新旧数据混在一起的中间态。加了这行判断以后数据稳定性提升非常明显。还有一点改完配置寄存器后芯片需要几个输出周期才能稳定所以校准和正式运行之间留 200ms 的预热时间比较稳妥。5.5 航向角整体偏移一个固定角度校准做完也一样现象所有方向的角度都同时偏移同一个值大约 5° 到 15°而且校准后依然存在。原因磁偏角没有补或者 PCB 上的元器件比如螺丝、电池产生了相对固定的硬铁偏置但旋转校准做得不够完整旋转范围不足一整圈或者速度太快采样密度不够。解决先用 4.3 节的验证方法确认输出曲线是否平滑如果平滑但整体平移那就是磁偏角问题按 3.3 节补上当地磁偏角。如果曲线在某个象限明显上凸或下凹说明椭圆拟合没做好需要增大采样量。以我自己的经验校准旋转至少做两圈慢速旋转每圈 20 秒以上得到的数据才算有用。6. 让航向更稳倾斜补偿与和运动传感器的融合HMC5883L 单独使用时要求设备保持水平一旦倾斜航向角误差会急剧变大。给系统加上加速度计比如把 MPU6050 的加速度部分利用起来做倾斜补偿能把这个限制放宽到 ±30° 以内。核心思路是用加速度计算出俯仰角 pitch 和横滚角 roll把磁力计的三轴数据投影回水平面再计算航向角float pitch atan2f(-acc_x, sqrtf(acc_y * acc_y acc_z * acc_z)); float roll atan2f(acc_y, acc_z); float mag_x_h mx * cosf(pitch) my * sinf(roll) * sinf(pitch) mz * cosf(roll) * sinf(pitch); float mag_y_h my * cosf(roll) - mz * sinf(roll); float heading atan2f(-mag_y_h, mag_x_h) * 180 / PI;这里的符号取决于你用的加速度计坐标定义不同传感器轴方向不一样需要自己在调试时验证正负号。我拿到新板子会先把板子固定在一个已知方向的支架上分别做水平、前倾 30°、左倾 30° 三个姿态看输出角度是否基本不变这一步能快速确认公式的坐标系是否一致。如果想要更高的动态稳定性可以在磁力计和加速度计基础上加入陀螺仪做互补滤波。陀螺仪短时间内非常准但会积分漂移磁力计和加速度计长时间稳定但短期噪声大。互补滤波把两者结合是低算力 MCU 上最划算的姿态融合方案float fused_heading 0.98f * (fused_heading gyro_z * dt) 0.02f * mag_heading;0.98 和 0.02 是工程上常用的权重系数实际调参时看你更信任谁噪声主要在高频就把磁力计权重调低漂移明显就把磁力计权重调高。这套方案不需要跑卡尔曼滤波器普通 STM32F103 主频 72MHz 跑起来绰绰有余也是我目前做机器人航向的首选结构。我自己的习惯是每次拿到新打的板子先不接电机把传感器焊好刷一个最小例程手持板子在空中慢速画几圈“8”字同时把原始数据通过串口画成轨迹。轨迹圆不圆、圆心偏多少一眼就能看出焊接、布局和芯片好坏。这个动作已经帮我避开了至少三次“传感器坏了但程序看着没问题”的无效调试。希望这个办法对你有用航向传感器的精度不是调出来的是从布线和校准里省出来的。本文还有配套的精品资源点击获取