FAQ

快速故障排除

电源按钮不工作 → 电源按钮不工作？
OLED 屏幕不工作 → OLED 屏幕无显示？
RGB 灯不工作 → RGB LED 无法工作？
GPIO 风扇不工作 → GPIO 风扇不工作？
CPU 风扇不转 → CPU 风扇不工作？
仪表盘不显示数据 → 仪表盘不显示数据
NVMe SSD 无法识别 → NVMe PIP 模块无法正常工作？
NVMe SSD 被识别但导致系统重启 → NVMe SSD 被识别但在读写时导致系统重启？

1. 硬件

兼容系统

以下系统已通过 Raspberry Pi 5 的兼容性测试：

电源按钮

该电源按钮为 Raspberry Pi 5 的扩展电源键，功能与树莓派 5 自带电源按钮一致。

短按：开机 / 唤醒 OLED / 切换 OLED 页面。
长按 2 秒：安全关机（需配置 1. 配置关机时关闭 GPIO 电源）。
长按 5 秒：强制关机。

电源按钮不工作？

首先，确认预期的电源按钮行为：
- Raspberry Pi OS Desktop：快速按两次电源按钮即可关机。长按 5 秒强制硬关机。关机状态下按一次开机。
- Raspberry Pi OS Lite：按一次电源按钮关机。长按 5 秒强制硬关机。关机状态下按一次开机。
检查电源转换器引脚是否与 Raspberry Pi 5 的 J2 焊盘正确对齐（位于 RTC 电池连接器和板边之间）。
检查电源转换器插座内的引脚是否与电源按钮连接器正确对齐。如有必要，重新连接电源按钮线缆。
使用螺丝刀短暂短接电源转换器插座上连接按钮的两个引脚。如果 Pi 启动，则按钮本身可能有故障；否则，问题可能出在转换器板或 Pi 5 连接上。

塔式散热器铜管尾端

塔式散热器顶部的 U 型热管在出厂时会进行压扁处理，以便更好地穿过铝制散热鳍片，这属于正常的生产工艺。

Raspberry Pi AI HAT+

Raspberry Pi AI HAT+ 与 Pironman 5 MAX 不兼容。

Raspberry Pi AI 套件由 Raspberry Pi M.2 HAT+ 与 Hailo AI 加速模块组成。

您可以将 Hailo AI 加速模块从 Raspberry Pi AI 套件中拆下，直接插入 Pironman 5 MAX 的 NVMe PIP 模块中使用。

我能否使用 Pironman5 Max 的振动开关功能？

从 v1.3.6 版本开始，OLED 唤醒功能使用电源按键。您必须移除振动开关跳线，以避免占用 Raspberry Pi GPIO 引脚并防止潜在的冲突。请检查是否存在此跳线；如果没有，请忽略本通知。

2. 散热与风扇

CPU 风扇不工作？

Pironman 5 上的 CPU 风扇由树莓派系统控制。CPU 风扇转速取决于树莓派 5 的 CPU 温度。

默认 CPU 风扇曲线：

< 50°C：关闭（0%）
50°C+：低速（30%）
60°C+：中速（50%）
67.5°C+：高速（70%）
75°C+：全速（100%）

检查当前 CPU 温度（示例输出：temp=48.7'C）：

vcgencmd measure_temp

您可以使用以下命令手动控制 CPU 风扇：

pinctrl FAN_PWM op dl   # 启用风扇（低电平有效）
pinctrl FAN_PWM op dh   # 禁用风扇（高电平有效）
pinctrl FAN_PWM a0      # 自动模式

您也可以通过编辑以下文件来调整 CPU 风扇温度阈值：

nano /boot/firmware/config.txt

添加：

dtparam=cooling_fan=on
dtparam=fan_temp0=40000
dtparam=fan_temp0_hyst=10000
dtparam=fan_temp0_speed=125

此配置将在 40°C 时启动 CPU 风扇，PWM 速度级别为 125。

保存文件后，重启树莓派以使更改生效。

GPIO 风扇不工作？

首先，检查 IO 扩展板上的 FAN 跳线帽是否已正确安装。

然后将 GPIO 风扇设置为 Always On 模式，检查风扇是否开始旋转。

sudo pironman5 -gm 0

您也可以将 GPIO 风扇直接连接到树莓派的 5V 和 GND 引脚进行测试。

如果风扇直接连接时正常旋转，则问题可能与 IO 扩展板有关。请联系我们获取进一步支持。

如果问题仍然存在，请打开仪表盘的日志页面检查错误消息。您也可以将以下日志文件发送给我们：

cat /var/log/pironman5/pironman5.log

3. OLED 与 RGB

OLED 屏幕无显示？

若 OLED 屏幕没有显示或显示异常，请依照以下步骤排查：

确保 OLED 屏幕的 FPC 排线已牢固连接。建议重新连接后再上电启动。
确认树莓派运行的是支持的操作系统。

