#1. 安全须知

在开始安装前，请先阅读以下事项：

1. 安装、拆下 HAT 或连接内部 USB 线时，必须先关闭 Raspberry Pi 并断开电源。
2. 对准 40-pin 排针的 1 脚标记。上电前确认排针没有错位、弯针或短路。
3. 进行 LoRa 发射前必须连接 860–960 MHz 天线。不要让 SX1262 在无天线或天线严重失谐的状态下发射。
4. HAT 的 5V Bias Tee 只适用于 SDR 接口。不要把它接到 GPS 或 LoRa 天线，也不要在连接无隔直电容的普通无源天线时随意开启。
5. 使用 LoRa 时必须遵守当地无线电法规，并正确设置 Meshtastic Region。不同区域的频率参数不能互操作，也不应通过修改 Region 规避当地限制。
6. RTC 电池为板载不可拆卸的可充电 3V 电池，由板载充电电路充电。不要尝试拆卸或更换电池；发现机械损伤、异常发热或漏液时，应停止使用并联系厂商。
7. GPS 使用 Raspberry Pi 的 GPIO14/15 UART。

#2. 产品概述

该 HAT 将以下四个功能集成到一块 Raspberry Pi 40-pin 扩展板上：

#2.1 外观与主要接口

图 1：上方为顶面，下方为底面。图中为 SMA 版本；U.FL 版本的接口位置和功能相同。

1. 1 — USB-C J2： RTL-SDR USB 数据与 VBUS，可连接外部 USB 主机。
2. 2 — SW1： 6 位 SMD 拨码开关，用于选择 GPS/RTC 辅助信号与备份电源连接。
3. 3 — RTC 电池： 板载不可拆卸可充电 3V 纽扣电池。
4. 4 — 40-pin 排针 J1： 2×20-pin、2.54 mm，作为 Raspberry Pi HAT 连接接口。
5. 5 — SDR 天线口 J3： SMA 或 U.FL，RTL-SDR 射频输入，支持软件控制的 5V Bias Tee。
6. 6 — GPS 天线口 J4： SMA 或 U.FL，GPS/GNSS 天线输入，支持主动和被动天线。
7. 7 — LoRa 天线口 J5： SMA 或 U.FL，SX1262 射频输入/输出。
8. 8 — 内部 USB J6： 底面 1×4、1.25 mm 接口，连接 Raspberry Pi USB-A。J2 与 J6 共用 USB 数据线，二者只能择一连接主机，未使用的端口不要保留线缆。

#2.2 Raspberry Pi 兼容性

• Raspberry Pi 3B、4B、5：可直接安装。
• Raspberry Pi Zero、Zero 2 W：板上有 40-pin 排针时可直接安装，但需注意整机高度和供电能力。
• CM4、CM5：不能直接插在 HAT 上，需要带 40-pin 排针的载板或转接板。
• Raspberry Pi 本体、天线和外壳是否随附以具体订单为准。

#2.3 供电与数据路径

• HAT 通过 Raspberry Pi 40-pin 头的 5V 引脚取电。
• RTL2832U 的 3.3V 由板上稳压器产生。
• RTL-SDR 的数据线经 J2/J6 引出，必须另外连接到 Raspberry Pi 的 USB 主机口；40-pin 排针本身不承载 USB。
• Bias Tee 的 5V 经板上功率开关提供，并由 RTL2832U 的 GPIO0 控制。
• Raspberry Pi 5 建议使用官方 5V/5A 电源；Raspberry Pi 4 建议使用稳定的 5V/3A 电源。SDR 接收、Bias Tee 和 LoRa 发射会增加瞬时负载。

#3. 40-pin 引脚定义

方向以 Raspberry Pi 为主机定义：

• Pi → HAT：Pi 输出，模组接收。
• HAT → Pi：模组输出，Pi 接收。
• 可选：必须将对应拨码位拨到 ON 才连接到 Pi GPIO。
• NC：当前 HAT 设计未连接。

#3.1 按模块汇总

#3.2 内部 USB 接口 J6

