EEPW论坛

本文目标：在 Uno Q 上搭建完整的开发工具链，覆盖 Arduino 官方生态和 Python 嵌入式开发，让你真正开始写代码。

适用同学：准备动手开发项目，需要图形化 IDE 或 Python 环境的用户。

一、Arduino App Lab：Uno Q 专属的"双脑"开发环境

1.1 什么是 Arduino App Lab？

Arduino App Lab 是 Arduino 官方为新世代"双脑"开发板设计的统一开发环境。传统 Arduino 开发板只有一个微控制器（MCU），而 Uno Q 同时搭载了运行 Debian Linux 的 Qualcomm MPU 和运行 Zephyr RTOS 的 STM32 MCU。App Lab 的独特之处在于：

可视化编程：通过拖拽"积木"（Bricks）组合项目，不需要写底层代码
双端协同：同时操作 Linux 端（MPU）和嵌入式端（MCU），两者通过内部总线通信
预装即用：Uno Q 出厂已预装，上电自动启动
也可以装在 PC 上：通过 USB 或网络连接板子进行开发
【图片 20】Arduino App Lab 配置界面：
1.2 首次启动：完成基础配置
如果你是第一次使用 Uno Q，App Lab 会引导你完成以下设置：
系统固件更新（可选）：首次启动时可能提示更新板子系统固件，建议更新到最新版本
设置 WiFi：选择你的无线网络并输入密码
设置用户名/密码：创建用于 SSH 登录的账户（默认用户 arduino）
设置设备名称（Hostname）：比如 my-uno-q，之后可以通过 my-uno-q.local 访问
完成配置后，App Lab 会自动连接板子，进入主界面。
【图片 21】Arduino App Lab 网络配置完成后的主界面：
1.3 App Lab 的核心概念
App Lab 引入了几个新的开发概念：
概念    说明    
App    一个完整的应用程序，可以同时包含 MPU 端代码和 MCU 端代码    
Brick    预封装的功能模块，比如"读取传感器""控制 GPIO""连接 WiFi"等，像搭积木一样组合    
Bridge    MPU 和 MCU 之间的通信桥梁，让 Linux 程序能和底层硬件交互    
Cloud Project    可以保存到 Arduino Cloud 的项目，换设备也能同步    
1.4 运行Blink LED
1. 打开 Arduino App Lab
2. 进入 Examples 界面
3. 点击 Blink LED
4. 点击 "Run" 运行——代码会自动部署到 MPU 和 MCU 两端
App Lab 在底层会自动生成 C++ / Python 代码并编译上传到对应的处理器。你看到的可视化界面，背后是完整的工具链在运转。
【图片 22】Arduino App Lab 编程界面：
点击界面右上角的 Copy and edit app，即可将Example保存为自己的程序，按照自己的需要进行修改。
【图片 22b】Arduino App Lab 编程界面：
运行后，可以看到Uno Q开发板上的LED按照程序设定进行闪烁。
【图片 22c】Uno Q 开发板 LED 闪烁状态（Blink LED 运行效果）：
1.5 使用 App Lab CLI（命令行）
App Lab 也提供了命令行工具，方便自动化和脚本化操作：
# 查看已连接的板子
arduino-app-lab board list
# 查看板子信息
arduino-app-lab board info
# 列出所有 App
arduino-app-lab app list
# 运行指定 App
arduino-app-lab app run <app-name>
# 安装 Brick
arduino-app-lab brick install <brick-name>
CLI 工具适合 CI/CD 场景，或者你习惯在终端里工作。
二、Arduino IDE 1.x：经典版本，apt 一键安装
在 Arduino Uno Q默认的系统重，可以通过apt安装Arduino IDE 1.x。
2.1 为什么选择 Arduino IDE 1.x？
Arduino IDE 1.x（当前最后版本 1.8.19）是 Arduino 的经典版本：
稳定成熟：经过了十多年的打磨，兼容性最好
ARM64 原生支持：Debian 仓库直接提供 ARM64 构建版本
适合老项目：很多 legacy 库和项目只在 1.x 上测试过
2.2 安装步骤
# 1. 更新软件源
sudo apt update
# 2. 安装 Arduino IDE 1.x
sudo apt install arduino
# 3. 验证安装
arduino --version
# 应输出类似：Arduino 1.8.19
安装包会自动处理所有依赖（运行环境、avr-gcc 工具链等）。
【图片 23】Arduino IDE 1.x 安装完成后的主界面：
2.3 配置板卡核心
Arduino IDE 1.x 安装后，需要确认板卡核心是否就绪：
1. 打开 Arduino IDE
2. 工具 -> 开发板，查看是否有 "Arduino UNO R4"
3. 如果没有，进入 工具 -> 开发板 -> 开发板管理器
4. 搜索 "Arduino UNO R4" 并安装
2.4 测试：Blink 示例
为了验证 Arduino IDE 1.x 的完整功能，我们用一块外接的 Arduino Uno R4 WiFi 开发板进行测试。
验证 Arduino IDE 1.x 是否能正常编译和上传：
// 文件 -> 示例 -> 01.Basics -> Blink
void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}
void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}
1. 开发板选择：工具 -> 开发板 -> Arduino UNO R4 WiFi
2. 端口选择：工具 -> 端口 -> /dev/ttyACM0
3. 点击上传按钮
测试过程中，发现使用 Arduino IDE 1.x 上传 Arduino UNO R4 WiFi 失败，具体原因暂时未知。使用 Arduino IDE 2.x时，可以正常上传。
【图片 24】Arduino IDE 1.x 编译上传 Blink 示例失败：
三、Arduino IDE 2.x：推荐的主力开发环境
3.1 为什么 IDE 2.x 是推荐选择？
Arduino IDE 2.x 基于 Electron + Monaco Editor（VS Code 同款编辑器），相比 1.x 有显著提升：
代码补全：智能提示变量、函数名
代码导航：Ctrl+点击跳转定义
实时调试：内置串口监视器，带时间戳和过滤功能
现代 UI：支持深色主题、多标签页
但 Arduino 官方目前只发布 x86_64 的 Linux 构建，ARM64 需要使用社区构建版本。
3.2 安装社区构建的 ARM64 版本
# 1. 下载社区构建的 .deb 包（以 v2.3.9 为例）
cd ~/
wget https://github.com/matu6968/arduino-ide-arm64/releases/download/v2.3.9/arduino-ide_2.3.9_arm64.deb
# 2. 安装
sudo apt install ./arduino-ide_2.3.9_arm64.deb
# 3. 验证安装
arduino-ide --version
# 应输出：2.3.9
安装完成后，可以在应用菜单中找到 "Arduino IDE 2.x" 启动。
【图片 25】Arduino IDE 2.x ARM64 版本主界面：
3.3 第一次启动：配置板卡核心和库
1. 打开 Arduino IDE 2.x
2. 左侧边栏点击"开发板管理器"图标
3. 搜索 "Arduino UNO R4"，安装对应的核心包
4. 左侧边栏点击"库管理器"图标
5. 搜索需要的库并安装（如 WiFi、MQTT 等）
3.4 用 Arduino Uno R4 WiFi 进行测试
为了验证 IDE 2.x 的完整功能，我们用一块外接的 Arduino Uno R4 WiFi 开发板进行测试。
接线：
用 USB-A 转 USB-C 线将 Uno R4 WiFi 连接到 Uno Q 的 USB Hub
测试代码：Arduino Uno R4 WiFi Examples中的MatrixIntro
/*
  Heart Animation Sketch
  
  This is the default sketch that comes
  shipped with every UNO R4 WiFi board.
  After the animation (a heart) is complete,
  the built-in LED blinks infinitely.
  No additional circuit required.
  created 26 Jun 2023
  by Martino Facchin
  See the full documentation here:
  https://docs.arduino.cc/tutorials/uno-r4-wifi/led-matrix
*/
// include the LED Matrix library from the Uno R4 core:
#include "Arduino_LED_Matrix.h"
// make an instance of the library:
ArduinoLEDMatrix matrix;
//include the "animation.h" header file that stores the frames for the animation 
#include "animation.h"
void setup() {
  Serial.begin(115200);
  //load frames from the animation.h file
  matrix.loadSequence(frames);
  // start the matrix
  matrix.begin();
  
  // turn on autoscroll to avoid calling next() to show the next frame; the paramenter is in milliseconds
  // matrix.autoscroll(300);
  //play the animation on the matrix
  matrix.play(true);
  //define LED_BUILTIN as an output
  pinMode(LED_BUILTIN, OUTPUT);
}
void loop() {
  //blinks the built-in LED every second
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}
上传步骤：
1. 开发板选择：工具 -> 开发板 -> Arduino UNO R4 WiFi
2. 端口选择：工具 -> 端口 -> /dev/ttyACM0（或 /dev/ttyACM1）
3. 点击左侧"上传"按钮
4. 等待编译和上传完成
【图片 26】Arduino IDE 2.x 连接 Uno R4 WiFi 并上传代码：
查看开发板LED效果：
【图片 27】开发板LED 状态：
3.5 Arduino IDE 1.x 与 2.x 的选择建议
场景    推荐版本    
快速验证、老项目维护    IDE 1.x    
日常开发、新功能使用    IDE 2.x（推荐）    
资源受限（内存 < 2GB）    IDE 1.x    
需要代码补全和调试    IDE 2.x    
四、Thonny：Python 与 CircuitPython 开发利器
4.1 为什么选择 Thonny？
Thonny 是专为初学者设计的 Python IDE，同时也是嵌入式 Python 开发（MicroPython / CircuitPython）的绝佳工具：
开箱即用：Debian 仓库直接安装，无需配置 Python 环境
MicroPython / CircuitPython 原生支持：一键烧录固件、交互式 REPL
变量可视化：运行中实时查看变量值
单步调试：支持断点和逐行执行
轻量级：ARM64 设备上运行流畅
4.2 安装 Thonny
为什么不直接用 apt install thonny？ 因为 Debian 仓库中的 Thonny 版本通常非常老旧，界面简陋、功能缺失。所以我推荐从 GitHub 下载官方发布的最新版本（v5.0.0），使用 bash 脚本安装：
# 1. 下载安装脚本
cd ~/
wget https://github.com/thonny/thonny/releases/download/v5.0.0/thonny-5.0.0.bash
# 2. 运行安装脚本
bash thonny-5.0.0.bash
安装完成后，可以在应用菜单中找到 "Thonny" 启动。
【图片 29】bash 安装的 Thonny v5.0.0 界面：
4.3 测试 1：运行本地 Python 脚本
先在 Uno Q 上写一个 Python 脚本测试基本功能：
# hello_unoq.py
# 测试 Uno Q 的 Python 运行环境
import platform
import os
import datetime
print("=" * 50)
print("Arduino Uno Q Python 测试")
print("=" * 50)
# 系统信息
print(f"操作系统: {platform.system()} {platform.release()}")
print(f"机器架构: {platform.machine()}")
print(f"Python 版本: {platform.python_version()}")
print(f"处理器: {platform.processor()}")
# 当前时间
now = datetime.datetime.now()
print(f"当前时间: {now.strftime('%Y-%m-%d %H:%M:%S')}")
# 简单的数学计算
def fibonacci(n):
    """计算斐波那契数列"""
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    return b
print("\n斐波那契数列前 20 项:")
for i in range(20):
    print(f"F({i}) = {fibonacci(i)}", end="  ")
    if (i + 1) % 5 == 0:
        print()
