# MCCompass

**Repository Path**: LOStacNet/mccompass

## Basic Information

- **Project Name**: MCCompass
- **Description**: 基于STM32G030的我的世界指南针，包含指北功能和定位指向功能，使用立创面板+EDA设计。受两个开源项目启发，基于STM单片机重构，便于学习和再开发，使用模块设计，便于制作。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-08-17
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开源我的世界指南针复刻

本项目对网上开源的我的世界指南针进行复刻，并添加一些自己的修改和功能。本项目尽量采用模块，降低制作难度。

作者：LO_StacNet

## 声明

本项目游戏素材具有一定版权风险，故项目开源需谨慎。

本文图片来自淘宝店铺和立创商城，有侵权风险。

## 介绍

本设计参考网络两位大佬的开源工程，并进行一些适应性改造，包括：

1. 灯珠替换为3528封装便于焊接
2. 电源管理、磁场传感、GPS使用模块，减少焊接需求
3. 更换主控为STM32G030，开发更便捷
4. 软件框架分层，移植和添加新功能更简单
5. 自动外设检测，没有GPS可以使用指北功能，没有磁场传感器还有地狱模式(指针乱转)

该指南针默认固件有以下功能：

1. 上电进入指北针模式，若相关外设缺失则进入地狱
2. 指北针模式下，指针指向北方，单击按钮切换到地狱，双击开始校准，长按切换到Home模式
3. Home模式下，指针指向家位置，单击设置当前位置为家，双击重置家位置为初始值，长按切换到指北针
4. 地狱模式下，单击切换回指北针，双击重置配置文件(家位置和校准值)
5. 按下按钮上电，重置配置文件(家位置和校准值)
6. 模式切换和校准时，显示中间红点的十字
7. Home模式第一次定位成功前，显示中间蓝点的十字

注意：

* 若有误差请进行校准，校准时屏幕长显示**中心红点十字**，注意让指南针**每个方向轴旋转**，让其每个轴都采到最大最小值
* Home模式重置后初始地址指向**时间广场**
* 切换到Home模式后显示**中心蓝点十字**，表示GPS正在定位，请移动到**开放场地**完成定位

## 项目结构

* 3D——存放外壳模型文件
* document——存放项目文档
* firmware——存放单片机固件
* hardware——存放PCB设计文件
* resource——存放指南针素材
* tools——存放素材处理取模脚本
* video——存放视频企划

## 元件选型

本节介绍各个元件的选择。

### 电源管理

**锂电池管理和5V供电**

电源管理直接使用淘宝成品充放电一体化模块，简化设计。

![image-20250607161623383](README.assets/image-20250607161623383.png)

**3V3供电**

3V3供电使用经典AMS1117-3.3V芯片，封装SOT-89，封装参考立创商城C5120796。

### 传感器

**磁场传感器**

磁场传感器定位方向，是实现指北功能的核心。

本设计使用GY-271 QMC5883L模块，便于焊接制作。由于L已经停产，市面上出现了5833P模块，比L便宜一点，但是寄存器和IIC地址都不一样，三轴方向不一样，读取要求也不一样，非常的坑。
更新：固件已支持QMC5883P。

![image-20250607171150736](README.assets/image-20250607171150736.png)



**GPS**

GPS模块获取位置信息，是实现定位指向功能的核心。

本项目使用ATGM336H模块。

![image-20250607171748386](README.assets/image-20250607171748386.png)

### 灯珠

常见的灯珠封装大小有SMD2x2mm(2x2mm)，SMD3538(3.5x2.8mm)，SMD3535(3.5x3.5mm)，SMD5050(5x5mm)，为控制体积、保证显示效果以及便于焊接，选择中等大小SMD3538(3.5x2.8mm)封装的灯珠，~~同时选择自带雾面的版本，不需要加柔光纸。~~(必须加柔光纸)

该型号灯珠可在淘宝搜索WS2812B-3528RGB找到，如果在立创商城上可以参考XL-3528RGBW-WS2812B，商品编号C2890364(不保证能正常运行)。

![{4CC41D9F-7892-4EF1-B116-AA371865F7A8}](README.assets/%7B4CC41D9F-7892-4EF1-B116-AA371865F7A8%7D.png)

### 主控

主控要求支持IIC，UART，单线数据输出，并最好支持单线数据DMA输出和低功耗。

选择STM32G030F6P6，该芯片主频64MHz，有一个ADC，2个IIC，3个SPI，两个USART以及DMA，符合本设计需求。正好淘宝也有该芯片的开发板，有硬件参考，调试也方便。

### 存储器

为保存配置信息，使用EEPROM存储数据。（虽然数据可以存储在flash中，但考虑到flash的寿命与其他限制，这里还是采用EEPROM。~~虽然Flash寿命应该用不完，但这里就是懒~~）。

这里选择AT24C02芯片即可。

### 接口和开关

**电源开关**

开关使用SS-12D00 立式柄长5MM，封装参考立创商城C22355741。

