当前位置： 首页 > news >正文

树莓派上使用arduino-cli开发ESP32-C3：从环境配置到项目实战

news 2026/7/28 8:53:05

1. 项目概述与核心价值

最近在折腾一个物联网项目，手头正好有块合宙的ESP32-C3开发板，想用它来采集一些传感器数据。我的主力开发机是一台树莓派4B，平时就放在工作台上当个小服务器用。一开始，我习惯性地打开了Arduino IDE，但很快就觉得有点别扭——在树莓派这种命令行环境下，用图形界面总觉得不够“原生”，而且远程操作也不方便。于是，我把目光投向了arduino-cli，这个Arduino官方的命令行工具。它轻量、高效，完全可以通过SSH在树莓派上完成ESP32-C3的所有开发工作，从安装板卡支持包、管理库，到编译、上传代码，一气呵成。这不仅仅是换了个工具，更是将嵌入式开发流程无缝集成到Linux服务器环境中的一次实践，对于构建自动化测试、持续集成流水线或者单纯的极客式开发，都极具价值。

简单来说，这篇内容就是记录我如何在树莓派系统（以Raspberry Pi OS为例）上，从零开始配置arduino-cli，并成功用它来为ESP32-C3编写和上传程序的全过程。无论你是想摆脱图形界面的束缚，还是希望将开发环境部署在更稳定的服务器上，甚至是为未来的自动化部署做准备，这套方案都值得一试。整个过程涉及环境配置、板卡添加、库管理、编译上传和问题调试，我会把每一步的原理、操作和踩过的坑都详细拆解出来。

2. 环境准备与arduino-cli安装

在树莓派上玩转命令行开发，第一步就是准备好战场。树莓派的操作系统选择很多，但为了最广泛的兼容性和社区支持，我强烈推荐使用官方的Raspberry Pi OS（原Raspbian），并且是64位版本。32位系统虽然也能用，但在处理一些较新的工具链或大型库时可能会遇到兼容性问题。我使用的是基于Debian Bookworm的Raspberry Pi OS Lite版本，没有图形界面，资源占用更少，通过SSH操作非常流畅。

2.1 系统更新与依赖安装

在安装任何新软件之前，更新系统是标准操作。这能确保你的包管理器拥有最新的软件源信息，并且所有基础组件都是最新的，避免一些因版本过旧导致的诡异问题。

sudo apt update sudo apt upgrade -y

更新完成后，我们需要安装一些必要的依赖包。arduino-cli本身是一个Go语言编写的二进制文件，但它需要一些系统库来支持其功能，比如处理串口、压缩包等。

sudo apt install -y curl git

curl用于从网络下载文件，git在后面管理自定义的板卡配置或者库时可能会用到。这两个工具在开发环境中非常常用，先装上准没错。

2.2 安装与配置arduino-cli

Arduino官方提供了非常方便的脚本来安装arduino-cli。这个脚本会自动检测系统架构，下载对应的最新版本二进制文件，并安装到合适的位置。

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

执行上述命令后，安装脚本通常会将arduino-cli可执行文件放在当前用户的bin目录下（例如~/bin）。为了能在任何位置直接运行它，你需要确保这个目录在你的系统PATH环境变量中。通常，~/bin目录如果存在，在登录时会被自动添加到PATH。你可以通过以下命令检查并添加：

echo $PATH | grep ~/bin # 如果未显示，可以将下面这行添加到 ~/.bashrc 或 ~/.zshrc 文件末尾 export PATH="$HOME/bin:$PATH" # 然后使配置生效 source ~/.bashrc

现在，你可以验证安装是否成功了：

arduino-cli version

如果正确显示了版本号（比如0.35.0），那么恭喜，命令行工具已经就位。

接下来是初始化配置。arduino-cli需要一个配置文件来存储诸如板卡管理器URL、库目录等设置。运行以下命令生成默认配置：

arduino-cli config init

这个命令会在~/.arduino15/目录下生成一个arduino-cli.yaml配置文件。你可以用文本编辑器查看和修改它，但大多数情况下，我们通过命令行来修改配置更安全便捷。

注意：树莓派的用户目录空间可能有限。如果你打算安装很多板卡支持包或库，可以考虑将数据目录更改到外置存储或空间更大的位置。通过arduino-cli config set directories.data /path/to/your/data来设置。

2.3 配置板卡管理器与串口权限

Arduino生态的核心是板卡支持包。我们需要告诉arduino-cli去哪里找这些包。默认的官方索引地址已经够用，但为了后续添加ESP32，我们还需要添加Espressif的官方板卡索引。