# 文件系统信息
print(f"\n当前目录: {os.getcwd()}")
print(f"用户主目录: {os.path.expanduser('~')}")
print("\n" + "=" * 50)
print("测试完成！")
运行步骤：
1. 打开 Thonny
2. 文件 -> 新建，粘贴上面的代码
3. 文件 -> 保存为 hello_unoq.py
4. 点击"运行当前脚本"按钮（绿色三角形）
5. 在 Shell 面板查看输出
【图片 30】Thonny 运行本地 Python 脚本的输出：
4.4 测试 2：在 ESP32-C61 上烧录 CircuitPython
CircuitPython 是 Adafruit 开发的 MicroPython 分支，专注于易用性和硬件教育。我们把它烧录到 ESP32-C61 开发板上。
准备工作：
ESP32-C61 开发板一块（本文使用 ESP32-C61-DevKitC-1-N8R2）
USB-C 数据线（支持数据传输）
Uno Q 上已安装 esptool
步骤 1：安装 esptool 并验证 ESP32-C61 连接
esptool 是 Espressif 官方的芯片烧录工具。我们用 pipx 来运行它，避免污染系统 Python 环境：
# 1. 安装 pipx
sudo apt install pipx
# 2. 将 ESP32-C61 通过 USB 线连接到 Uno Q 的 USB Hub
# 3. 检查串口设备
ls /dev/ttyUSB*
# 应看到 /dev/ttyUSB0（如果没有，尝试 /dev/ttyACM*）
# 4. 使用 esptool 读取芯片信息（验证连接和识别芯片型号）
pipx run esptool -p /dev/ttyUSB0 flash-id
正常情况下，esptool 会输出芯片的 Flash 信息，确认这是 ESP32-C61。
【图片 31】esptool 读取 ESP32-C61 的 flash-id 信息：
步骤 2：下载 CircuitPython 固件
# 下载 ESP32-C61-DevKitC-1-N8R2 对应的 CircuitPython 固件
cd ~/
wget https://downloads.circuitpython.org/bin/espressif_esp32c61_devkitc_1_n8r2/en_US/adafruit-circuitpython-espressif_esp32c61_devkitc_1_n8r2-en_US-10.2.1.bin
# 备用：如果上述链接失效，从官网下载页获取最新链接
# https://circuitpython.org/board/espressif_esp32c61_devkitc_1_n8r2/
步骤 3：使用 esptool 烧录固件
# 烧录 CircuitPython 固件到 ESP32-C61
# -z 表示自动检测并压缩数据
# 0x00 表示从 Flash 起始地址开始写入
pipx run esptool -p /dev/ttyUSB0 write_flash -z 0x00 \
  adafruit-circuitpython-espressif_esp32c61_devkitc_1_n8r2-en_US-10.2.1.bin