J2 和 J6 的 USB D+/D− 在板上并联，二者择一连接主机。不要在 J2 和 J6 同时连接两个 USB 主机。使用 J6 内部线时，先接好 HAT 一侧和 Raspberry Pi 一侧，再给整机上电。

使用其中一个端口时，另一个端口也不要插着线。未使用端口上的 USB 线必须完全拔掉，而不是只拔掉线缆另一端；悬空线缆可能形成天线，耦合干扰并影响 USB 通信。

#4. 六位配置开关 SW1

SW1 的 ON 表示该位两端导通。板上的开关位号通常从标有 1 或方形焊盘的一端开始，实际安装时以 PCB 丝印为准。

#4.1 推荐初始位置

GPS 星座模式：

• SW1-3 OFF + R29 已焊： GPS+GLONASS。
• SW1-3 ON： BDS+GPS。

若板卡修订版或 BOM 改变了 R29，请以实物丝印和当前原理图为准。不要把不同拨码位的 ON/OFF 方向混用；有些滑动开关的拨杆朝向并不等于 ON，观察通断关系或使用万用表确认最可靠。

#5. 硬件安装步骤

#5.1 装配爆炸图

图 2：HAT、Raspberry Pi、铜柱、固定螺丝、内部 USB 线与天线装配关系示意。天线、铜柱、螺丝和内部线是否随附以具体订单为准。

装配时先确认 HAT 与 Raspberry Pi 的 40-pin 排针对应，再安装铜柱、内部 USB 线和天线。不要用天线或 SMA 接头承受板卡和机箱重量。

#5.2 检查包装和板卡

1. 核对 HAT、天线连接方式、USB 内部线和安装铜柱是否与订单一致。
2. 检查 40-pin 排针是否笔直，PCB 和屏蔽罩是否有明显挤压或元件脱落。
3. 检查板载 RTC 电池和焊接区域没有机械损伤。该电池不可拆卸，不要尝试取出或更换。
4. 检查 SW1 是否位于无遮挡、可再次调整的位置。
5. 首次使用建议先让板卡上电充电 2–4 小时，再测试断电保持时间。

#5.3 安装 HAT

1. 关闭 Raspberry Pi，拔掉电源，等待所有指示灯熄灭。
2. 先在 Raspberry Pi 四角安装适合高度的铜柱或支撑件。
3. 将内部 USB 线的一端接 HAT 底面的 J6，另一端接到 Raspberry Pi USB-A 口。确认 1.25 mm 插头完全插入且线束没有夹在板边；此时 J2 上不得保留任何 USB 线。
4. 对准 40-pin 排针与 Raspberry Pi 的 1 脚标记，垂直、均匀地压入 HAT。不要只压一侧。
5. 用螺丝固定 HAT，但不要过度拧紧。检查 HAT 背面没有金属件碰到 Pi 的裸露测试点或 HDMI/USB 金属壳。
6. 重新检查 SW1 设置、USB 线方向、未使用 USB 端口是否已完全空置，以及 40-pin 排针对齐情况。

#5.4 连接天线和电源

1. 先在断电状态连接 SDR、GPS 和 LoRa 天线。
2. GPS 天线尽量放在室外或靠近窗户的位置；不要靠近金属屏蔽物。
3. LoRa 天线必须与所设置的频段匹配。
4. 检查所有连接无误后再接入 Raspberry Pi 电源。
5. 首次启动后先不要开启 SDR Bias Tee，也不要进行 LoRa 发射。

#6. 软件安装前置条件

本文以 Raspberry Pi OS Bookworm/Trixie 64-bit 为基准。开始前连接网络并更新软件包：

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y git i2c-tools minicom util-linux-extra
sudo reboot

确认系统版本：

cat /etc/os-release
uname -m

RTL-SDR 和 Meshtastic 的用户态程序建议使用 64-bit 系统。32-bit Raspberry Pi OS 与 Meshtastic 官方 Debian/Bookworm/Trixie 软件源的兼容性会不同；使用 32-bit 系统时请改看 Meshtastic 的 Raspbian 安装说明。

#7. Raspberry Pi 设备树配置

编辑 Raspberry Pi 的启动配置：

sudo nano /boot/firmware/config.txt

