FAQ

Quick Troubleshooting

电源按钮无法工作 → Power Button Not Working?
OLED 屏幕不工作 → OLED Screen Not Working?
RGB 灯不亮 → RGB LEDs Not Working?
风扇不工作 → Fan Not Working / Cannot Be Controlled?
仪表盘不显示数据 → The Dashboard Shows No Data
NVMe SSD 无法识别 → NVMe PIP Module Not Working?
NVMe SSD 被识别但导致系统重启 → NVMe SSD Detected but Causes System Restart on Read/Write?
PI5 无法启动 → PI5 Fails to Boot (Red LED)?

1. Hardware

Compatible Systems

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

Power Button

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

短按：开机 / 唤醒 OLED / 切换 OLED 页面。
长按 2 秒：安全关机（需配置 1. Configuring Shutdown to Deactivate GPIO Power）。
长按 5 秒：强制关机。

Power Button Not Working?

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

Copper Pipe Ends on the Tower Cooler

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

Raspberry Pi AI HAT+

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

Raspberry Pi AI Kit 由 Raspberry Pi M.2 HAT+ 与 Hailo AI 加速模块组合而成。

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

4.3-Inch Screen Is Black / Not Displaying?

4.3 英寸 DSI 屏幕即插即用，无需额外安装驱动。

备注

HDMI/USB 板上的 ON/AUTO 跳线仅控制扬声器音频输出，不影响屏幕显示。

如果屏幕黑屏或不显示，请检查以下事项：

确保 DSI 排线已连接到 Raspberry Pi 5 的正确 DSI 端口。
检查排线是否完全插入，卡扣是否压紧，触点方向是否正确。
运行以下命令确认系统是否检测到 DSI 屏幕：
```
sudo dmesg | grep -i dsi
```
如果检测到屏幕，你应该会看到类似 DSI display found 的输出。如果没有输出，则屏幕未被识别，请重新检查物理连接。

External HDMI Screen — Taskbar Only Appears on the 4.3-Inch Screen?

当你将外部 HDMI 显示器连接到 Pironman 5 Pro MAX 时，桌面任务栏可能仍然停留在内置的 4.3 英寸 DSI 屏幕上，而不是移动到外部显示器上。这是因为系统默认将 DSI 屏幕设置为主显示屏。

如果你希望将 HDMI 显示器设置为主屏幕，请按以下步骤操作：

创建启动脚本：

sudo nano /usr/local/bin/fix-primary-screen.sh

将以下内容添加到脚本中：

#!/bin/bash
# Check if an external HDMI monitor is connected
if wlr-randr | grep -q "HDMI-A-1"; then
    # Turn off the DSI screen first
    wlr-randr --output DSI-1 --off
    sleep 2
    # Re-enable DSI and place it to the right of HDMI
    wlr-randr --output DSI-1 --on --right-of HDMI-A-1
fi

赋予脚本可执行权限：

sudo chmod +x /usr/local/bin/fix-primary-screen.sh

将脚本添加到自动启动。编辑 labwc 自动启动文件：
```
nano ~/.config/labwc/autostart
```
添加以下行（& 表示在后台运行）：
```
/usr/local/bin/fix-primary-screen.sh &
```

2. Cooling and Fans

Fan Not Working / Cannot Be Controlled?

Pro MAX 采用官方 Raspberry Pi PWM 风扇控制方案。三个散热风扇均由 Raspberry Pi 系统直接控制，不依赖 pironman5 服务（因此你在命令行工具或仪表盘中不会看到风扇控制选项）。

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。

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

Dashboard Does Not Show Fan Speed?

Pro MAX 使用定制的 5 针 风扇，引脚定义如下：PWM / 5V / GND / RGB Data In / RGB Data Out。

这些风扇没有转速计（速度反馈）引脚，因此系统无法读取实际 RPM。仪表盘不显示风扇速度是正常现象。

风扇速度由 Raspberry Pi 的原生 PWM 温度曲线控制：

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

3. OLED and RGB

OLED Screen Not Working?

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

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

