Minecraft我的世界指南针

Minecraft我的世界指南针

声明

本项目含有游戏素材，版权归属微软所有，使用时请注意。
本描述部分图片来自淘宝店铺和立创商城，侵权请联系删除。
本项目为本人受两个开源项目启发进行的复刻，修改并添加了自己的设计，两个开源项目为MCompass一个现实世界中的Minecraft罗盘和简易我的世界指南针，欢迎大家学习上面两个大佬的项目。

介绍

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

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

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

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

注意：

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

固件开源地址：
https://github.com/LOStacNet/mccompass
https://gitee.com/LOStacNet/mccompass

图片展示

• PCB正面
  
• PCB背面
  
• 正面无面板
  
• 成品
  

硬件设计

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

像素设计

Minecraft中的指南针大小为14x12像素，其中共有40个像素为显示区域。
根据灯珠大小，设定一个像素显示区域为6x6mm，设定光栅厚度为1mm，那么可视为一个像素7mm，最终大小为98x84mm。
在文档层绘制像素框，设定矩形线宽为1mm，宽和高分别为7mm，则显示像素区域如图所示：

整个范围如图：

灯珠电路

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

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

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

每行设置一个100nF电容去噪，输入输出预留电阻位置用于调试。
灯珠使用中等大小SMD3538(3.5x2.8mm)封装的灯珠，该型号灯珠可在淘宝搜索WS2812B-3528RGB找到，如果在立创商城上可以参考XL-3528RGBW-WS2812B，商品编号C2890364(未测试，不保证能正常运行，但封装一样)。必须搭配柔光纸使用。

电源管理

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

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

EEPROM

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

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

单片机

主控要求支持IIC，UART，单线数据输出，并最好支持单线数据DMA输出和低功耗。
选择STM32G030F6P6，该芯片主频64MHz，有一个ADC，2个IIC，3个SPI，两个USART以及DMA，符合本设计需求。正好淘宝也有该芯片的开发板，有硬件参考，调试也方便。
该单片机外部电路较为简单，只需要提供RST信号和下载接口即可。本设计中除了外设接口，还使用了USART2作为Debug输出，同时添加了LED用于显示程序状态。

开关和接口

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

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

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

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

传感器

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

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

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

本项目使用ATGM336H模块。

3D外壳

设计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指南针素材的取色，设置每个像素的颜色。将显示区域在透明控制层标出。
立创面板设计十分简单，建议大家可以看看，但是面板打样暂时没有优惠活动。

软件设计

本节介绍软件设计。

整体框图

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

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

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

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

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

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

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

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

BSP层定义

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

具体实现的API结构和描述见源码bsp.h文件，这里不再赘述。

灯珠驱动

WS灯珠使用单线信号，以典型值为例，在一个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，空闲时低电平。

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

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

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

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

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

最核心函数如下：

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传输即可：

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 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轴到向量顺时针需要经过多少度。

//根据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()会自动判断相位，从而输出-pipi范围的值(以X轴为中心)，通过符号取反和归一化操作，可以将输出变换到0360顺时针域。该函数输出就是北方在X轴顺时针多少度位置。

方位角计算

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

通过方位角和北方方向，可以得到另外一处地点的方位位置，方位角的计算公式如下：

该公式的输出结果角度，正为北方顺时针方向，负为北方逆时针方向，对负方向，通过归一化转换为0-360范围,计算代码详见源码。

配置读写功能

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

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

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

具体实现见源码。

Tools

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

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

制作指南

PCB下单

PCB直接从立创EDA下单即可，板厚选择1.6mm，其他参数视需求设置即可。

该设计将所有贴片放到一面，可以选择开钢网(55元)方便焊接灯珠。

面板下单

面板下单选择黑色半透明亚克力、1mm厚、正面打印、常规遮光(白底)、背胶。

由于背胶有厚度，最后会让显示区域薄一点，刚好可以放一张柔光纸。

焊接方法

• 以下焊接过程仅针对钢网
• 强烈建议焊接前先将GPS连接到电脑查看输出
  需要贴的电阻电容值如下：

首先，将PCB垫平，周围使用其他板子垫到同高度并通过胶带固定，方便固定钢网。将钢网与焊盘对齐后，使用胶带固定。

挤出适量锡膏，本次使用138度的低温锡膏，使用刮片让锡膏均匀填充钢网的开口，注意PCB下半部分不要上锡膏（因为不焊贴片元件）。锡膏最好填满钢网的孔，否则可能有些不够。

然后将元件摆放到相应位置，注意放好后按以下保证元件和焊盘贴合好。