参见兼容系统。
OLED 屏幕首次通电可能只显示像素方块。您需要根据 4. 设置或安装软件的说明完成配置，之后即可正常显示信息。
使用以下命令检测 OLED 的 I2C 地址 0x3C 是否被识别：
```
sudo i2cdetect -y 1
```
- 若检测到 I2C 地址 0x3C，请重启 Pironman 5 服务：
```
sudo systemctl restart pironman5.service
```
- 若未检测到，请开启 I2C：
```
sudo nano /boot/firmware/config.txt
```
  添加：
```
dtparam=i2c_arm=on
```
  保存文件并重启树莓派。
如果问题仍然存在，请将以下日志文件发送给我们：
```
cat /var/log/pironman5/pironman5.log
```

RGB LED 无法工作？

J9 上方的 IO 扩展板有两个引脚用于连接 RGB 灯至 GPIO10，请确保这两个引脚上的跳线帽已正确安装。
确认树莓派运行的是兼容的操作系统。

参见兼容系统。
运行以下命令启用 SPI：
```
sudo raspi-config
```
进入：

3 Interfacing Options → I3 SPI → YES

然后重启树莓派。
如果问题仍然存在，请将以下日志文件发送给我们：
```
cat /var/log/pironman5/pironman5.log
```

如何自定义 OLED 显示？

如果您想自定义 OLED 显示内容，例如添加自定义的 2-4 位图像显示，您可以通过以下两种方式修改 OLED 页面文件。

方法一：直接修改已安装的文件
1. 列出 OLED 页面文件：
```
ls /opt/pironman5/venv/lib/python3.13/site-packages/pm_auto/addons/oled/pages/
```
2. 修改所需的 Python 文件。
3. 重启服务以应用更改：
```
sudo systemctl restart pironman5.service
```

方法二：克隆并重新安装 ``pm_auto``

克隆 pm_auto 仓库：

git clone -b 1.4.x https://github.com/sunfounder/pm_auto/

进行更改后，重新安装修改后的包：

sudo /opt/pironman5/venv/bin/pip3 uninstall pm_auto -y && \
sudo /opt/pironman5/venv/bin/pip3 install ~/pm_auto --no-build-isolation && \
sudo chown -R pironman5:pironman5 /opt/pironman5

重启服务：

sudo systemctl restart pironman5.service

测试和调试

查看运行日志：

journalctl -xefu pironman5.service

您也可以停止服务并手动运行以加快测试：

sudo systemctl stop pironman5.service
sudo systemctl restart pironman5.service

4. 仪表盘与软件

仪表盘不显示数据

如果仪表盘不显示数据，请先打开仪表盘的日志页面，检查是否有与 influxdb 相关的错误消息。

常见错误包括：

database not found
failed to connect to influxdb
connection refused
timeout

您可以尝试以下步骤来解决问题。

清除浏览器缓存，或使用 无痕/隐私 模式重新打开仪表盘页面。

检查以下服务是否正常运行：

sudo systemctl status pironman5 --no-pager
sudo systemctl status influxdb --no-pager

两个服务都应显示：

active (running)

如果任一服务运行不正常，请重新启动它们：
```
sudo systemctl restart influxdb
sudo systemctl restart pironman5
```
然后等待约 30 秒，刷新仪表盘页面。
检查 pironman5 数据库是否存在：
```
influx
```
然后运行：
```
SHOW DATABASES;
```
您应该看到：
```
pironman5
_internal
```
如果数据库缺失或损坏，您可以尝试从仪表盘中清除历史数据：

Settings → Clear All Data
如果尝试以上所有步骤后问题仍然存在，我们建议重新安装 Raspberry Pi OS 和 Pironman 5 软件。

如何禁用 Web Dashboard？

安装 pironman5 模块后，您可以访问通过控制面板查看和控制。

若不需要该功能，并希望减少 CPU 和内存占用，可以在安装 pironman5 时添加 --disable-dashboard 参数来禁用控制面板：

cd ~/pironman5
sudo python3 install.py --disable-dashboard

如果您已经安装了 pironman5，可以卸载仪表盘模块和 influxdb：

/opt/pironman5/env/bin/pip3 uninstall pm-dashboard influxdb
sudo apt purge influxdb
sudo systemctl restart pironman5

如何卸载并重新安装 Pironman 5 软件

卸载当前的 pironman5 软件：

cd ~/pironman5
sudo python3 install.py --uninstall

按提示重启树莓派，然后删除 pironman5 目录：
```
cd ~/
sudo rm -rf pironman5
```

运行以下命令为您的 Pironman 5 型号重新安装软件：

curl -sSL "https://raw.githubusercontent.com/sunfounder/sunfounder-installer-scripts/main/pironman5/install.sh" | sudo bash

如何使用 `pironman5` 命令控制组件

您可以参考以下教程，使用 pironman5 命令控制 Pironman 5 系列的组件。