![image-20250609204032873](README.assets/image-20250609204032873.png)

**按钮**

按钮使用卧式弯插轻触开关，封装参考立创商城C2845277。

![image-20250607154716759](README.assets/image-20250607154716759.png)

**调试按钮**

主控还需要复位等调试按钮，使用3\*4\*2mm 立贴 轻触开关，封装参考立创商城C707339。

![image-20250609205742457](README.assets/image-20250609205742457.png)

**固定螺丝**

使用M2x6，头径4mm的螺丝，自攻和平螺丝均可。

![image-20250709015117451](README.assets/image-20250709015117451.png)

![image-20250709015154795](README.assets/image-20250709015154795.png)

## 硬件设计

本节介绍各个部分电路的设计。

### 像素设计

Minecraft中的指南针大小为14x12像素，其中共有40个像素为显示区域。

根据灯珠大小，设定一个像素显示区域为6x6mm，设定光栅厚度为1mm，那么可视为一个像素7mm，最终大小为98x84mm。

在文档层绘制像素框，设定矩形线宽为1mm，宽和高分别为7mm，则显示像素区域如图所示：

![image-20250608200103862](README.assets/image-20250608200103862.png)

整个范围如图所示：

![image-20250608200828449](README.assets/image-20250608200828449.png)

### 灯珠电路

WS2812灯珠数据信号的控制逻辑如下：

1. 每个灯珠有24bits颜色数据
2. 每次传输假设有10个灯珠数据，第一个灯珠会保留第一个数据，并将剩下的数据从DOUT发送
3. 间隔50us以上则判定为两次传输

基于上述特性，如果从IO依次发送一个数组，想要数组索引与灯珠顺序相同，设置灯珠顺序为从左到右从上到下排列，灯珠电路如下：

![image-20250609211206307](README.assets/image-20250609211206307.png)

每行设置一个100nF电容去噪，输入输出预留电阻位置用于调试。

### 电源管理

锂电池充放电和5V电源直接使用淘宝电源模块处理。该模块带一个typec接口，可以自动检测5V输入，当有输入时为充电模式，给锂电池进行充电，带保护；当没有5V输入时，切换到放电模式，锂电池放电。

![image-20250709013823569](README.assets/image-20250709013823569.png)

同时，再使用AMS1117输出3.3V电源即可。

### EEPROM

EEPROM使用24C02，用于存储校准信息和家位置坐标，连接到STM32的硬件IIC接口，电路图如下：

![image-20250709014012642](README.assets/image-20250709014012642.png)

### 单片机

单片机使用STM32G030F6P6，该单片机外部电路较为简单，只需要提供RST信号和下载接口即可。本设计中除了外设接口，还使用了USART2作为Debug输出，同时添加了LED用于显示程序状态。

![image-20250709014254174](README.assets/image-20250709014254174.png)

### 3D外壳

设计注意事项：

1. 电池型号为603450，厚6mm 34*50mm，注意预留空间
2. GPS天线需要最终朝上，注意设置固定位置
3. 固定孔统一使用M2*6 头厚0.8mm 头直径4mm自攻螺丝固定
4. 模块与板子并不在同一平面，注意预留位置
5. 光栅尽量窄，保证像素间距不要太大
6. 拨动开关位置、TypeC口、按键位置需要预留
7. 外壳厚度1.8mm

外壳分为前壳和后壳，前壳同时包含光栅。前壳、PCB、后壳通过M2螺丝孔进行连接。本设计使用的是M2x6，头径4mm规格的螺丝，自攻螺丝和普通螺丝均可。

### 面板设计

面板使用立创EDA 面板设计。首先根据像素大小，在板框层绘制外框，然后在打印层绘制出像素网格，然后根据对MC指南针素材的取色，设置每个像素的颜色。将显示区域在透明控制层标出。

![image-20250709015625727](README.assets/image-20250709015625727.png)

## 软件设计

本节介绍软件设计。

### 整体框图

![image-20250709021554786](README.assets/image-20250709021554786.png)

程序设计了一个简单的架构，首先是**BSP层封装了所有传感器的初始化和访问函数**，程序所有其他程序对硬件的访问都通过BSP提供的API进行。这样，当芯片变动或者传感器改变时，能最大限度的减少对主程序的改动。（这在后面遇到QMC5883L和P不同的坑时十分有用）

其次，由于该指南针有两种不同的模式，这里通过函数指针的形式运行不同的模式，避免出现添加模式需要修改主代码的情况。每个模式有一个Init函数和一个Run函数：

* **Init函数**：用于判断能否进入该模式(该模式需要的外设是否存在，如Home模式需要GPS外设和QMC外设)，并进行初始化，只在切换模式时运行一次
* **Run函数**：是模式的主while循环函数，该函数用于执行程序的主逻辑，在while中运行。

所有模式的函数通过两个数组管理，函数在数组的索引就是模式号，程序在主循环通过当前的模式号选择对应的Run函数运行。

