firefly-board

name	firefly-board
version	1.0.0
description	专用于用户的 Firefly 控制主板开发/运维/调试。触发场景：用户提到 Firefly 板子、控制主板、192.168.31.50、板子 SSH/ADB、ROS Noetic、mihomo 科学上网、GPIO/I2C/UART/串口调试、外设控制、板子开发环境、在板子上安装软件/跑程序/查日志/修复环境时使用。该技能包含板子的连接方式、已安装工具、硬件接口、敏感 GPIO、ROS/mihomo 配置和推荐操作流程。

Firefly Board Skill

目标

帮助 agent 快速接管用户的 Firefly 控制主板：连接、安装软件、运行 ROS、使用代理、调试 GPIO/I2C/UART、维护开发环境。

不要保存/输出明文密码、机场订阅 URL、代理凭据或私钥内容。 可以引用已有私钥路径。

板子身份

• 主机：Firefly 控制主板
• IP：192.168.31.50
• 系统：Ubuntu 20.04.6 LTS focal / aarch64
• 内核：Linux firefly 4.19.232 aarch64
• 主机名：firefly
• 根分区：约 24G，常见可用空间约 17G 左右

三种连接方式

优先用 SSH；SSH 失败时用无线 ADB 恢复/诊断。

1. SSH firefly 用户

ssh -i /var/minis/shared/ssh/firefly_192_168_31_50_ed25519 \
  -o StrictHostKeyChecking=no \
  -o UserKnownHostsFile=/var/minis/shared/ssh/known_hosts \
  firefly@192.168.31.50

2. SSH root 用户

ssh -i /var/minis/shared/ssh/firefly_192_168_31_50_ed25519 \
  -o StrictHostKeyChecking=no \
  -o UserKnownHostsFile=/var/minis/shared/ssh/known_hosts \
  root@192.168.31.50

3. 无线 ADB root shell

adb connect 192.168.31.50:5555
adb -s 192.168.31.50:5555 shell

已知 ADB 设备显示类似：

192.168.31.50:5555 device product:occam model:Nexus_4 device:mako

adb shell 进入的是 Firefly Linux root shell，不是普通 Android userspace：

uid=0(root)
Linux firefly 4.19.232 aarch64

SSH 公钥恢复流程

板子重烧录后可能没有 authorized_keys。若 ADB 可用，用本地公钥恢复 SSH：

PUB=$(cat /var/minis/shared/ssh/firefly_192_168_31_50_ed25519.pub)
adb -s 192.168.31.50:5555 shell "mkdir -p /home/firefly/.ssh /root/.ssh; printf '%s\n' '$PUB' > /home/firefly/.ssh/authorized_keys; printf '%s\n' '$PUB' > /root/.ssh/authorized_keys; chown -R firefly:firefly /home/firefly/.ssh; chmod 700 /home/firefly/.ssh /root/.ssh; chmod 600 /home/firefly/.ssh/authorized_keys /root/.ssh/authorized_keys"

然后测试：

ssh -i /var/minis/shared/ssh/firefly_192_168_31_50_ed25519 -o BatchMode=yes root@192.168.31.50 'id; uname -a'

apt / ROS 源

• Ubuntu ports 源：阿里云 http://mirrors.aliyun.com/ubuntu-ports/
• ROS Noetic 源：清华 TUNA

ROS 源文件：

/etc/apt/sources.list.d/ros-latest.list

内容：

deb https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu/ focal main

曾备份 apt 源到类似：

/root/apt-source-backup-YYYYMMDD-HHMMSS

已安装 ROS Noetic 基础环境

已安装：

ros-noetic-ros-base
python3-rosdep
python3-rosinstall
python3-rosinstall-generator
python3-wstool
build-essential

/root/.bashrc 和 /home/firefly/.bashrc 已添加：

source /opt/ros/noetic/setup.bash

验证命令：

source /opt/ros/noetic/setup.bash
echo $ROS_DISTRO
roscore
rosnode list
rostopic list

已验证：

ROS_DISTRO=noetic
roscore 可启动
rosnode list 显示 /rosout

建议：板子上优先使用 ros-noetic-ros-base，避免安装 GUI/RViz/Gazebo 等重组件，除非用户明确需要。

mihomo 代理环境

已安装：

/usr/local/bin/mihomo
Mihomo Meta v1.19.24 linux arm64

systemd 服务：

/etc/systemd/system/mihomo.service

配置目录：

/etc/mihomo/

主配置：

/etc/mihomo/config.yaml

常用命令：

systemctl status mihomo
systemctl restart mihomo
journalctl -u mihomo -f

当前订阅配置已成功导入，配置约 269K，mihomo -t 通过。代理测试曾通过：

curl -I -x http://127.0.0.1:7890 https://www.google.com
curl -I -x http://127.0.0.1:7890 https://github.com

当前配置为规则模式：

mode: rule

订阅配置中曾看到：

allow-lan: false
external-controller: 0.0.0.0:9091

实际代理端口常见监听：

127.0.0.1:7890

只给板子自身使用时没问题；若要局域网其它设备使用，需要改 allow-lan / bind-address。

Geo 数据文件

为避免未代理时无法从 GitHub 自动下载，已预置：

/etc/mihomo/geosite.dat
/etc/mihomo/geoip.dat
/etc/mihomo/Country.mmdb

如果订阅导入提示找不到 mmdb，可检查大小写或加软链接：

ln -sf /etc/mihomo/Country.mmdb /etc/mihomo/country.mmdb

订阅导入脚本