在文件中有注释、模块化且不重复的位置加入：

# HackerGadgets RTL-SDR / LoRa / GPS / RTC HAT
dtparam=i2c_arm=on
dtoverlay=i2c-rtc,pcf85063a
dtparam=spi=on
dtoverlay=spi1-1cs

配置项含义：

再根据平台添加 UART 配置。

Raspberry Pi 4 / CM4：

enable_uart=1

该配置启用 GPIO14/15 的 UART，GPS 路径为 /dev/ttyS0。

Raspberry Pi 5 / CM5：

dtparam=uart0=on

该配置启用 UART0，GPS 路径为 /dev/ttyAMA0。Raspberry Pi 5 / CM5 应使用这一项，不要用 Raspberry Pi 4 / CM4 的 UART 配置替代。

然后删除串口控制台对 GPS UART 的占用。编辑：

sudo nano /boot/firmware/cmdline.txt

如果同一行中存在以下任一项，将其删除：

console=serial0,115200
console=ttyAMA0,115200

cmdline.txt 必须保持为单行。修改后重启：

sudo reboot

也可以使用 sudo raspi-config 的 Interface Options → Serial Port：

• “Login shell over serial”选择 No；
• “Serial port hardware enabled”选择 Yes。

#8. RTC 设置

#8.1 检查 I²C 设备

sudo i2cdetect -y 1

正常应看到 PCF85063A 位于 0x51：

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
50: -- UU -- -- -- -- -- -- -- -- -- -- -- -- -- --

若没有 UU，先检查设备树配置和 40-pin 连接。板载 RTC 电池为不可拆卸的可充电电池；若曾长期断电存放，可先保持系统上电 2–4 小时充电后重测，不要尝试拆卸电池。

#8.2 读写硬件时钟

sudo hwclock -r
sudo hwclock -w
sudo hwclock -r

• hwclock -r：从 RTC 读取时间。
• hwclock -w：把当前系统时间写入 RTC。
• 第二条 hwclock -r 应返回与当前系统时间接近的值。

先让系统通过 NTP 得到正确时间，再同步到 RTC：

timedatectl status
sudo hwclock -w

#8.3 断电保持测试

1. 记录 date -Is 和 sudo hwclock -r 的结果。
2. 正常关机并断开整机电源 1–2 分钟。
3. 重新上电。
4. 再次执行 date -Is 和 sudo hwclock -r。
5. 若系统时间已被正确恢复且两次读数连续，说明 RTC 和电池备份工作正常。

如使用 RTC 闹钟或中断，将 SW1-6 拨到 ON，并使用 GPIO16。读取 GPIO 线号和总线号时应以当前 Raspberry Pi 的 gpiodetect 输出为准；不同 Pi 5 内核版本的 gpiochip 编号可能改变。RTC 中断控制和 rtcwake 参数应以 PCF85063A 设备树绑定和系统版本为准。先验证基本时间保存功能，再增加唤醒功能，避免把 I²C 通信正常误判为中断配置正常。

#9. GPS 设置

#9.1 验证串口

GPS 串口路径必须按平台选择：

查看对应设备：

ls -l /dev/ttyS0 /dev/ttyAMA0

启动串口监视：

# Raspberry Pi 4 / CM4
sudo minicom -D /dev/ttyS0 -b 9600

# Raspberry Pi 5 / CM5
sudo minicom -D /dev/ttyAMA0 -b 9600

正常会持续出现类似下面的 NMEA 数据：

$GNGGA,100139.000,2307.73354,N,11322.65974,E,1,09,2.3,43.1,M,-6.8,M,,*6F
$GNRMC,100139.000,A,2307.73354,N,11322.65974,E,0.00,0.00,040125,,,A,V*08

退出 Minicom：按 Ctrl-A，再按 X。

#9.2 定位判断

• GGA 中的第 6 个字段为定位质量：1 通常表示有效定位。
• 字段 09 附近的数值为卫星数。
• 室内、金属机箱附近或天线朝向不佳时，可能长时间没有定位。
• 首次定位可能需要几分钟；请把 GPS 天线置于室外并保持静止。

#9.3 GPS 数据服务