之后，设置加热台温度，本次使用138度的低温锡膏，加热台温度设置为180度即可。待加热台温度达标后，将PCB放到上面，加热。

等待锡膏全部融化后拿下，用电烙铁修补一下没焊好的地方，尤其是连锡短路。

然后焊接上模块和插件。

最终成品见上面的展示。

程序烧录

将STLink/DapLink等烧录器连接到烧录接口，直接烧录即可。建议使用烧录针或者杜邦线公母线，不要把排针焊上了。

外壳装配

由于本外壳3D模型没有预留多少冗余空间，在装配时需要尤其注意螺丝部分。

打印完成后，需要手工修整一下边缘，保证前壳和后盖能够契合。对于后盖的螺丝孔部分，需要提前将孔扩大清理，保证M2螺丝能够打到最里面。

扩孔如下图，这里使用了2毫米直径的棍捅穿孔洞

先让所有螺丝都能够出头，如下：

所有螺丝都能打到最里面：

之后，按照下面进行装配，注意，GPS天线小圆点需要朝上，天线从下面走过去，防止打螺丝时打到天线(问就是我差点搞坏一个)

然后裁剪柔光纸，形状裁剪成面板透明部分：

然后撕开背胶，将面板贴到正面即可。

开机校准

除此使用，需要进行校准，让磁场向量中心回到原点。在指南针模式下，双击按键，屏幕长显示中心红点十字时旋转罗盘(各个方向)，让其各方向都能采集到最大最小值，进行校准。

就像手机指南针让人八字移动手机一样。

元件与BOM表

元件名称	型号	数量	单价	某宝最小数量	某宝最小单价
5V充放电一体化模块	DC黑色 主推5V充放一体(1个)	1	3.74	1	3.74
深圳光泽光电-WS2812灯珠3528RGB幻彩	3528幻彩(雾面)	40	0.092	100	9.22
UMW AMS1117-3.3S SOT-89 1A低压差线性稳压器LDO芯片	AMS1117-3.3S SOT-89	1	0.18	1	0.18
XH2.54接插件2.54mm间距连接器	XH2.54_2P_弯针座	1	0.02	10	0.2
3.7V聚合物锂电池	603450-1200毫安/拍二发三	1	13.13	1	13.13
STM32G030F6P6	STM32G030F6P6 TSSOP-20	1	3.45	1	3.45
AT24C02D-SSHM-T SOIC-8 存储器芯片 EEPROMs串行	AT24C02D-SSHM-T SOIC-8	1	0.71	1	0.71
拨动开关	拨动开关 SS-12D00 1P2T 立式 柄高5MM (20个)	1	0.1	20	2.09
轻触式开关按键微动开关按钮开关	3*4*2MM 按键按钮 2脚（20个）	1	0.1	20	1.9
微动开关按键开关轻触按钮	6*6*8mm 卧式带支架开关（30个）	1	0.1	30	3.22
QMC5883L电子指南针罗盘模块 三轴磁场传感器 GY-271	QMC5883三轴磁场传感器(1个）GY-271	1	16.9	1	16.9
ATGM336H GPS 北斗双模模块	ATGM336H版本模块（未焊排针）+陶瓷有源天线	1	34	1	34
4.7uF 0603 贴片电容	4.7uF 0603	1
47K 0603 贴片电阻	47K 0603	2
1uF 0603 贴片电容	1uF 0603	2
LED 0603 贴片LED	LED 0603	1
10k 0603 贴片电阻	10k 0603	3
4.3k 0603 贴片电阻	4.3k 0603	1
100nF 0603 贴片电容	100nF 0603	10
304不锈钢十字扁平头自攻螺丝钉CA M2*6 头厚0.8mm 头直径4mm	M2*6 (200个)	4	0.001	200	3.23

上述元件单套成本约78元，某宝购买做一套成本91元左右，详细的信息见附件。

此外，假设使用免费PCB打样，还需要花10元左右一个打印面板(彩色图案黑色亚克力)，单次5个50元左右(这里我15个花了88元)。

另外，还需要购买柔光材料，购物网站搜索柔光纸即可，10元即有一大卷。

因此，复刻一个成本可能达到120元左右，批量制作约80元一个。本数据是通过物料粗略计算得出，仅供参考。

注意电源管理和磁场感应器GY-271 QMC5883模块和GPS模块ATGM336H的型号，尤其是引脚信号定义是否和PCB一致。

参考文章

项目1-简易我的世界指南针

项目2-MCompass一个现实世界中的Minecraft罗盘

利用GPS坐标计算方位角

QMC5883P坐标系方向