已放置：

/usr/local/sbin/update-mihomo-subscription

需要用户在交互终端里运行并粘贴订阅 URL；不要让用户把订阅 URL 发到聊天里。

/usr/local/sbin/update-mihomo-subscription

日志限制

mihomo 配置里 log-level: error，日志量很小。

已为 systemd journal 添加限制：

/etc/systemd/journald.conf.d/99-limit.conf

内容：

[Journal]
SystemMaxUse=100M
RuntimeMaxUse=50M
MaxRetentionSec=14day

查看日志占用：

journalctl --disk-usage

已安装常用开发工具

核心：

gcc / g++ 9.4
make
cmake 3.16.3
pkg-config
git 2.25.1
python3 3.8.10
python3-dev
python3-pip
python3-venv
ninja-build
ccache
tmux
vim / nano
curl / wget / jq
zip / unzip / tar
rsync
htop
tree

调试：

gdb 9.2
gdbserver
strace 5.5
ltrace 0.7.3

推荐长任务使用 tmux：

tmux new -s work
# Ctrl-b d detach
tmux attach -t work

外设调试工具

已安装：

gpiod
libgpiod-dev
python3-libgpiod
i2c-tools
python3-smbus
minicom
picocom
setserial

可用命令：

gpioinfo / gpioget / gpioset / gpiomon
i2cdetect / i2cget / i2cset / i2cdump
minicom / picocom / setserial

GPIO 信息

GPIO 设备：

/dev/gpiochip0
/dev/gpiochip1
/dev/gpiochip2
/dev/gpiochip3
/dev/gpiochip4
/dev/gpiochip5

范围：

gpiochip0: GPIO 0-31
gpiochip1: GPIO 32-63
gpiochip2: GPIO 64-95
gpiochip3: GPIO 96-127
gpiochip4: GPIO 128-159
gpiochip5: GPIO 511

sysfs GPIO 可用：

/sys/class/gpio/export
/sys/class/gpio/unexport

推荐优先使用 libgpiod：

gpioinfo
gpioget gpiochipN LINE
gpioset gpiochipN LINE=1
gpiomon gpiochipN LINE

Linux 全局 GPIO 与 gpiochip line 换算：

全局 GPIO = chip base + line offset
例如 gpio-59 = gpiochip1 line 27，因为 gpiochip1 base 是 32。

敏感/已占用 GPIO：不要随意拉高拉低

gpio-6   vcc5v0_host
gpio-17  power-rtl8821
gpio-21  bt_default_reset
gpio-28  vcc3v3_pcie
gpio-59  txrx_485ctl_enable
gpio-146 minipcie_power
gpio-154 reset5G

还有 debug 中见到的部分占用：

gpio-0 work
gpio-16 reset
gpio-29 enable
gpio-57 enable
gpio-77 bt_default_rts
gpio-86 chipen-rtl8821
gpio-94 reset
gpio-97 reset
gpio-98 vcc_dvdd
gpio-99 vcc_avdd
gpio-101 vcc_iovdd
gpio-102 headset_gpio
gpio-104 mdio-reset
gpio-107 out5G_power
gpio-108 hp-ctl
gpio-110 reset
gpio-113 vcc5v0_otg

操作 GPIO 前先确认物理引脚、功能复用和电平安全；不确定时只读不写。

I2C 信息

设备：

/dev/i2c-0
/dev/i2c-1
/dev/i2c-2
/dev/i2c-3
/dev/i2c-4

均识别为：

rk3x-i2c

查看总线：

i2cdetect -l

扫描总线，先征得用户确认，避免影响敏感设备：

i2cdetect -y 1

SPI 信息

当前未见：

/dev/spidev*

可能 SPI 未在设备树启用。若用户需要 SPI，优先检查设备树 overlay / kernel config / pinmux。

串口信息

console 相关：

/dev/ttyFIQ0

不要用于普通串口实验。

普通 UART：

/dev/ttyS1  IRQ 73  16550A
/dev/ttyS3  IRQ 74  16550A
/dev/ttyS4  IRQ 75  16550A
/dev/ttyS5  IRQ 76  16550A
/dev/ttyS7  IRQ 77  16550A
/dev/ttyS8  IRQ 78  16550A

USB 串口：

/dev/ttyUSB0
/dev/ttyUSB1
/dev/ttyUSB2

串口调试示例：

picocom -b 115200 /dev/ttyS1
# 退出：Ctrl-a 然后 Ctrl-x

查看串口：

setserial -g /dev/ttyS*

常用健康检查命令

ssh -i /var/minis/shared/ssh/firefly_192_168_31_50_ed25519 root@192.168.31.50 'hostname; uptime; df -h /; free -h'

adb connect 192.168.31.50:5555
adb -s 192.168.31.50:5555 shell 'id; uname -a; hostname -I'

systemctl --no-pager --full status mihomo
source /opt/ros/noetic/setup.bash && rosversion -d

操作原则

1. 优先 SSH root；SSH 不通时用 ADB root 修复。
2. 长时间安装/编译/roscore 用 tmux。
3. 安装包前可 apt-get update，但避免无意义大升级。
4. 不输出明文密码、订阅 URL、代理节点、私钥内容。
5. 控制 GPIO 前必须确认物理引脚与用途；敏感 GPIO 默认禁止写。
6. I2C 扫描、GPIO 写、串口改参数属于外设操作，若可能影响硬件，先说明风险并确认目标。
7. 生成脚本/配置文件时用文件写入工具；执行命令再用 shell。