框架的详细信息见代码，这里给出固件中的三种模式的流程图。

* 模式0-地狱模式-无条件进入，用于所有传感器没有的情况

![image-20250709023551875](README.assets/image-20250709023551875.png)

* 模式1-指北针模式-上电后默认模式，需要QMC外设

![image-20250709024655483](README.assets/image-20250709024655483.png)

* 模式2-Point Home模式-指向设定点，需要QMC+GPS

![image-20250709025651470](README.assets/image-20250709025651470.png)

### BSP层定义

BSP层用于分离底层数据IO与程序主要应用逻辑。在本项目中，需要实现以下几个BSP层的API。

#### LED Panel API

该API用于显示像素。

```c
uint8_t LED_PanelInit(void);
```

**函数名：**LED_PanelInit

**描述：**用于初始化SPI、DMA等相关外设，包括硬件初始化（使用CubeMX生成的则留空）以及设置初始界面。

**参数：**无

**返回值：**0——正常；1——初始化失败。

```c
uint8_t LED_PanelDisp(uint16_t pixel[]);
```

**函数名：**LED_PanelDisp

**描述：**将pixel中的数据刷新到LED上。如果上次刷新未完成，返回错误码。该函数构造要发送的数据，并通过SPI+DMA进行无阻塞刷新。

**参数：**

* `pixel`——要刷新的像素信息，固定长40个，RGB565格式

**返回值：**0——正常；1——设备忙(上次刷新未完成)；2——刷新失败。

#### GPS API

该API用于获取解析GPS数据信息。

```c
struct GPS_Data{
    float dlat;  //维度-北纬正南纬负
    float dlong; //经度-东经正西经负
    float dalt; //高度-可不采
};
```

GPS_Data用于传递位置信息。

```c
uint8_t GPS_Init(void);
```

**函数名：**GPS_Init

**描述：**用于初始化GPS外设，包括硬件初始化（使用CubeMX生成的则留空）以及串口配置GPS输出模式。同时该函数还要检测是否存在GPS设备。

**参数：**无

**返回值：**0——正常；1——初始化失败。

```c
uint8_t GPS_ReadPos(struct GPS_Data* gps_data);
```

**函数名：**GPS_ReadPos

**描述：**读取GPS定位数据，如果不存在GPS设备或者定位未成功，返回随机值。

**参数：**`gps_data`——读取到的位置信息

**返回值：**0——正常；1——定位无效；2——读取失败。

#### QMC API

该API用于读取磁力传感器数据。

```c
struct QMC_Data{
    int16_t x;
    int16_t y;
    int16_t z;
};
```

存放三轴磁场数据的结构体。

```c
uint8_t QMC_Init(void);
```

**函数名：**QMC_Init

**描述：**用于初始化磁场传感器，包括IIC硬件初始化（使用CubeMX生成的则留空）以及配置传感器。同时该函数还要检测是否存在磁场传感器。

**返回值：**0——正常；1——没有QMC设备；2——初始化失败。

```c
uint8_t QMC_ReadMagneticField(struct QMC_Data* qmc_data);
```

**函数名：**QMC_ReadMagneticField

**描述：**读取磁场传感器数据。

**参数：**`qmc_data`——读取到的磁场信息

**返回值：**0——正常；1——读取失败。

```c
uint8_t QMC_GetStatus(void);
```

**函数名：**QMC_GetStatus

**描述：**返回QMC数据是否准备完成，可以直接读取引脚或者寄存器获取信息。鉴于QMC5883P的特性，不建议轮询读取，两次调用需要间隔一段时间。

**参数：**无

**返回值：**0——数据准备完成；1——数据未准备完成。

#### EEPROM API

该API用于操作EEPROM中的数据。

```c
uint8_t AT24_Init(void);
```

**函数名：**AT24_Init

**描述：**用于初始化EEPROM，包括IIC硬件初始化（使用CubeMX生成的则留空）以及配置。同时该函数还要检测是否存在EEPROM。

**参数：**无

**返回值：**0——正常；1——没有ROM设备；2——初始化失败。

```c
uint8_t AT24_MemRead(uint8_t addr,uint8_t data[],uint8_t length);
```

**函数名：**AT24_MemRead

**描述：**从EEPROM中指定地址读取指定长度数据。当数据超长时，不读取，返回错误。

**参数：**

* `addr`——读取起始地址
* `data`——存放读取的数据
* `length`——要读取的长度

**返回值：**0——正常；1——读取失败。

```c
uint8_t AT24_MemWrite(uint8_t addr,uint8_t data[],uint8_t length);
```

**函数名：**AT24_MemWrite

**描述：**向EEPROM中指定地址写入指定长度数据。当数据超长时，不写入，返回错误。

**参数：**

* `addr`——起始地址
* `data`——存放要写入的数据
* `length`——要写入的长度

**返回值：**0——正常；1——写入失败。

#### CRC API

该API用于校验数据是否正确。

```c
uint8_t CRC_Init(void);
```