烧录过程中你会看到进度条。完成后 ESP32-C61 会自动重启，就可以用Thonny连接进行开发调试了。
【图片 32a】esptool 烧录 CircuitPython 固件过程：
【图片 32b】esptool 烧录完成：
步骤 4：在 Thonny 中配置 CircuitPython 解释器
1. 打开 Thonny
2. 点击右下角状态栏的 Python 版本号（如"Python 3.11"）
3. 选择"配置解释器..."
4. 解释器类型选择：CircuitPython
5. 端口选择：/dev/ttyUSB0（与 esptool 使用的端口一致）
6. 点击 OK
Thonny 会自动连接到 ESP32-C61 的 CircuitPython REPL。左下角会显示板子上的文件系统（CIRCUITPY 驱动器）。
【图片 33】Thonny 中选择 CircuitPython 解释器和端口：
步骤 5：编写并运行 ESP32-C61 上的代码
# 保存到 ESP32-C61 的 code.py（CircuitPython 开机自动运行此文件）
import board
import busio
import time
import neopixel_spi
# 手动创建 SPI 总线，MOSI 接 WS2812 的数据引脚 IO8
# clock 指定一个合法的时钟引脚（这里用 IO3），MISO 不用则留空
spi = busio.SPI(clock=board.IO3, MOSI=board.IO8, MISO=None)
# 创建 NeoPixel_SPI 对象，驱动 1 颗灯珠
pixels = neopixel_spi.NeoPixel_SPI(spi, 1)
while True:
    print("LED on")
    pixels[0] = (255, 255, 255)   # 白色
    pixels.show()
    time.sleep(1)
    print("LED off")
    pixels[0] = (0, 0, 0)         # 熄灭
    pixels.show()
    time.sleep(1)