通过命令行控制

5. 启动与存储

如果我设置了 OMV，还能使用 Pironman5 的功能吗？

可以。OpenMediaVault 是在树莓派系统上进行的设置。请继续按照在 Raspberry Pi OS/Ubuntu/Kali Linux/Homebridge 上的配置的步骤完成配置。

PI5 无法启动（红灯常亮）？

此问题可能是由于系统更新、启动顺序更改或引导程序损坏导致的。您可以尝试以下步骤来解决该问题：

检查 USB-HDMI 适配器连接
- 请仔细检查 USB-HDMI 适配器是否牢固连接到 PI5。
- 尝试拔下并重新插入 USB-HDMI 适配器。
- 然后重新连接电源，检查 PI5 是否能正常启动。
在机箱外测试 PI5
- 如果重新插拔适配器仍未解决问题：
- 将 PI5 从 Pironman 5 机箱中取出。
- 使用电源适配器直接为 PI5 供电（不通过机箱）。
- 检查是否能够正常启动。
恢复引导程序
- 如果 PI5 仍无法启动，可能是引导程序已损坏。您可以参考此教程：2. 更新引导程序（Bootloader），并选择从 SD 卡或 NVMe/USB 启动。
- 将准备好的 SD 卡插入 PI5，通电后至少等待 10 秒。恢复完成后，取出并重新格式化 SD 卡。
- 然后使用 Raspberry Pi Imager 烧录最新的 Raspberry Pi OS，将卡插回并再次尝试启动。

NVMe PIP 模块无法正常工作？

确认您的 NVMe SSD 兼容。请参考兼容 NVMe SSD 列表查看已验证、稳定且兼容的驱动器。
确保连接 NVMe PIP 模块与 Raspberry Pi 5 的 FPC 排线已牢固连接。
确认您的 SSD 已正确安装并固定在 NVMe PIP 模块上。
检查 NVMe PIP 模块的 LED 状态：

确认所有连接后，给设备上电并观察 NVMe PIP 模块上的两个指示灯：
- PWR LED：应常亮。
- STA LED：应闪烁，表示正常工作。
- 如果 PWR LED 亮但 STA LED 不闪烁，表示 NVMe SSD 未被 Raspberry Pi 识别。
- 如果 PWR LED 不亮，请短接模块上的 “Force Enable” 引脚。如果 PWR LED 亮起，可能是 FPC 排线松动或系统不支持 NVMe。
确认您的 NVMe SSD 已正确安装操作系统。参考 3. 安装操作系统。

如果问题仍然存在，请将以下日志文件发送给我们：
```
cat /var/log/pironman5/pironman5.log
```

NVMe SSD 被识别但在读写时导致系统重启？

在某些情况下（尤其是 WD Blue SN5000），NVMe SSD 可能被 Raspberry Pi 5 识别，但在读写操作时导致系统重启。这是 SSD 与 Raspberry Pi 5 之间的 PCIe 兼容性/稳定性问题，不是 Pironman 5 的硬件故障。

请尝试以下步骤解决问题：

将 Raspberry Pi 5 引导程序更新到最新版本：
```
sudo rpi-eeprom-update -a
sudo reboot
```
在 /boot/firmware/config.txt 中添加以下行以强制使用 PCIe Gen3 速度：
```
dtparam=pciex1_gen=3
```
在内核命令行中添加 pcie_aspm=off 以禁用 ASPM（主动状态电源管理）。编辑 /boot/firmware/cmdline.txt 并将其附加到现有行末尾（不要创建新行）：
```
pcie_aspm=off
```
备注

pcie_aspm=off 通常是关键修复方法——PCIe ASPM 问题在 Raspberry Pi 5 上非常常见，可能导致 NVMe 驱动器在大量 I/O 操作时随机断开或重启系统。
应用以上更改后，重新启动 Raspberry Pi：
```
sudo reboot
```
如果问题仍然存在，请重新分区并格式化 NVMe SSD，然后重新安装操作系统。

如何通过命令修改树莓派的启动顺序

如果您已登录树莓派系统，可以通过命令修改启动顺序。

3. 配置从 SSD 启动

如何用 Raspberry Pi Imager 修改启动顺序？

除了在 EEPROM 配置中修改 BOOT_ORDER，您还可以使用 Raspberry Pi Imager 更改启动顺序。

2. 更新引导程序（Bootloader）

如何将系统从 SD 卡复制到 NVMe SSD？

如果您没有 NVMe 转 USB 适配器，可以先将系统安装到 Micro SD 卡上，成功启动后，再将系统复制到 NVMe SSD。

将系统从 Micro SD 卡复制到 NVMe SSD

6. 高级用法

如何撕下亚克力板的保护膜

包装内包含两块亚克力板，正反两面均贴有黄色或透明保护膜，用于防止刮花。保护膜可能较难揭除，可使用螺丝刀轻轻刮起角落，再慢慢撕下整张膜。