**函数名：**CRC_Init

**描述：**用于初始化CRC计算组件，（使用CubeMX生成的则留空）。

**参数：**无

**返回值：**0——正常；1——初始化失败。

```c
uint8_t CRC_Calculate(const uint8_t data[],uint32_t length,uint32_t* result);
```

**函数名：**CRC_Calculate

**描述：**计算一串数据的CRC值。

**参数：**

* `data`——存放要计算的数据
* `length`——要计算数据的长度
* `result`——存放计算结果

**返回值：**0——正常；1——计算失败。

#### BAT API

该API用于获取电池电量数据。

```c
uint8_t BAT_Init(void);
```

**函数名：**BAT_Init

**描述：**用于初始化读取电池电压的外设（使用CubeMX生成的则留空）。

**参数：**无

**返回值：**0——正常；1——初始化失败。

```c
uint8_t BAT_ReadStatus(uint8_t* status);
```

**函数名：**BAT_ReadStatus

**描述：**读取电池电量。

**参数：**

* `status`——电池电量（百分制）

**返回值：**0——正常；1——读取失败。

#### KEY API

该API用于读取用户按键输入。

```c
typedef enum{
    KEY_NONE=0,			//无事件
    KEY_SINGLE_CLICK, 	//按键单击
    KEY_DOUBLE_CLICK,	//按键双击
    KEY_LONG_PRESS,		//按键长按
}KEY_STATUS;
```

表示按钮的三种按下状态，分别为单击，双击，长按。

```c
uint8_t KEY_Init(void);
```

**函数名：**KEY_Init

**描述：**用于初始化相关的外设（使用CubeMX生成的则留空）以及必要的初始化步骤。

**参数：**无

**返回值：**0——正常；1——初始化失败。

```c
uint8_t KEY_ReadStatus(KEY_STATUS* key_status);
```

**函数名：**KEY_ReadStatus

**描述：**无阻塞的查询按键最新的状态。按键状态具体的判断逻辑在中断中实现。

**参数：**

* `key_status`——按键的状态

**返回值：**0——正常；1——读取失败。

```c
uint8_t KEY_ReadValue(void);
```

**函数名：**KEY_ReadValue

**描述：**直接读取按键当前的值。

**参数：**无

**返回值：**1——按键松开；0——按键按下。

### 灯珠驱动

#### 灯珠参数

灯珠信号定义如下所示：

![image-20250612151513481](README.assets/image-20250612151513481.png)

以典型值为例，在一个2us的时间内，高电平+电平时间为0.28+1.72us表示0，为0.9+1.1us表示1，持续150us低电平重制。两帧传输之间需要插入RESET让数据生效。

2us分为8份，1bit的时间为0.25us，那么可以得到：

* 发送0——1000 0000 -> 0x80
* 发送1——1110 0000 -> 0xE0
* SPI频率——1/2*8-> 4MHz

#### 外设配置

基于上面的参数对，SPI1进行配置，设置为Tranmit Only Master模式，设置Data Size为**8bits**，设置Baud Rate为**4MHz**(通过Prescaler设置)，同时将CPOL设置为0，空闲时低电平。

![image-20250612154043582](README.assets/image-20250612154043582.png)

此时，通过SPI**发送0x80则为发送0，发送0xE0则为发送1。**

同时，需要对DMA进行配置，配置如下所示：

![image-20250612154631254](README.assets/image-20250612154631254.png)

设置内存到外设，内存地址递增，搬运Byte数据，Normal单次搬运模式。

为了检查DMA是否传输完毕，还需要开启中断来设置完成标识。DMA传输完成中断会强制开启，最后会调用SPI的中断回调函数，因此直接实现SPI的回调函数即可，**不要开启SPI中断**。

#### 驱动代码

本驱动使用RGB565格式来保存指南针帧数据，在刷新时先将RGB565转换为RGB888，然后再将每一bit转换为对应的byte，再通过DMA搬到SPI。因此，在驱动中需要准备一个大小为40\*3\*24的数组用于DMA传输。

最核心函数如下：

```c
static void rgb2spi(uint8_t* buffer, uint16_t color, uint8_t brightness)
{
    uint8_t r,g,b;

    RGB565ToGRB888(color, &g, &r, &b, brightness); // 转换为GRB888
    for (int bit = 0; bit < 8; bit++) 
    {
        // 绿色高位优先
        buffer[bit]     = (g & (0x80 >> bit)) ? WS_1 : WS_0;
        // 红色高位优先
        buffer[bit + 8]  = (r & (0x80 >> bit)) ? WS_1 : WS_0;
        // 蓝色高位优先
        buffer[bit + 16] = (b & (0x80 >> bit)) ? WS_1 : WS_0;
    }
}
```

该函数将RGB565转换为RGB888，然后将24个bit的颜色数据分别转换为SPI需要发送的字节。

通过多次调用该函数转换字节，填充整个缓冲区，然后开启DMA传输即可：

