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