首先，添加额外的板卡管理器URL：

arduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

你可以通过arduino-cli config dump命令查看当前所有配置，确认additional_urls已正确添加。

然后，更新核心索引。这个操作会从配置的URL下载板卡包的索引信息，类似于apt update。

arduino-cli core update-index

最后，解决一个在Linux系统上常见的实操问题：串口权限。在树莓派上，普通用户默认无法直接访问USB串口设备（比如连接ESP32-C3后出现的/dev/ttyUSB0）。每次上传都需要sudo显然太麻烦。

最一劳永逸的方法是将你的用户加入到dialout组，这个组通常拥有串口设备的读写权限。

sudo usermod -a -G dialout $USER

重要：执行此命令后，你需要完全注销并重新登录，或者重启树莓派，这个组权限变更才会生效。仅仅新开一个终端窗口是不够的。完成后，重新插拔一下ESP32-C3开发板，你应该就能以普通用户身份访问/dev/ttyUSB0了（可以使用ls -l /dev/ttyUSB0命令查看权限）。

3. 添加ESP32-C3板卡支持与核心安装

环境配置妥当后，接下来就是为我们的主角——ESP32-C3——安装“驱动程序”，在Arduino语境下，这被称为安装“核心”。

3.1 搜索与安装ESP32核心

首先，我们可以搜索一下有哪些可用的ESP32相关核心包：

arduino-cli core search esp32

你会看到一个列表，其中应该包含来自espressif的esp32核心。这就是我们需要的。使用以下命令进行安装：

arduino-cli core install esp32:esp32

这个命令会从我们之前添加的Espressif索引地址下载并安装ESP32 Arduino核心。安装过程可能会持续几分钟，因为它需要下载编译器工具链、库文件等，总体积大约在几百MB。请确保树莓派的网络连接稳定，并且有足够的磁盘空间（至少1GB空闲空间会比较稳妥）。

安装完成后，可以列出所有已安装的核心来确认：

arduino-cli core list

你应该能看到类似esp32:esp32的行，后面跟着安装的版本号。

3.2 理解板卡标识符（FQBN）

在命令行中，我们不是通过图形界面选择“Arduino Uno”或“ESP32-C3 Dev Module”，而是通过一个叫做Fully Qualified Board Name (FQBN)的字符串来唯一指定一块开发板。

FQBN的格式通常是：包作者:架构:板卡型号[:其他参数]。

对于ESP32-C3，最常用的FQBN是esp32:esp32:esp32-c3。这个标识符告诉编译器：使用espressif的esp32核心包，针对esp32架构，编译适用于esp32-c3这块具体板卡的代码。

你可以通过以下命令查看已安装核心支持的所有板卡列表，并从中找到ESP32-C3对应的准确FQBN：

arduino-cli board listall

在输出中仔细查找，你会看到类似esp32:esp32:esp32-c3 (ESP32C3 Dev Module)的条目。括号前的部分esp32:esp32:esp32-c3就是我们要用的FQBN。

实操心得：不同厂商的ESP32-C3开发板，其引脚定义、内置LED的GPIO号、烧录模式按键的接法可能略有不同。例如，合宙ESP32-C3开发板的板载LED通常连接在GPIO8上，而有些其他板子可能接在GPIO2。虽然FQBN都是esp32:esp32:esp32-c3，但具体的引脚定义是由核心包中的boards.txt文件定义的。如果你发现示例代码不工作，第一件事就是去确认你所用的具体开发板的原理图或说明文档。

3.3 安装常用库

和图形界面一样，我们可以用命令行来搜索和安装库。例如，如果你想安装一个用于Wi-Fi管理的库，可以这样搜索：

arduino-cli lib search “WiFi”

找到想要的库后，使用其名称进行安装。例如，安装一个非常流行的JSON解析库ArduinoJson：

arduino-cli lib install “ArduinoJson”

所有安装的库都会存放在配置文件中指定的目录下（默认在~/Arduino/libraries）。你可以通过arduino-cli lib list查看已安装的库。

4. 第一个项目：从编译到上传

理论准备就绪，现在来点实际的。我们将创建一个最简单的Blink项目，让ESP32-C3的板载LED闪烁，并完成完整的编译、上传流程。

4.1 创建项目目录与源代码

首先，为你的项目创建一个独立的目录，这有助于管理。进入该目录并创建主程序文件。

mkdir ~/esp32c3_blink cd ~/esp32c3_blink nano blink.ino

在nano编辑器中，输入以下经典的Blink代码。注意，根据你的具体板子修改LED_BUILTIN的引脚号，对于合宙ESP32-C3，通常是8。

