EEPW论坛

第一篇：Arduino Uno Q 通电后必做的几件事

本文目标：从通电到能够稳定通过 SSH 远程登录 Arduino Uno Q，解决这一路上遇到的每一个坑。

适用同学：刚拿到这块板子，或者准备入手的开发者。不需要你有 Linux 深度背景，但我会把背后的原理讲清楚，让你知其然也知其所以然。

一、先认识一下这块板子

【图片 1】Arduino Uno Q 板子外观：

Arduino Uno Q 不是传统意义上的单片机开发板。它本质上是一台运行 Debian 13 (Trixie) 的 ARM64 迷你主机，搭载了：

• MPU（主处理器）：Qualcomm Dragonwing QRB2210（4× Cortex-A53 @ 2.0GHz，运行 Debian Linux）

• MCU（实时控制器）：STMicroelectronics STM32U585（Cortex-M33 @ 160MHz，运行 Zephyr RTOS + Arduino Core）

• 内存：4GB LPDDR4X（另有 2GB 入门版）

• 存储：32GB eMMC（另有 16GB 入门版）

• 外设接口：USB-C（供电+数据+DisplayPort Alt-Mode）、可通过 USB Hub 扩展 USB-A 和 HDMI

这意味着你可以把它当作一台树莓派来使用——有完整的桌面环境、可以装软件、可以跑 Docker、可以 SSH 远程管理。但它又比树莓派更贴近 Arduino 生态，因为板上还保留了 Arduino 的 GPIO 接口，可以像传统 Uno 一样接传感器和执行器。

所以它的定位是：既能当 Linux 开发主机，又能当嵌入式控制器。

初次使用的时候，你可以把 Arduino Uno Q 连接到电脑上，使用Arduino App Lab进行设置然后使用，也可以直接连接显示屏进行设置然后使用。

下面，我就是通过USB Hub连接了显示屏来使用的。

【图片 2】USB Hub 连接实物图：

二、上电时序：

2.1 问题现象

如果你按照直觉操作——先把所有设备（鼠标、键盘、显示器）连到 USB Hub，再把 Hub 的 type-c 线插到 Arduino Uno Q，最后通电——结果很可能是：

• HDMI 有画面 ✓

• 键盘灯不亮 ✗

• 鼠标没反应 ✗

这个问题在 Arduino 官方论坛上有讨论：UNO Q, USBC dongle issue

2.2 根本原因：PD 供电协商时序

USB-C 的供电（Power Delivery，简称 PD）是一个协商过程。当 Uno Q 作为主设备通过 USB-C 连接 USB Hub 时，双方需要协商供电角色：

• Source（供电方）：Hub 应该先作为 Source，给下游的鼠标、键盘供电

• Sink（受电方）：Uno Q 作为 Sink，从 Hub 取电

如果 Hub 和 Uno Q 同时上电，PD 控制器可能来不及完成完整的角色协商，导致 Hub 没有稳定输出 5V 给下游设备。结果就是：Hub 本身亮了，但鼠标和键盘因为没拿到电而不工作。

先给 Hub 单独供电，就是为了确保 Hub 先完成 Source 角色初始化，再和 Uno Q 握手。

2.3 正确上电步骤

1. 准备一个带 PD 供电口的 USB-C Hub（必须支持外接电源）

2. 把 USB 鼠标、键盘接到 Hub 的 USB-A 口

3. 把 HDMI 显示器接到 Hub 的 HDMI 口

4. 用 5V/3A 电源给 Hub 的 PD 口供电（Hub 上的设备指示灯应该亮了）

5. 等 2-3 秒，确认 Hub 稳定工作后，再把 Hub 的 USB-C 数据线插到 Uno Q

6. 等系统启动，看到桌面后：

• 按一下 Caps Lock，指示灯亮了 → 键盘正常

• 晃一下鼠标，指针动了 → 鼠标正常

功率提示：官方推荐 5V/3A（15W）。如果 Hub 本身带多个设备，功率需求更高，建议用足 3A 的电源，不要用普通的手机充电器（通常只有 5V/2A）。

三、设置网络：

3.1 系统自带的网络管理器

Uno Q 预装的是 XFCE 桌面环境，网络管理由 NetworkManager 负责。启动后：

1. 桌面右上角有一个网络图标

2. 点击图标 -> "Wi-Fi 网络" -> 选择你的 SSID

3. 输入密码连接

【图片 3】XFCE 桌面网络图标：

【图片 4】WiFi 连接对话框：

注意：第一次启动时系统会自动打开 Arduino App Lab，这是 Arduino 官方提供的可视化编程环境，可直接进行基本参数和网络的配置。

【图片 5】Arduino App Lab 界面：

3.2 为什么不用命令行配网络？

你当然可以用 nmcli 命令行配置：