1. 在 Thonny 中新建文件
2. 粘贴上面的代码
3. 文件 -> 保存到 -> CIRCUITPY / code.py
4. 代码会自动开始运行
5. 在 Shell 面板查看输出，观察 LED 闪烁
【图片 34】Thonny 连接 ESP32-C61，Shell 显示 CircuitPython 输出：
步骤 6：下载并安装 CircuitPython 库包
上面的 LED 闪烁示例只用了 CircuitPython 内置库。但如果你要接传感器（如 DHT 温湿度、BMP280 气压计、SSD1306 OLED 等），就需要额外的社区库。Adafruit 提供了一个完整的库包（Bundle），包含数百个常用驱动：
# 1. 下载 Adafruit CircuitPython Bundle（Python 源码版，非 .mpy 版，兼容性好）
cd ~/
wget https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/download/20260526/adafruit-circuitpython-bundle-py-20260526.zip
# 2. 解压
unzip adafruit-circuitpython-bundle-py-20260526.zip
# 3. 查看 Bundle 结构
ls ~/adafruit-circuitpython-bundle-py-20260526/lib/
# 里面有 adafruit_dht.mpy、adafruit_ssd1306.mpy、neopixel.mpy 等
把需要的库上传到 ESP32-C61：
1. 确认 ESP32-C61 已作为 CIRCUITPY 驱动器连接到 Uno Q
2. 在 Thonny 左下角查看板子的文件系统
3. 如果 CIRCUITPY 目录下没有 lib/ 文件夹，右键新建文件夹，命名为 lib
4. 从解压的 Bundle 中复制需要的库文件到 CIRCUITPY/lib/ 目录下
   例如：adafruit_dht.mpy、adafruit_bmp280.mpy 等