如果只需要验证 GPS，使用 Minicom 即可。若要把 GPS 提供给其他 Linux 程序，可安装 gpsd：

sudo apt install -y gpsd gpsd-clients

# Raspberry Pi 4 / CM4
sudo gpsd -N -n -F /run/gpsd.sock /dev/ttyS0

# Raspberry Pi 5 / CM5
sudo gpsd -N -n -F /run/gpsd.sock /dev/ttyAMA0

cgps -s

#9.4 可选 PPS

需要秒脉冲时：

1. 将 SW1-2 拨到 ON。
2. 在 /boot/firmware/config.txt 增加：

dtoverlay=pps-gpio,gpiopin=6

1. 重启后安装测试工具：

sudo apt install -y pps-tools
sudo ppstest /dev/pps0

PPS 只用于提高授时精度，不是 GPS 输出 NMEA 的必要条件。

#10. RTL-SDR 设置

#10.1 安装驱动和用户态程序

部分 Raspberry Pi OS 镜像会自动加载 DVB-T 内核驱动并占用 RTL-SDR。先阻止它自动加载：

sudo tee /etc/modprobe.d/blacklist-rtl.conf >/dev/null <<'EOF'
blacklist dvb_usb_rtl28xxu
EOF

sudo modprobe -r dvb_usb_rtl28xxu 2>/dev/null || true
sudo apt update
sudo apt install -y rtl-sdr
sudo reboot

#10.2 识别设备

lsusb
rtl_test -t

lsusb 中可能显示 Realtek RTL2832/RTL2838 设备，具体 PID 和序列号随机型、生产批次而异。rtl_test -t 应能报告设备、调谐器、增益档和频率范围。

如果只看到 USB 设备但 rtl_test 无法打开：

1. 检查 J6 内部 USB 线是否完整插入。
2. 换用 Raspberry Pi 上另一个 USB-A 口。
3. 确认 dvb_usb_rtl28xxu 没有再次加载：

lsmod | grep -E 'dvb_usb_rtl|rtl28xxu' || true

1. 检查 5V 电源是否足够；SDR 枚举失败或反复掉线常见于供电不足。

#10.3 快速接收测试

先接好 SDR 天线，再启动 RTL-SDR 工具：

rtl_test -s 2048000

也可以安装 GQRX：

sudo apt install -y gqrx-sdr
gqrx

在 GQRX 中选择 RTL-SDR 输入，再选择检测到的 RTL-SDR 设备。建议先调到本地 FM 广播频点，使用 WFM 解调，确认瀑布图和声音正常。

#10.4 HF 直采

HAT 支持 100 kHz–28.8 MHz 的 HF 直采。根据所用软件选择：

• Quadrature / Q Branch 直采；
• I Branch 直采；
• 具体菜单名称随 SDR++、GQRX 或 rtl_fm 版本变化。

不要为了接收 HF 而在 GPS/LoRa 接口上做实验。HF 直采仍使用 SDR 天线口。

#10.5 Bias Tee

Bias Tee 由 RTL2832U GPIO0 控制，旁边 LED 可指示状态。使用 有隔直电容的主动天线或 LNA 时，可在支持该功能的 SDR 软件中启用。

若系统安装了 rtl_biast，可用以下方式测试：

rtl_biast -d 0 -b 1
rtl_biast -d 0 -b 0

• -b 1：开启 5V Bias Tee。
• -b 0：关闭 5V Bias Tee。

执行命令前先确认 SDR 天线口接的是允许 5V 直流注入的负载。验证结束后重新执行 -b 0，不要长期在未知负载上开启。

#11. Meshtastic LoRa 设置

#11.1 从官方 Debian 软件源安装

Meshtastic 官方支持 Debian 12 Bookworm 和 Debian 13 Trixie，并提供 Beta、Alpha 和 Daily 软件源。以下采用官方文档中的 Beta 源。

安装依赖：

sudo apt update
sudo apt install -y curl gnupg

#Debian 12 / Raspberry Pi OS Bookworm

echo 'deb http://download.opensuse.org/repositories/network:/Meshtastic:/beta/Debian_12/ /' | \
  sudo tee /etc/apt/sources.list.d/network:Meshtastic:beta.list