```c
uint8_t WS_Update(const uint16_t* pixel, uint16_t length, uint8_t brightness)
{
    if(length > WS_LED_NUM) return 2;

    for(uint16_t i=0;i<length;i++)
    {
        rgb2spi(&ws_spi_buffer[i*24], pixel[i], brightness);
    }
    //填充RESET-不需要，因为一般两次间隔已经超过RESET时间
    //memset(&ws_spi_buffer[WS_LED_NUM * 24], 0x00, WS_RESET_LEN);

    uint8_t res = HAL_SPI_Transmit_DMA(&hspi1, ws_spi_buffer, sizeof(ws_spi_buffer));
    if(res == HAL_BUSY) return 1;
    else return 0;
}
```

这样CPU不用等待刷屏完成即可继续运行。

### I2C驱动

#### 模块参数

QMC5883L的I2C地址为0001 101x，支持Standard-mode -100 kbit/s和Fast-mode - 400 kbit/s 。该模块除了数据接口，还有一个DRDY接口表示数据是否准备完成，当数据准备完成，该引脚变为高电平直到数据被读取。

AT24C02的I2C地址为1010 000x，支持Standard-mode -100 kbit/s和Fast-mode - 400 kbit/s 。

本项目为提高速度，使用Fast-mode。

#### 外设配置

将I2C2的Speed Mode设置为Fast Mode即可，其他配置保存默认。

![image-20250612161057183](README.assets/image-20250612161057183.png)

除此之外，由于QMC的DRDY接口连接到了PA4引脚，来读取数据准备情况，设置PA4为GPIO_Input模式，无上下拉电阻。

#### QMC代码

**注意QMC5883L(丝印DX5883)和QMC5883P(丝印HP5883)的区别。**

QMC5883L——写地址:0X1A

QMC5883P——写地址:0X58

QMC5883P-**软件reset需要先写1然后写0**，**方向通过0x26寄存器设置**，值见附录，要设置成文档中方向需要设置0x26为0x06.

QMC驱动就是常规的IIC寄存器读取，详见源码，但这里需要特别提醒一下某宝的坑爹。

由于QMC5883L停产，被QMC5883P代替，淘宝的QMC5883L一般较贵(15R)，但是有一些特别便宜的(7R)的模块，这种买回来需要看一下丝印，一般是QMC5883P芯片(丝印HP)。

虽然只有一个后缀不同且PINtoPIN替代(伪)，但是**5883L和5883P可以看作完全不同的片子**，两者的IIC地址、寄存器地址、三轴方向、读取方式完全不同，在开发时需要注意以下几点：

1. 5883P没有DRDY引脚，因此使用该芯片的模块的DRDY角没有用
2. 5883P的XY方向与L不同，因此GY-271模块上的标识是错误的，并且初始方向与手册中也不一样，需要设置0x26寄存器为0x06才能和datasheet上的方向一致，该寄存器手册上没有，见附录文章
3. 5883P的寄存器地址和L不一样，需要重新设置
4. 5883P的软件Reset不能自动清零，需要先写1再写0才能完成复位
5. 5883P的Ready寄存器不能轮询读取，因为该寄存器读取后会自动清零，如果读取过快将全部读到0(L是读取了数据寄存器才会清零)

~~某宝店铺用了5883P但给的资料还是L，P的数据手册也说的不清楚，害我调了一下午，积累了宝贵的经验。~~

#### EEPROM代码

EEPROM代码也非常常规，直接使用HAL库的MemWrite/Read函数即可。详见源码。

但这里需要注意一下页写入的问题，每8个字节为一页，每写满8个需要手动写地址换页，具体操作见源码。

### GPS驱动

#### 模块参数

ATGM336H模块默认波特率为9600，上电后会不断发送数据，每次发送数据如下所示：

```
//由于定位未成功这里缺少很多值
$GNGGA,,,,,,0,00,25.5,,,,,,*64
$GNGLL,,,,,,V,N*7A
$GPGSA,A,1,,,,,,,,,,,,,25.5,25.5,25.5*02 // 也有可能是GNGSA
$BDGSA,A,1,,,,,,,,,,,,,25.5,25.5,25.5*13
$GPGSV,1,1,00*79
$BDGSV,1,1,00*68
$GNRMC,,V,,,,,,,,,,N*4D
$GNVTG,,,,,,,,,N*2E
$GNZDA,,,,,,*56
$GPTXT,01,01,01,ANTENNA OK*35

$GNGGA,110656.000,3045.27648,N,10355.70921,E,1,16,1.2,537.0,M,0.0,M,,*70
$GNGLL,3045.27648,N,10355.70921,E,110656.000,A,A*40
$GPGSA,A,3,10,23,28,32,199,,,,,,,,2.7,1.2,2.4*08
$BDGSA,A,3,06,08,09,13,16,25,27,28,38,39,41,,2.7,1.2,2.4*2D
$GPGSV,3,1,11,10,53,334,35,12,19,109,,15,11,071,,18,34,182,03*79
$GPGSV,3,2,11,23,66,079,32,24,38,046,,25,18,144,,28,23,211,15*7B
$GPGSV,3,3,11,32,42,288,39,195,27,158,27,199,46,140,27*44
$BDGSV,3,1,11,06,67,186,30,08,66,065,23,09,53,195,27,13,71,025,30*6C
$BDGSV,3,2,11,16,72,178,33,25,51,132,30,27,28,266,31,28,24,218,21*6E
$BDGSV,3,3,11,38,63,092,30,39,82,148,32,41,53,336,34*50
$GNRMC,110656.000,A,3045.27648,N,10355.70921,E,0.00,328.88,170625,,,A*79
$GNVTG,328.88,T,,M,0.00,N,0.00,K,A*2A
$GNZDA,110656.000,17,06,2025,00,00*48
$GPTXT,01,01,01,ANTENNA OK*35
```