// blink.ino const int ledPin = 8; // 合宙ESP32-C3板载LED引脚，其他板子可能是2 void setup() { pinMode(ledPin, OUTPUT); } void loop() { digitalWrite(ledPin, HIGH); // 点亮LED delay(1000); // 等待1秒 digitalWrite(ledPin, LOW); // 熄灭LED delay(1000); // 等待1秒 }

输入完成后，按Ctrl+O保存，再按Ctrl+X退出nano。

4.2 编译代码（Verify）

编译，在Arduino CLI中称为“verify”。这个步骤会检查代码语法，并将其编译成可供ESP32-C3执行的二进制文件。

arduino-cli compile --fqbn esp32:esp32:esp32-c3 blink.ino

命令解释：

  • compile：执行编译操作。
  • --fqbn esp32:esp32:esp32-c3：指定目标板卡。
  • blink.ino：要编译的草图文件。

如果一切顺利，你会在终端看到大量的编译输出，最后以“项目使用了 xxx 字节，剩余 xxx 字节”的提示结束，并且没有错误信息。编译生成的二进制文件（如blink.ino.bin）和中间文件会保存在当前目录下的build子目录中。

第一次编译可能会比较慢，因为需要缓存编译工具链和核心库。后续编译会快很多。

4.3 上传代码到设备

编译成功后，就可以将程序上传到开发板了。首先，你需要知道开发板连接到了哪个串口。

  1. 连接开发板：使用USB数据线将ESP32-C3连接到树莓派的USB口。

  2. 查找串口：连接后，运行以下命令查看新增的串口设备：

    ls /dev/ttyUSB*

    通常，它会显示为/dev/ttyUSB0。如果你的树莓派连接了多个串口设备，可能会有ttyUSB1等。

  3. 进入下载模式：ESP32系列芯片需要通过串口下载程序，且需要在上电时保持特定的GPIO引脚电平才能进入下载模式。对于大多数ESP32-C3开发板（包括合宙的），通常有两种方式：

    • 自动下载：开发板的USB转串口芯片（如CH340、CP2102）的DTR/RTS引脚已经连接到了ESP32-C3的GPIO9和GPIO8，用于控制其进入下载模式。这是最方便的方式，arduino-cli的上传命令会自动利用这个功能。
    • 手动下载：如果自动下载失败，你需要手动操作：按住开发板上的“BOOT”（或“DOWNLOAD”）按钮不放，然后按一下“RST”（复位）按钮，接着释放“BOOT”按钮。此时芯片进入下载模式。

  4. 执行上传命令：使用以下命令进行上传。假设你的串口是/dev/ttyUSB0。

    arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32-c3 blink.ino

    命令解释：

    • upload：执行上传操作。
    • -p /dev/ttyUSB0：指定上传使用的串口端口。
    • --fqbn esp32:esp32:esp32-c3：同样需要指定板卡类型。

如果上传成功，你会看到类似“Hard resetting via RTS pin...”的提示，然后开发板会自动复位并运行新程序。此时，你应该能看到板载LED开始以1秒的间隔闪烁。

注意事项：上传过程中，终端可能会打印很多调试信息。如果上传失败，最常见的错误是“串口权限拒绝”或“芯片同步失败”。前者请回顾3.3节检查用户组权限；后者通常是因为没有正确进入下载模式，或者串口号错误，或者数据线有问题（有些USB线只能充电不能传输数据）。

5. 项目进阶：管理多文件与使用外部库

一个真实的项目不可能只有一个.ino文件。我们可能需要头文件（.h）、额外的C++源文件（.cpp）、以及依赖第三方库。

5.1 多文件项目结构

假设我们的项目结构如下：

my_project/ ├── my_project.ino ├── Sensor.h ├── Sensor.cpp └── config.h

arduino-cli能够自动处理这种结构。你只需要在项目根目录（即my_project.ino所在的目录）执行编译命令即可，它会自动查找同目录下的其他相关文件并一起编译。

arduino-cli compile --fqbn esp32:esp32:esp32-c3 .

注意，这里的编译目标从单个文件变成了当前目录.。

5.2 使用已安装的库

如果你在代码中使用了已通过arduino-cli lib install安装的库，例如#include <ArduinoJson.h>，编译时arduino-cli会自动在库目录中查找并链接这个库，无需额外参数。

5.3 使用自定义（本地）库