curl -fsSL https://download.opensuse.org/repositories/network:Meshtastic:beta/Debian_12/Release.key | \
  gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/network_Meshtastic_beta.gpg > /dev/null

sudo apt update
sudo apt install -y meshtasticd

#Debian 13 / Raspberry Pi OS Trixie

echo 'deb http://download.opensuse.org/repositories/network:/Meshtastic:/beta/Debian_13/ /' | \
  sudo tee /etc/apt/sources.list.d/network:Meshtastic:beta.list

curl -fsSL https://download.opensuse.org/repositories/network:Meshtastic:beta/Debian_13/Release.key | \
  gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/network_Meshtastic_beta.gpg > /dev/null

sudo apt update
sudo apt install -y meshtasticd

官方 Debian 软件源明确提示：32-bit Raspbian 应使用 Raspbian 仓库，而不是直接使用上述 Debian 仓库。

#11.2 配置 SPI 和 SX1262

先确认 SPI1 已出现：

ls -l /dev/spidev1.0

该文件不存在时，检查 /boot/firmware/config.txt 中是否已有 dtoverlay=spi1-1cs，然后重启。

备份配置文件：

sudo cp /etc/meshtasticd/config.yaml /etc/meshtasticd/config.yaml.bak
sudo nano /etc/meshtasticd/config.yaml

将已有的 Lora: 段替换为以下内容。不要在整个文件中保留第二个 Lora: 段，否则 YAML 中重复键会导致启动失败或不生效：

Lora:
  Module: sx1262
  DIO2_AS_RF_SWITCH: true
  DIO3_TCXO_VOLTAGE: true
  IRQ: 26
  Busy: 24
  Reset: 25
  spidev: spidev1.0

参数与硬件对应关系：

#11.3 配置 GPS

Raspberry Pi 4 / CM4 使用：

GPS:
  SerialPath: /dev/ttyS0

Raspberry Pi 5 / CM5 使用：

GPS:
  SerialPath: /dev/ttyAMA0

先完成第 9 节，确认对应平台的串口有 NMEA 输出，再在配置文件中只保留与当前平台对应的 GPS: 段。不能同时保留两个 GPS: 段；同样应删除文件中已有的其他 GPS: 段。若 meshtasticd 启动时无法打开 GPS，停止使用该串口的其他程序，包括 gpsd、Minicom 和上游脚本。

#11.4 启用 Web 服务

如果配置文件内有注释的 Webserver: 段，将其启用并设置为：

Webserver:
  Port: 443
  RootPath: /usr/share/meshtasticd/web

同样不要保留重复的 Webserver: 段。

#11.5 启动和检查服务

sudo systemctl daemon-reload
sudo systemctl enable meshtasticd
sudo systemctl restart meshtasticd
systemctl status meshtasticd --no-pager

若服务没有正常运行：

sudo journalctl -u meshtasticd -b -n 150 --no-pager

重点检查：

• 是否成功打开 /dev/spidev1.0；
• SX1262 初始化是否成功；
• GPS 串口是否被其他进程占用；
• 配置文件中是否有重复的 YAML 键。

#11.6 首次配置

在 Raspberry Pi 浏览器打开：

https://localhost

Web 服务使用本地自签名证书，首次打开可能出现证书提示。仅在确认访问的是本机 localhost、端口 443 的服务时继续进入。

1. 点击 New Connection。
2. 主机或 IP 地址填 localhost，不要依赖离线环境中可能无法解析的 .local 主机名。
3. 连接后进入 Config → LoRa。
4. 设置 Region。不同区域使用不同频率范围和发射限制，不同 Region 不能正常通信。
5. 设置频道和节点名称。
6. 使用第二个 Meshtastic 节点验证收发。

在完成 Region 设置、连接合格的 LoRa 天线并检查法规限制前，请勿进行发射测试。

#12. 推荐验证顺序

为了快速分离故障，建议按以下顺序进行：

一次只改变一个变量。尤其在修改设备树后，先重启再判断结果，不要把 I²C、GPS 和 LoRa 三个问题混在同一次排查中。