nmcli dev wifi list          # 扫描 WiFi
nmcli dev wifi connect "SSID" password "密码"  # 连接

但既然有桌面环境，图形界面配置更直观，而且对于不熟悉 nmcli 的同学来说门槛更低。而且 NetworkManager 的配置会自动持久化到 /etc/NetworkManager/system-connections/，重启后仍然有效。

四、mDNS 配置：

4.1 问题：连上 WiFi 了，但 hostname.local 不通

假设你的设备 hostname 是 my-uno-q。按照常理，同一局域网内的其他设备应该可以通过 my-uno-q.local 找到它。这样的好处是即使不知道Uno Q的ip地址，也可以访问它。但你会发现：

# 在另一台电脑上
ping my-uno-q.local
# ping: cannot resolve my-uno-q.local: Unknown host

但直接 ping IP 又是通的：

ping 192.168.1.198 
  
# 可以通

这说明网络层没问题，问题在服务发现层。

4.2 mDNS 是什么？

传统的 DNS 需要一个中央 DNS 服务器来维护域名到 IP 的映射。但在家庭/小型局域网中，我们往往没有 DNS 服务器。这时候就需要 mDNS（Multicast DNS）：

• 每台设备自己维护自己的 hostname

• 当需要解析 xxx.local 时，查询方发送一个多播 UDP 包到 224.0.0.251:5353

• 拥有该 hostname 的设备收到后，直接回复自己的 IP 地址

• 不需要中央服务器，完全去中心化

在 Linux 上，实现 mDNS 的服务是 avahi-daemon。macOS 上对应的是 mDNSResponder。

4.3 为什么 avahi 默认不发布主机名？

检查一下 avahi 的配置：

cat /etc/avahi/avahi-daemon.conf | grep publish-workstation
# 输出：publish-workstation=no

avahi 的设计哲学是"安全优先"。publish-workstation=yes 会让设备在局域网中广播自己的主机名和 IP，这在某些安全敏感的环境中可能是不希望的（比如在公共 WiFi 中暴露设备信息）。所以 Debian 默认关闭了主机名发布。

但对于普通开发环境来说，我们需要这个广播，能够让其他电脑方便找到。

4.4 修复步骤

# 1. 修改配置，启用主机名发布
sudo sed -i 's/publish-workstation=no/publish-workstation=yes/' /etc/avahi/avahi-daemon.conf
# 2. 确认修改成功
grep publish-workstation /etc/avahi/avahi-daemon.conf
# 应输出: publish-workstation=yes
# 3. 重启 avahi 服务
sudo systemctl restart avahi-daemon
# 4. 验证：在另一台电脑上测试
ping my-uno-q.local

【图片 6】mDNS 修复后 ping 成功：

4.5 进阶：avahi 还发布了什么？

除了主机名，avahi 还可以发布服务。比如 SSH 服务：

# 查看本机通过 mDNS 发布了哪些服务
avahi-browse -a   # 如果安装了 avahi-utils

如果你在其他 Linux 设备上安装了 avahi-utils，你可以看到 Uno Q 不仅发布了主机名，还发布了 _ssh._tcp 服务。这就是 macOS 上"Finder -> 网络"中能看到其他设备的原理。

4.6 macOS 用户的特殊坑：Microsoft Edge 占用 mDNS 端口

如果你是 macOS 用户，即使 avahi 配置正确了，仍然可能发现 .local 域名不通。这时候要检查：Microsoft Edge 是否占用了 UDP 5353 端口。

# macOS 上检查谁占用了 mDNS 端口
lsof -i UDP:5353

如果看到 Microsoft 进程占用了端口，说明 Edge 的实验性功能（--enable-experimental-web-platform-features）启动了某些网络实验，劫持了 mDNS 端口。这会导致 macOS 的系统 mDNSResponder 无法正常工作。

修复方法：

# 1. 完全关闭 Edge
pkill -f "Microsoft Edge"
# 2. 重启 mDNSResponder（macOS 会自动重新启动它）
sudo killall -9 mDNSResponder
# 3. 等待几秒后测试
ping my-uno-q.local

长期避免：在 Edge 地址栏访问 edge://flags/，搜索并禁用与 mDNS 相关的实验性功能。

五、SSH 配置：从密码登录到密钥登录

5.1 先用密码登录

默认用户是 arduino，首次启动时要求设置密码，然后就可以通过远程ssh访问。

ssh arduino@my-uno-q.local

5.2 为什么要用密钥登录？

密码登录有几个问题：

1. 安全性：密码可能在网络传输中被嗅探（虽然 SSH 本身是加密的，但弱密码可以被暴力破解）

2. 便利性：每次登录都要输入密码，很烦

3. 自动化：如果你要配置 CI/CD 或脚本自动登录，密码交互很不方便

SSH 密钥对（公钥+私钥）基于非对称加密，安全性远高于密码。