5. 复制完成后，代码中就可以 import 使用了
CircuitPython 常用库：
CircuitPython 有丰富的内置库和社区库：
import board        # 引脚定义
import digitalio    # GPIO 数字输入输出
import analogio     # ADC 模拟输入
import busio        # I2C / SPI / UART
import pwmio        # PWM 输出
import time         # 延时
import neopixel     # WS2812 RGB LED
import adafruit_dht # DHT 温湿度传感器

安装额外库：

1. 下载需要的 .mpy 库文件（从 Adafruit 的 GitHub 或 circuitpython.org/libraries）

2. 复制到 ESP32-C61 的 /lib/ 目录下

进阶测试：驱动板载 WS2812 RGB LED

ESP32-C61 开发板上集成了一颗 WS2812 LED，连接到了 board.IO8，CircuitPython 中也把它映射为 board.NEOPIXEL。驱动这颗 LED 需要使用 adafruit/Adafruit_CircuitPython_NeoPixel_SPI: SPI driven CircuitPython driver for neopixels. 中的 neopixel_spi 库，通过 SPI 协议控制。

准备库文件：

复制 neopixel_spi 库到开发板

测试 ：多项功能（白色闪烁 + RGB 循环 + 彩虹渐变）

# 保存到 ESP32-C61 的 code.py（CircuitPython 开机自动运行此文件）
import board
import busio
import neopixel_spi
import time
# ---------- 配置 SPI 总线 ----------
spi = busio.SPI(clock=board.IO3, MOSI=board.IO8, MISO=None)
pixels = neopixel_spi.NeoPixel_SPI(spi, 1, brightness=0.3, auto_write=True)
# ---------- 辅助函数 ----------
def wheel(pos):
    """彩虹颜色生成函数：输入 0~255，返回 (r,g,b)"""
    if pos < 0 or pos > 255:
        return (0, 0, 0)
    if pos < 85:
        return (255 - pos * 3, pos * 3, 0)
    if pos < 170:
        pos -= 85
        return (0, 255 - pos * 3, pos * 3)
    pos -= 170
    return (pos * 3, 0, 255 - pos * 3)
