inspired-by-atmosphere/ops-troubleshooting-skills/dev-board-bringup

开发板 / 单板机 与 PC 互联（上手 → 远程 shell）

When to Use（触发场景）

• "本机有没有接上开发板""板子插上电脑没反应"
• "怎么连上板子 / 怎么 SSH 进板子 / 用不用网线"
• 新板子到手第一步，或板子进不去系统要救

0. 先分清这条线是「数据通道」还是「主机/供电口」

板子上的 Type-C/USB 口在手册里有三种身份，只有前两种能让 PC 认出设备：

判定用 windows-hardware-enum 的四维枚举（USB VID 全集 / 串口 / Status≠OK / setupapi 日志）。四维全空 = 这条链路不是设备链路，别往"装驱动"方向排查。

1. 选通道（按场景，不按手头方便）

千兆网 ≈ 119 MB/s，比串口快约 1 万倍——量级差就是选通道的第一判据；串口只当"保险绳"（板子没进系统也能出日志）。

2. 找板子 IP——不要猜

1. 先确认 PC 自己在哪个网：Get-NetConnectionProfile + netsh wlan show interfaces（拿 SSID 和网段），板子必须连同一个 SSID 才互通；
2. 板子本地：hostname -I / ip addr show wlan0（有线看 eth0）；
3. 拿不到就在 PC 侧扫：arp -a 过滤网段、路由器 DHCP 客户端列表；
4. IP 会变 → 要固定就在路由器后台按板子 MAC 做静态绑定。

3. 登录

• 默认凭据随板厂不同（香橙派 AIpro = HwHiAiUser / Mind@123），首次登录常强制改密；
• Windows 自带 OpenSSH 客户端够用（先 ssh -V 确认有没有），要拖文件再上 MobaXterm；
• 串口侧：串口工具选对 COM 口 + 115200 8N1，直接回车出登录提示。

Pitfalls

• 别用「注销 / 重启显示会话」去验证桌面配置：lightdm 的 autologin 只在开机启动时生效一次，手动注销后必然停在 greeter —— 用户会以为"免密坏了"，其实配置完好、下次重启照旧免密直进桌面。更坑的是板子的 WiFi 连接常带 connection.permissions: user:<用户>（NM 默认把新建连接绑给创建者），会话一结束 NetworkManager 立刻停掉 WiFi → 板子彻底失联，看起来像整机死机。分辨真假：能 SSH 时看 uptime -s（时间没变=压根没重启过，别叫人断电）；失联时让用户在本机登录一次即可恢复。根治（需 root）：sudo nmcli connection modify <连接名> connection.permissions ""。
• 板端普通用户读不到系统日志：HwHiAiUser 不在 adm/systemd-journal 组 → journalctl、/var/log/lightdm/lightdm.log 全被拒（提示需要 adm 组），查日志必须 root。
• 板端 sudo 一律免交互：ssh 非交互拿不到 tty，裸 sudo <cmd> 会报 a terminal is required → 用 echo '<密码>' | sudo -S <cmd>；安装器还要按 y 接受许可时，把两条 stdin 源串成一条管道 (echo '<密码>'; yes) | sudo -S bash <包> --install（第一行给 sudo 当密码，其余给安装器）；要把环境变量带进 sudo 用 sudo -S env VAR=<值> <cmd>（sudo -E 常被 env_reset 拦掉）。
• 板子突然掉线先等再判：ping 不通 + ssh 报 Connection closed by remote host，常见原因是用户自己关机/断电，或磁盘告急后的异常重启 → 等 1~2 分钟重连确认，别当场改方案或宣告硬件故障。
• Micro USB 线必须是数据线：市面上大量 Micro USB 是纯充电线（无线芯），插上零反应——先换线再怀疑板子。
• WiFi 天线必须接：不接那两根小天线，5G 频段基本扫不到。
• 板子别连校园网 SSID：校园网常见"一人一设备"，宿舍路由（Z503）已是认证对象，板子再连校园网 SSID 会把认证设备挤下线 → 全屋断网。只连宿舍自己的 WiFi 或手机热点。
• AP 隔离：同 WiFi 下两台设备互 ping 不通 = 路由器开了客户端隔离 → 两边都改连手机热点。
• Type-C 电源口给不了板子电（需 PD 20V/65W）：板子不亮不是坏了，用官方适配器供电。

4. 屏幕方向（X11 / XFCE）——改哪里才持久

香橙派 AIpro 的厂商镜像里 XFCE 把 X 输出默认设成 180°（画面上下颠倒），配置烘焙在镜像的 ~/.config/xfce4/xfconf/xfce-perchannel-xml/displays.xml（Rotation 属性，单位是度：0/90/180/270），Default 与 Fallback 两个 profile 都要改，改完重登录/重启仍生效。

• 查当前实况：DISPLAY=:0 xrandr --query，贴整行看。⚠️ 别用 grep -oE "inverted|normal" 判方向 —— 行尾括号里的 (normal left inverted right ...) 是可选方向清单，同样含这些词，必然给假阳性。真规则：当前方向 = 几何尺寸后面紧邻的裸词，且 normal 时该词被省略（VGA-1 connected primary 1920x1080+0+0 (normal left ...) = normal；... 1920x1080+0+0 inverted (normal left ...) = 180°）。另：同一块屏在 X 里可能叫 VGA-1、内核日志里叫 HDMI0，且常报 EDID 0 字节，不代表没接显示器。
• 改持久值：DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus xfconf-query -c displays -p /Default/<输出>/Rotation -s 0（Fallback 同名属性同样处理）。改前先 cp -a 备份该 xml。
• 只写 xfconf 不会立刻生效，必须再跑一次 DISPLAY=:0 xrandr --output <输出> --rotate normal|inverted|left|right 让屏幕当场转过来；xfconf 值负责下次登录自动应用。
• 要验“持久”就整机重启一次（别注销），起来后一并核三件事：① who 里有开机时刻的 tty7 :0 会话 = 免密直进桌面成功（无需任何人输密码）；② 没有 greeter 进程（lightdm-gtk-greeter / slick-greeter）= 没卡在登录页；③ 输出行无裸旋转词 = 方向仍是改后的值。附带一条：重启后在无人登录状态下 SSH 仍能通，正好证明 WiFi 那条 connection.permissions 已解绑。
• 改系统级 NetworkManager 连接（如上面的 connection.permissions）普通用户会被 polkit 拒（Insufficient privileges），必须 root。
• 开机阶段（引导日志、控制台）不受 XFCE 影响，要一起转得动内核 cmdline 的 fbcon=rotate:N，属另一条线。

支持文件

• references/orange-pi-aipro.md — 香橙派 AIpro 8T/20T 接口差异、默认凭据、官方远程登录流程与文档入口。