该数据协议为NMEA0183 协议，具体信息可以到网上搜索。

经过测试，模块默认配置下，完整的信息大约500个字符，未定位输出大约265个字符。

使用STM32的`HAL_UARTEx_ReceiveToIdle_DMA`在串口空闲或DMA满时中断，在`HAL_UARTEx_RxEventCallback`进行处理。

考虑到数据可能会部分接收导致缺失，这里同时检测`GNGLL`和`GNRMC`来获取位置信息。

这是在另一家买的模块输出的数据，可以看到`GNGLL`的下一句是`GNGSA`而不是`GPGSA`，注意根据实际购买的模块进行区别。

```
$GNGGA,150334.000,3045.20210,N,10355.66433,E,1,09,1.3,559.4,M,-41.2,M,,*6B
$GNGLL,3045.20210,N,10355.66433,E,150334.000,A,A*42
$GNGSA,A,3,03,16,28,31,194,,,,,,,,3.3,1.3,3.1,1*01
$GNGSA,A,3,16,20,36,39,,,,,,,,,3.3,1.3,3.1,4*3E
$GPGSV,2,1,08,03,40,293,32,16,45,205,34,28,42,046,21,29,16,067,,0*66
$GPGSV,2,2,08,31,59,006,32,32,35,117,,194,51,093,21,199,46,140,,0*63
$BDGSV,2,1,05,16,62,002,30,19,,,37,20,69,169,30,36,27,246,26,0*48
$BDGSV,2,2,05,39,58,025,29,0*4A
$GNRMC,150334.000,A,3045.20210,N,10355.66433,E,0.00,262.34,230625,,,A,V*0E
$GNVTG,262.34,T,,M,0.00,N,0.00,K,A*22
$GNZDA,150334.000,23,06,2025,00,00*4A
$GPTXT,01,01,01,ANTENNA OK*35
```

#### 外设配置

GPS模块连接到USART1，设置Baud Rate为9600，8个数据位,无校验,1个停止位，注意将**Overrun设置关闭**。

Overrun会阻止RX寄存器在还没读取时被新的值覆盖，如果开启，实测会在`HAL_Receive()`阻塞读取时超时。

![image-20250612194702747](README.assets/image-20250612194702747.png)

![image-20250617203023961](README.assets/image-20250617203023961.png)

除此之外，为了减小数据读取对CPU的占用，这里选择开启串口DMA，在串口DMA中断中进行处理。需要开启DMA中断和UART中断(使用IDLE中断)。

#### 驱动代码

GPS串口数据解析使用了DMA中断和串口IDLE中断。首先设置一个比完整GPS报文略长一点的串口缓冲区，使用`HAL_UARTEx_ReceiveToIdle_DMA()`开启接收。

在HAL库中，通过上面函数开启的DMA接收，会在串口空闲时或者传输到指定长度时进入`HAL_UARTEx_RxEventCallback()`回调，并传入传输的长度作为参数。

因此设置一个标志位，用于标志GPS驱动状态。当GPS读取数据时，如果处于停止状态，则开启传输，切换到等待状态；如果处于等待状态，则直接Pass；如果处于数据待解析状态，则根据数据类型对缓冲区执行字符串解析。

```c
uint8_t ATGM_ParseGpsBuffer(float* dlat, float* dlong)
{
    if(data_ready == 0) // GPS 没开始接收数据
    {
        data_ready = 1; //Start Rx
        HAL_UARTEx_ReceiveToIdle_DMA(&GPS_UART_HANDLE,(uint8_t*)uart_buffer,GPS_BUFFER_SIZE);
        return 1;
    }
    else if(data_ready == 1) // GPS 正在接收数据，但还没收到
    {
        return 1;
    }
    // data_ready == 2(GNGLL)或者3(GNRMC) 接收到目标数据
    uint8_t status_index,lat_index,long_index;
    if(data_ready == 2){status_index = 6;lat_index = 1;long_index = 3;}
    else if(data_ready == 3){status_index = 2;lat_index = 3;long_index = 5;}
    data_ready = 0;

//解析过程略，见源码

    // 结束，重新开始一轮接收
    res = HAL_UARTEx_ReceiveToIdle_DMA(&GPS_UART_HANDLE,(uint8_t*)uart_buffer,GPS_BUFFER_SIZE);
    if(res != HAL_OK) return 3; // 开始接收失败
    
    return 0;
}
```