5.3 生成密钥对

在你的电脑（不是 Uno Q）上执行：

ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"
# 一路回车，使用默认路径 ~/.ssh/id_rsa

这会生成两个文件：

• ~/.ssh/id_rsa：私钥，绝对不能泄露

• ~/.ssh/id_rsa.pub：公钥，可以公开

5.4 把公钥传到 Uno Q

# 方法1：用 ssh-copy-id（推荐）
ssh-copy-id arduino@my-uno-q.local
# 方法2：手动复制
cat ~/.ssh/id_rsa.pub | ssh arduino@my-uno-q.local "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

authorized_keys 的权限很重要：

# 在 Uno Q 上检查权限
ls -la ~/.ssh/
# 应该是：
# -rw------- 1 arduino arduino authorized_keys   (600)
# drwx------ 2 arduino arduino .ssh             (700)

如果权限不对，SSH 会拒绝密钥登录（这是安全设计）。

现在，就可以在其他电脑上，直接使用 ssh arduino@my-uno-q.local，无密码登录了：

【图片 7】SSH 密钥登录成功：

5.5 禁用密码登录（可选但推荐）

# 在 Uno Q 上编辑 sshd 配置
sudo nano /etc/ssh/sshd_config
# 找到并修改以下两项：
PubkeyAuthentication yes
PasswordAuthentication no   # 禁用密码登录
# 重启 SSH 服务
sudo systemctl restart ssh
# 或旧版本：
sudo /etc/init.d/ssh restart

注意：在禁用密码登录之前，务必确认密钥登录已经能正常工作！否则你可能把自己锁在门外。

六、sudo 免密：简化日常操作

6.1 为什么要免密？

在 Debian 上，普通用户执行 sudo 时需要输入密码。这在远程 SSH 操作中非常打断节奏：

sudo apt update          # 输入密码
# 过一段时间后
sudo apt install xxx     # 再次输入密码
# 过一段时间后
sudo systemctl restart xxx  # 又输入密码

对于个人开发板来说，这种安全保护有点过度了（毕竟物理上已经在你手里）。

6.2 配置方法

# 使用 visudo 编辑 sudoers（带语法检查，防止改错锁死）

sudo visudo -f /etc/sudoers.d/arduino

添加一行：

arduino ALL=(ALL) NOPASSWD: ALL

解释一下这行的含义：

• arduino：用户名

• ALL=(ALL)：在所有主机上，以所有用户的身份

• NOPASSWD:：不需要密码

• ALL：执行所有命令

保存退出后，需要重新登录（或者开一个新的 SSH 会话）才能生效。

6.3 为什么不直接改 /etc/sudoers？

我们把配置放在 /etc/sudoers.d/arduino 而不是直接改 /etc/sudoers，原因有二：

1. 模块化：每个用户/用途一个文件，清晰不混乱

2. 安全：如果改错了，只需要删除这个文件即可，不影响系统默认配置

visudo 的重要性：如果你用普通编辑器改 sudoers，一旦语法错误，整个 sudo 系统会失效，你可能需要用物理键盘登录 root 修复。visudo 会在保存前检查语法，有错误会拒绝保存。

七、设置时区：别让你的日志时间错乱

7.1 为什么需要设置？

Debian 默认使用 UTC 时区。如果你在中国，日志时间会显示为 "UTC+8" 之前的 8 小时，看起来非常别扭：

date
# 默认输出：Fri May 25 15:22:00 UTC 2026
# 实际北京时间：Fri May 25 23:22:00 CST 2026

7.2 设置方法

sudo dpkg-reconfigure tzdata

选择：

• Geographic area：Asia

• Time zone：Shanghai

7.3 验证

date
# 输出应为：Fri May 25 23:30:00 CST 2026
timedatectl status
# 显示 Time zone: Asia/Shanghai (CST, +0800)

【图片 8】时区设置验证：

7.4 NTP 自动校时

现代 Debian 默认使用 systemd-timesyncd 自动同步网络时间，不需要额外配置。只要联网，时间会自动校准。如果需要检查：

systemctl status systemd-timesyncd
timedatectl status | grep "NTP enabled"

八、验证：一切是否正常？

完成以上步骤后，建议做一个完整的连通性验证：

# 1. 在电脑上测试 mDNS 发现
ping my-uno-q.local -c 4
# 2. SSH 密钥登录（不需要输入密码）
ssh arduino@my-uno-q.local
# 3. 在设备上检查时区
date
timedatectl status
# 4. 测试 sudo 免密
sudo whoami
# 应直接输出：root
# 5. 检查 avahi 是否在运行
systemctl status avahi-daemon

如果以上全部通过，恭喜！你的 Arduino Uno Q 已经完成了基础初始化，下一篇将介绍系统优化和中文本地化。