有时我们需要使用自己编写或从GitHub直接克隆的、尚未发布到Arduino库管理器的库。对于这种自定义库，有几种处理方法：

  1. 放在项目目录内：最简单的方法是将整个库文件夹复制到你的项目目录下。这样编译时会被自动包含。但这不是标准的做法，不利于库的复用。

  2. 放在Arduino全局库目录：将库文件夹放在~/Arduino/libraries/目录下。这是Arduino IDE的标准做法，arduino-cli也会从这个目录查找库。重启arduino-cli或重新打开终端后，就可以像使用已安装的库一样使用它了。

  3. 使用--library参数：在编译时，通过--library参数显式指定自定义库的路径。这适用于临时测试或库位于非标准位置的情况。

    arduino-cli compile --fqbn esp32:esp32:esp32-c3 --library /path/to/your/custom/library .

5.4 编译输出与产物分析

arduino-cli的编译输出信息非常详细。除了基本的成功/失败提示，有两类信息特别有用：

  • 存储空间使用情况：编译最后会输出类似这样的信息：

    Sketch uses 234567 bytes (17%) of program storage space. Maximum is 1310720 bytes. Global variables use 15872 bytes (4%) of dynamic memory, leaving 314688 bytes for local variables. Maximum is 327680 bytes.

    这清晰地告诉你程序占用了多少Flash（程序存储空间）和RAM（动态内存）。对于资源有限的嵌入式开发，时刻关注这两个数值至关重要，尤其是当项目变大、使用了大量全局变量或字符串时。

  • 详细的警告和错误：arduino-cli会输出编译器（gcc）的所有警告和错误。不要忽视警告（warning），它们常常预示着潜在的逻辑错误或可优化的代码。养成保持零警告编译的习惯，能极大提升代码质量。

6. 高级配置与问题排查实录

掌握了基础操作后，我们来看看如何应对更复杂的情况和那些令人头疼的常见问题。

6.1 配置文件的深度定制

~/.arduino15/arduino-cli.yaml文件是控制arduino-cli所有行为的核心。除了用config set命令，直接编辑它也能实现更精细的控制。几个有用的配置项：

  • 代理设置：如果你的网络环境需要通过代理访问外部资源，可以在这里配置。
    network: proxy: http://your-proxy:port
  • 自定义库和硬件路径：你可以指定额外的目录来搜索自定义的板卡定义和库，这对于使用非官方或自己修改的硬件支持包非常有用。
    directories: user: /home/pi/MyArduinoStuff # 用户项目目录 data: /home/pi/.arduino15 # 数据目录（核心、工具链） downloads: /tmp/arduino-downloads # 下载缓存目录 board_manager: additional_urls: - https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json - https://another-custom-board-index.json
    修改配置文件后，需要重启终端或重新运行arduino-cli命令才能生效。

6.2 串口监控

上传程序后，我们经常需要查看设备通过串口打印的日志信息（比如Serial.print的输出）。arduino-cli本身不包含串口监视器功能，但我们可以使用树莓派上强大的命令行工具来实现。

最常用的工具是screen和minicom。以screen为例：

sudo apt install screen -y # 如果未安装 screen /dev/ttyUSB0 115200

这条命令会打开一个串口终端，波特率设置为115200（这是Arduino ESP32核心的默认串口波特率）。要退出screen，按Ctrl+A，然后按K，最后按Y确认。

你也可以使用minicom，功能更强大，但配置稍复杂。对于简单的日志查看，screen已经足够快捷。

6.3 常见问题与解决方案速查表

以下是我在实战中遇到的一些典型问题及解决方法：

问题现象可能原因解决方案
arduino-cli: command not found1. 安装脚本未将可执行文件放入PATH中的目录。
2. PATH环境变量未正确加载。		1. 检查~/bin目录是否存在arduino-cli文件。
2. 确认~/bin在PATH中 (echo $PATH)。
3. 可以手动将下载的二进制文件移动到/usr/local/bin/：sudo mv ~/bin/arduino-cli /usr/local/bin/
编译失败，提示fatal error: xxx.h: No such file or directory1. 依赖的库未安装。
2. 头文件路径错误（自定义库）。		1. 使用arduino-cli lib search和install安装缺失库。
2. 检查自定义库的存放位置，或使用--library参数指定路径。
上传失败，提示Permission denied用户没有串口设备的读写权限。将用户加入dialout组 (sudo usermod -a -G dialout $USER)，并重新登录。
上传失败，提示Failed to connect to ESP32: Timed out waiting for packet header或Chip sync error1. 开发板未进入下载模式。
2. 串口号错误。
3. USB数据线或接口问题。
4. 驱动问题（在树莓派上较少见）。		1.手动进入下载模式：按住BOOT键，按一下RST键，松开BOOT键，再尝试上传。
2. 确认串口号 (ls /dev/ttyUSB*)。
3. 换一条数据线，并尝试更换树莓派的USB接口。
4. 确保板卡型号(FQBN)选择正确。
编译时内存占用报告异常高，或程序运行不稳定1. 程序中定义了非常大的全局数组或字符串。
2. 堆栈溢出。
3. 使用了动态内存分配但未妥善管理。		1. 使用PROGMEM将常量数据存放到Flash。
2. 减少全局变量，使用局部变量。
3. 优化数据结构，使用更节省内存的类型。
4. 使用ESP.getHeapSize()等函数监控内存使用。
arduino-cli core install下载极慢或失败网络连接问题，特别是访问GitHub或Espressif的服务器。1. 检查树莓派网络连接。
2. 考虑为命令行工具配置网络代理（修改配置文件）。
3. 可以尝试手动下载板卡包，但过程复杂，不推荐新手操作。