中断中需要判断触发类型，如果是DMAHalf中断，直接Pass继续等待中断；如果接收数据过短，说明数据截断的厉害，需要标识为停止状态等待重新开始；如果处于数据待解析状态，说明是串口空闲中断后在数据解析前又触发了DMA传输完成中断，直接Pass即可；如果处于等待状态，则判断有无特定的两个报文，如果没有，则标识为停止状态等待重新开始，如果找到特定报文，根据报文类型标识不同的数据待解析状态。

不能在中断中`HAL_UARTEx_ReceiveToIdle_DMA()`，因为可能此时DMA还没传输完成。

中断处理函数如下：

```c
//中断回调-DMA接收满回调或串口空闲回调
void ATGM_Int_Handle(UART_HandleTypeDef* huart, uint16_t size)
{
    if(size == GPS_BUFFER_SIZE/2 ) return; // DMA half中断
    if(huart != &GPS_UART_HANDLE) return;
    if(data_ready != 1) return; // 串口空闲中断后又触发了DMA传输完成中断，或者是意外触发
    if(size <= 240) // 接收的东西太少了,比没定位的都少
    {
        data_ready = 0;
        return;
    }

    char* data_start;
    char* data_end;
    uart_buffer[size] = '\0'; //末尾添加字符串结尾
    // 判断缓冲区是否存在需要的数据
    data_start = strstr(uart_buffer, "$GNGLL");
    data_end = strstr(uart_buffer, "$GPGSA");
    if(data_end == NULL)// 由于GPS型号问题，可能是"GNGSA"
        data_end = strstr(uart_buffer, "$GNGSA");
    if(data_start != NULL && data_end != NULL && data_start<data_end) //找到GNGLL
    {
        *data_end = '\0';
        gps_str = data_start;
        data_ready = 2;
        return;
    }
    data_start = strstr(uart_buffer, "$GNRMC");
    data_end = strstr(uart_buffer, "$GNVTG");
    if(data_start != NULL && data_end != NULL && data_start<data_end) //找到GNRMC
    {
        *data_end = '\0';
        gps_str = data_start;
        data_ready = 3;
        return;
    }

    data_ready = 0; // 什么东西都没有
}

```

### 按键驱动

#### 外设配置

按键使用外部中断管理，电路板上的按键按下时引脚会从高电平变为低电平。

设置PA1为GPIO_EXIT，双边缘触发。

![image-20250612200337101](README.assets/image-20250612200337101.png)

为了实现按键各种功能，还需要定时器进行计时，这里使用**TIM16定时器运行按键状态机，使用TIM14用于按键消抖**。由于我们设置单片机主频为64MHz，定时器的频率也是64MHz，将Prescaler频率设置为（64000-1），这样每计数一个值的时间为1ms，这样就可以灵活设置计数时间。

#### 驱动代码

为了无阻塞的使用按键功能，驱动使用两个定时器。~~（还得是STM32外设多，经得住这样霍霍）~~

由于使用外部中断触发中断，即使做了硬件滤波，还是做了一个软件消抖防止过于敏感。

当按键引脚状态变换时，在EXIT中断中会开启消抖定时器，用于在消抖时间后中断触发读取引脚状态，从而获取引脚真实电平。当确定按键状态变化时，将会启动按键状态机定时器。

按键状态机定时器用于处理按键的状态转移，包括对其按下时间计时，长按短按判断等，状态转移如下：

![image-20250710023035658](README.assets/image-20250710023035658.png)

具体实现见源码。在该设定下，如果第一次按下时间小于100ms且到第二次按下时超过100ms，那么需要在300ms内按下两次；如果第一次按下时间大于100ms，双击间隔必须大于200ms小于400ms，即要在300-500ms间按下第二次（~~待改进BUG~~已改进）。

### CRC

#### 外设配置



#### 驱动代码

由于配置中设置了CRC的长度为8bit，因此使用时直接输入byte长度即可，HAL库会自动帮我们调用处理成32bit长度计算。

### ADC

#### 外设配置

ADC开启PA0的通道，即IN0的通道，设置保持默认即可。

#### 驱动代码

电池电压代码比较简单，直接读取即可，通过一个映射数组判断电量的多少。具体见源码。

### 主程序API功能

#### 指针方向设定

MC指南针的动画一共有29个帧，提取其文件得到0~28个图像，其中0图像指向正下方，然后顺时针旋转，知道指向正下方的前一个角度，如图所示：

![Compass_0](README.assets/Compass_0.png)

![Compass_28](README.assets/Compass_28.png)

因此只需要将360度等分为29份分别对应一个帧即可。进行转换时，输入X轴到该方向顺时针需要旋转的角度，输出对应第几帧数据，代码如下：