#13. 故障排查

#13.1 RTC 无响应

• i2cdetect -y 1 没有 0x51：检查 dtparam=i2c_arm=on 和 dtoverlay=i2c-rtc,pcf85063a。
• 有 0x51 但 hwclock -r 失败：检查系统是否加载了 RTC overlay，并用 dmesg 查看 I²C 错误。
• 断电后时间丢失：先让板卡持续上电 2–4 小时，使板载不可拆卸电池获得足够充电；若仍无法保持时间，应检查板载充电电路并联系厂商，不要自行拆卸或更换电池。
• 系统时间不断被网络时间覆盖：先检查 timedatectl status，网络授时成功后执行 sudo hwclock -w。

#13.2 GPS 没有数据

• 确认天线接在 GPS 口，且没有误接 SDR 或 LoRa。
• 检查 40-pin 的 8、10 脚和 UART 配置。
• 检查 cmdline.txt 是否仍包含 console=serial0,115200。
• 用 sudo raspi-config 关闭串口登录终端，并启用硬件串口。
• 移到室外，等待数分钟；在窗边也不能保证首次定位。
• 检查是否有 gpsd、Minicom、上游服务或另一个程序占用当前平台的 GPS 串口：Pi 4/CM4 为 /dev/ttyS0，Pi 5/CM5 为 /dev/ttyAMA0。
• 检查 SW1-3 的星座模式选择是否符合预期。模式不影响串口能否打开，但会影响可接收的星座。
• 若模块修订版要求 ON/OFF 脚为确定电平而当前 NMEA 仍为空，可尝试将 SW1-5 拨到 ON，并由 GPIO23 输出高电平；不要在不了解模块使能极性的情况下反复切换。

#13.3 RTL-SDR 无法识别

• 检查 J6 的 D+/D−/5V/GND 是否接对。
• 使用 Raspberry Pi 的其他 USB 口排除单口故障。
• 检查 DVB-T 驱动是否重新占用设备。
• 换用质量可靠、短且支持数据通信的 USB 线。
• 检查 Pi 电源是否出现欠压，尤其在 SDR 加 Bias Tee 时。

#13.4 /dev/spidev1.0 不存在

• 确认 /boot/firmware/config.txt 中没有重复或相互覆盖的 SPI1 overlay。
• 检查是否误用了 SPI0 的 /dev/spidev0.0。
• 重启后用 dmesg | grep -i spi 查看设备树加载情况。

#13.5 Meshtastic 无法初始化 SX1262

• 核对 IRQ: 26、Busy: 24、Reset: 25。
• 确认 spidev: spidev1.0，而不是 spidev0.0。
• 检查 3.3V 供电和焊接、连接器状态。
• 查看 journalctl 中是否有 SPI 打开失败或 SX1262 busy 超时。

#13.6 Meshtastic 能启动但无法收发

• 设置正确的 Region。
• 检查 LoRa 天线频段是否匹配。
• 检查第二个节点是否使用相同 Region、频道参数和调制参数。
• 不要在无天线状态下重复发射。
• 确认目标节点距离、天线极化和遮挡情况。

#14. 参考与版本说明

本文中的 Raspberry Pi HAT 引脚和 SW1 关系依据当前 RPI_AIO 工程原理图/网表核对；软件流程参考以下公开资料：

1. 产品页：RTL-SDR/LoRa/GPS/RTC hat for Raspberry Pi
2. HackerGadgets uConsole AIO V1/V2 Extension Board Setup Guide
3. Meshtastic Debian 安装文档

注意：

• uConsole 扩展板和 Raspberry Pi HAT 的外形、引脚用途和 CM4/CM5 设备树配置不同。本文没有把 uConsole 的 GPS/LoRa/SDR GPIO 使能脚直接复制到 HAT。
• Meshtastic 官方 Debian 文档会持续更新。安装前建议再次检查软件源、Debian 版本和 Beta/Alpha 通道状态。
• 若 HAT 的 PCB 修订、BOM、GPS 模组或 SX1262 外围电路发生变化，应以对应修订的原理图和新版丝印为准，并重新验证本文表格。