# ---------- 测试模式 ----------
def test_white_blink(repeat=5):
    """模式1：白色闪烁 repeat 次"""
    print("测试模式1：白色闪烁")
    for _ in range(repeat):
        pixels.fill((255, 255, 255))
        time.sleep(0.5)
        pixels.fill((0, 0, 0))
        time.sleep(0.5)
def test_rgb_cycle(repeat=3):
    """模式2：红->绿->蓝 交替"""
    print("测试模式2：红绿蓝交替")
    colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255)]
    for _ in range(repeat):
        for c in colors:
            pixels.fill(c)
            time.sleep(0.5)
    pixels.fill((0, 0, 0))
def test_rainbow_fade(duration=10):
    """模式3：彩虹渐变，持续 duration 秒"""
    print(f"测试模式3：彩虹渐变，持续 {duration} 秒")
    start_time = time.monotonic()
    step = 0
    while time.monotonic() - start_time < duration:
        pixels.fill(wheel(step & 255))
        step += 2
        time.sleep(0.02)
    pixels.fill((0, 0, 0))
# ---------- 主程序 ----------
if __name__ == "__main__":
    print("开始 WS2812B 灯珠测试")
    test_white_blink(repeat=5)
    time.sleep(0.5)
    test_rgb_cycle(repeat=3)
    time.sleep(0.5)
    test_rainbow_fade(duration=10)
    print("所有测试完成，灯珠已熄灭")

1. 确保 neopixel_spi.py 和 adafruit_bus_device 已复制到 CIRCUITPY/lib/

2. 在 Thonny 中新建文件，粘贴上面的测试代码

3. 文件 -> 保存到 -> CIRCUITPY / code.py

4. 观察板载 WS2812 LED 依次执行：白色闪烁 -> RGB 交替 -> 彩虹渐变

【图片 35】ESP32-C61 板载 WS2812 运行彩虹渐变效果：

4.5 Thonny 的高级功能

交互式 REPL：

在 Shell 面板中可以直接输入 Python 命令与板子交互：

>>> import board
>>> dir(board)          # 查看所有可用引脚
>>> import digitalio
>>> led = digitalio.DigitalInOut(board.IO2)
>>> led.direction = digitalio.Direction.OUTPUT
>>> led.value = True    # 点亮 LED
>>> led.value = False   # 熄灭 LED

文件管理：

Thonny 左下角可以浏览板子上的文件系统，直接右键上传/下载文件，无需额外工具。

五、串口权限配置（重要）

无论你使用哪种 IDE，外接 Arduino 或 ESP32 开发板时都会涉及串口访问权限。

5.1 问题现象

上传代码时提示权限不足：

无法打开设备 "/dev/ttyACM0"：权限不够
# 或
Failed to open serial port /dev/ttyUSB0

5.2 解决方法

将当前用户加入 dialout 组：

# 1. 添加用户到 dialout 组
sudo usermod -a -G dialout $USER
# 2. 确认加入成功
groups $USER
# 输出中应包含 dialout
# 3. 重新登录使权限生效
exit
# 重新 SSH 登录或重启系统

六、总结

完成本篇的全部配置后，你的 Arduino Uno Q 已经是一台功能完备的开发工作站，覆盖了从可视化编程到传统 Arduino 开发，再到 Python 嵌入式开发的全场景：

三种开发环境的适用场景总结：

• Arduino App Lab：快速原型、教学、探索 Uno Q 的双脑架构

• Arduino IDE 1.x/2.x：传统 Arduino 开发、外接 Arduino 兼容板

• Thonny：Python 脚本、MicroPython / CircuitPython 嵌入式开发

现在，开始你的 Arduino Uno Q 开发之旅吧！