```c
//根据角度计算动画帧索引-从X轴正方向开始顺时针0-360
uint8_t Angle2Dir(int16_t angle)
{
    if(angle < 0 || angle > 360) // 超限，从地狱获取坐标
        return GetDirFromNether();
    
    if (angle > 353) {
        angle = 0; // 特别处理的情况
    }
    uint8_t interval_index = (uint8_t)((angle + 180.0/29) / (360.0/29));
    return interval_index;
}
```

该代码中，0度位于一个区间段的中间位置。

#### 指南指北功能实现

在本项目中，传感器的X-Y平面和面板平行，因此只需要根据三轴向量在XY的投影即可判断面板平面内的方向，具体就是根据XY向量与方向轴的夹角(atan值)来判断指针需要旋转的角度。向量的方向就是北方。

根据本项目传感器的位置，X轴正方向指向正下方，Y轴正方向指向右侧，相对于常规坐标系顺时针旋转了90度，同时以顺时针为正角度方向。我们需要求从X轴到向量顺时针需要经过多少度。

```c
//根据XY计算角度-从X轴正方向顺时针0-360
float QmcCalAngle(struct QMC_Data* qmc_data)
{
    float deg = atan2f((float)qmc_data->y,(float)qmc_data->x)*180.0f/3.14159f; // 计算角度输出-pi~pi
    deg = -deg; // 逆时针转顺时针
    if(deg < 0) deg += 360; // 转换到0~360
    return deg;
}
```

使用`atan2()`会自动判断相位，从而输出-pi~pi范围的值(以X轴为中心)，通过符号取反和归一化操作，可以将输出变换到0~360顺时针域。该函数输出就是北方在X轴顺时针多少度位置。

#### 方位角的计算

方位角：是从某点的指北经线起，依顺时针方向到目标方向线之间的地表夹角，如下图θ角所示。

![image-20250618201820295](README.assets/image-20250618201820295.png)

通过方位角和北方方向，可以得到另外一处地点的方位位置，方位角的计算公式如下：
$$
\theta = \text{atan2}\left(\frac{\sin(\lambda_2 - \lambda_1) \cdot \cos(\varphi_2)}{\cos(\varphi_1) \cdot \sin(\varphi_2) - \sin(\varphi_1) \cdot \cos(\varphi_2) \cdot \cos(\lambda_2 - \lambda_1)}\right)
$$
该公式的输出结果角度，正为北方顺时针方向，负为北方逆时针方向，对负方向，通过归一化转换为0-360范围,计算代码如下：

```c
// 计算位置1到位置2的方位角-0~360
float GpsCalBearing(struct GPS_Data* gps_1, struct GPS_Data* gps_2)
{
    // 方位角：是从某点的指北经线起，依顺时针方向到目标方向线之间的地表夹角
    // 这里使用球模型进行计算，但实际上不需要这么精确，应该平面模型即可

    if (gps_1->dlat == gps_2->dlat && gps_1->dlong == gps_2->dlong) {
        return 0; // 相同点，返回0
    }

    float rlat1 = gps_1->dlat * 3.14159f/180.0f;
    float rlong1 = gps_1->dlong * 3.14159f/180.0f;
    float rlat2 = gps_2->dlat * 3.14159f/180.0f;
    float rlong2 = gps_2->dlong * 3.14159f/180.0f;

    float numerator = sinf(rlong2 - rlong1) * cosf(rlat2);
    float denominator = cosf(rlat1) * sinf(rlat2) - sinf(rlat1) * cosf(rlat2) * cosf(rlong2 - rlong1);
    float x = atan2f(numerator, denominator);
    x = x * 180.0f/3.14159f;

    if(x < 0) x=x+360.0f;
    
    return x;
}

```

####  配置存取功能

配置信息使用一个结构体维护，保存时按原始字节直接写入EEPROM，并加上固定2字节帧头和CRC校验码帧尾。

读取时验证CRC来判断是否保存过配置或者配置数据是否正确。

注意不能通过将结构体指针直接指向读取缓冲区的方式提取信息，因为在读取多字节时会触发Cortex内核内存对齐问题，直接进hardfault。可以使用memcpy函数防止直接的内存访问。

具体实现见源码。

## Tools

本项目使用tools如下(均使用DeepSeek生成~~D学长太强了~~)：

* `extract_gif.py` 将wiki上的指南针动图拆分为png
* `extract_pic.py`从上面拆分的png中提取特定区域的像素并取模

## 参考

项目1-[简易我的世界指南针](https://oshwhub.com/realtix/jian-yi-mc-zhi-nan-zhen) 

项目2-[MCompass一个现实世界中的Minecraft罗盘](https://oshwhub.com/chaosgoo/wcompass) 

[利用GPS坐标计算方位角](https://johnnyqian.net/blog/gps-locator.html) 

[QMC5883P坐标系方向](https://blog.csdn.net/u014436243/article/details/122358056)