6.4 性能优化与清理

随着开发进行，~/.arduino15目录下会缓存大量的工具链、平台文件，占用不少磁盘空间。你可以定期清理不再需要的旧版本核心或工具链。

  • 查看已安装核心及其版本：arduino-cli core list
  • 卸载特定版本的核心：arduino-cli core uninstall packager:arch@version(例如esp32:esp32@2.0.11)
  • 清理所有未使用的平台和工具链：这是一个比较激进但有效的清理方式，arduino-cli目前没有内置一键命令，但你可以手动删除~/.arduino15/staging和~/.arduino15/packages中你认为不必要的子目录。操作前建议备份。

对于树莓派这种存储空间有限的设备，定期清理可以保持系统清爽。我个人习惯在完成一个重大版本升级并确认稳定后，清理掉旧版本的安装包。

http://www.jsqmd.com/news/1279544/

相关文章：

  • 2026 西安 PVC 塑胶地板、橡胶地板行业盘点：工装采购痛点与一站式解决方案 - 国麟测评
  • JizhiCMS 1.6.7前台SQL注入漏洞深度剖析与实战利用
  • flutter_tts多平台适配攻略：Android、iOS、Web与桌面端实现详解
  • ZigbeeTLc按钮功能详解：4种操作模式让设备控制更简单
  • 大麦网自动化抢票架构解析：从API逆向到请求模拟的技术实现方案
  • 架构师必备：分布式锁方案选型
  • 3大Flipper Zero固件编译方案对比：从入门到精通的全流程指南
  • 二分查找算法原理、实现与优化全解析
  • AI代码审查安全吗？从Claude Code看人机协同安全防线构建
  • 并查集原理、优化与应用实战指南
  • 微服务多环境架构设计实战：5套环境2个参数搞定部署（从混乱到体系化）
  • 校招投递多少家公司合适？别用海投数量掩盖低匹配度
  • LDAP与NoSQL注入攻击：超越SQL的Web安全新威胁
  • 释放游戏潜能：Wand-Enhancer 的本地化增强方案
  • 基于行空板与GStreamer的低延迟图传系统实现与优化
  • 2026本溪持证防水补漏商家权威TOP3榜单 卫生间厨房外墙屋面天花板漏水检测靠谱师傅维修指南 - 宅安选房屋修缮
  • NVIDIA Profile Inspector终极指南：3步快速优化显卡性能，提升游戏体验50%
  • Caddy WAF测试方法论：从单元测试到ELK日志分析的完整流程
  • 千笔与万方智搜AI：学术写作工具深度对比与应用技巧
  • AI入门五大核心技能：Python数据处理与机器学习实战
  • 苹果触控板Windows驱动终极指南：5分钟实现原生级触控体验
  • 零成本搭建私有知识库：Dify整合DeepSeek实现本地RAG方案
  • IMU与GPS数据融合的卡尔曼滤波实现与优化
  • 解决tldr-python-client常见问题：网络错误、缓存失效与平台兼容
  • 大统一逻辑链7.0（GULP7.0）：演化的涌现（草稿）
  • 2026巴中持证防水补漏商家权威TOP3榜单 卫生间厨房外墙屋面天花板漏水检测靠谱师傅维修指南 - 宅安选房屋修缮
  • 智慧树学习效率革命：三招告别手动刷课的智能解决方案
  • 【Bug已解决】[Bug]: Image URL errors return HTTP 500 instead of 422 for unprocessable content 解决方案
  • ZigbeeTLc高级配置指南：温度湿度偏移、显示设置与测量间隔调整
  • Jellium Desktop网络连接增强工具：提升连接稳定性的终极指南