参见 Compatible Systems。
OLED 屏幕首次通电可能只显示像素方块。您需要根据 Set Up on Raspberry Pi/Ubuntu/Kali/Homebridge OS 的说明完成配置，之后即可正常显示信息。
使用以下命令检测 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
```

How to Customize the OLED Display?

如果您想自定义 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

RGB LEDs Not Working?

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

参见 Compatible Systems。
运行以下命令启用 SPI：
```
sudo raspi-config
```
进入：

3 Interfacing Options → I3 SPI → YES

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

How to Wake Up the OLED Screen

为了节省电量并延长屏幕寿命，OLED 屏幕在一段时间无操作后会自动关闭。这是正常设计，不会影响设备功能。

备注

如需配置 OLED 屏幕（如开关、休眠时间、旋转等），请参考通过 Dashboard 查看与控制或 Control with Commands。

4. Dashboard and Software

The Dashboard Shows No Data

如果仪表盘不显示数据，请先打开仪表盘的日志页面，检查是否有与 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 软件。

How to Disable the Web Dashboard

安装 pironman5 模块后，您可以访问通过 Dashboard 查看与控制。

若不需要该功能，并希望减少 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

How to Uninstall and Reinstall the Pironman 5 Software

卸载当前的 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

How to Control Components Using the `pironman5` Command

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

Control with Commands

`pip install piper-tts` Fails with “Could Not Find a Version”?

在 Pironman 5 Pro MAX 上安装 sunfounder-voice-assistant 时，可能会遇到以下错误：

ERROR: Could not find a version that satisfies the requirement piper-tts==1.3.0
ERROR: No matching distribution found for piper-tts==1.3.0

此错误的原因是 piper-tts 1.3.0 仅提供 64 位（aarch64）的 wheel 包。如果你的 Raspberry Pi 运行的是 32 位 操作系统，pip 无法找到兼容的包。

解决方法： 安装 64 位版本的 Raspberry Pi OS。

检查当前系统架构：
```
uname -m
```
- aarch64 → 64 位（无问题）
- armv7l → 32 位（需要升级）
使用 Raspberry Pi Imager 将 64 位 Raspberry Pi OS 镜像写入你的存储设备。
安装 64 位操作系统后，重新安装 pironman5 软件和 sunfounder-voice-assistant。

5. Boot and Storage

PI5 Fails to Boot (Red LED)?

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

检查 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 Module Not Working?

确认您的 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. 安装操作系统。

如果线路连接正确且操作系统已安装，但 NVMe SSD 仍无法启动，请尝试使用 Micro SD 卡启动以验证其他组件功能。确认无误后，参考 3. 配置从 SSD 启动。
如果完成以上步骤后问题仍然存在，请发送邮件至 service@sunfounder.com。我们会尽快回复。

NVMe SSD Detected but Causes System Restart on Read/Write?

在某些情况下（尤其是 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，然后重新安装操作系统。

How to Change the Raspberry Pi Boot Order Using Commands

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

3. 配置从 SSD 启动

How to Modify the Boot Order with Raspberry Pi Imager

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

2. 更新 Bootloader

How to Copy the System from the SD Card to an NVMe SSD

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

将系统从 Micro SD 复制到 NVMe SSD

6. Advanced Usage

How to Remove the Protective Film

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

How to Install OpenSSH via Powershell?

当你使用 ssh <username>@<hostname>.local（或 ssh <username>@<IP address>）连接 Raspberry Pi 时，出现以下错误提示：

ssh: The term 'ssh' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the
spelling of the name, or if a path was included, verify that the path is correct and try again.

说明你的电脑系统版本过旧，未预装 OpenSSH，需按照以下教程手动安装。

在 Windows 桌面搜索栏中输入 powershell，右键点击 Windows PowerShell，选择 Run as administrator（以管理员身份运行）。

使用以下命令安装 OpenSSH.Client：

Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

安装完成后，将返回以下输出：

Path          :
Online        : True
RestartNeeded : False

使用以下命令验证安装：

Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*'

现在提示你 OpenSSH.Client 已成功安装：
```
Name  : OpenSSH.Client~~~~0.0.1.0
State : Installed

Name  : OpenSSH.Server~~~~0.0.1.0
State : NotPresent
```
警告

如果没有出现上述提示，说明你的 Windows 系统版本仍然过旧，建议安装第三方 SSH 工具，如 PuTTY。
现在重启 PowerShell，继续以管理员身份运行。此时你将能够使用 ssh 命令登录 Raspberry Pi，系统将提示你输入之前设置的密码。

If I Set Up OMV, Can I Still Use the Pironman5’s Function?

可以。OpenMediaVault 是在 Raspberry Pi 系统上搭建的服务。请按照 Set Up on Raspberry Pi/Ubuntu/Kali/Homebridge OS 的步骤继续配置，即可正常使用 Pironman5 的功能。

Raspberry Pi Camera Not Working?

当摄像头无法正常工作时，90% 的问题都与排线连接或摄像头硬件本身有关。

首先，使用 rpicam-hello --list-cameras 确认系统是否检测到摄像头。如果检测成功，你应该会看到类似如下的信息：

Available cameras
-----------------
0 : ov5647 [2592x1944] (/base/axi/pcie@1000120000/rp1/i2c@88000/ov5647@36)

如果未检测到摄像头，请检查排线是否插反或未完全插入。如果问题仍然存在，请尝试更换排线或摄像头模组进行交叉测试。

Can I Install Home Assistant OS on the Pironman 5 Pro MAX?

Pironman 5 Pro MAX 没有专用的 Home Assistant 插件。但你可以使用 Pironman 5 MAX 的插件代替——请按照 SunFounder 插件仓库指南操作。

请注意以下限制：

4.3 英寸屏幕：Home Assistant OS 是 Lite 系统，没有桌面环境。Pro MAX 内置的 4.3 英寸屏幕将无法显示任何内容。
NVMe PIP 双 SSD：Home Assistant OS 无法读取 Pro MAX 双 NVMe PIP 模块上的两个 NVMe SSD。
OLED 屏幕和 RGB LED：安装插件后这些组件正常工作，无需额外配置。
CPU 风扇：CPU 风扇需要在 Home Assistant OS 下手动配置。将以下内容添加到 /boot/firmware/config.txt：
```
dtparam=cooling_fan=on
dtparam=fan_temp0=40000
dtparam=fan_temp0_hyst=10000
dtparam=fan_temp0_speed=125
```
保存并重启后，CPU 风扇将由 Raspberry Pi 系统根据 CPU 温度控制。你也可以通过 pinctrl 命令手动控制，详见 Fan Not Working / Cannot Be Controlled?。