我买了两台 AirGradient ONE 室内空气质量监测仪，用来监测家中的空气质量。AirGradient 的设备是开源的，所以你可以自行刷入自定义固件，在本地收集空气数据，而不必将数据发送到 AirGradient 专有的云端面板。

现有的刷写固件文档都要求你使用 Arduino IDE，这个笨重的图形界面程序：

我一直没找到通过命令行刷写 AirGradient 设备的教程，花了好几个小时才摸索出来，因此在下面整理了具体步骤。

题外话：我不太理解 AirGradient 为何这么受追捧

每次在论坛讨论中看到 AirGradient，大家似乎都对它的产品赞不绝口。我手上的 AirGradient ONE 体验却只能算一般。软件 bug 非常多，文档也十分零散。但它是目前我能找到的唯一一家提供开源成品空气质量监测仪的厂商，所以我还是又买了一台。

多年来，AirGradient 甚至懒得发布如何给 AirGradient ONE 刷写软件的说明。我是从下面这两篇博文里才学会的：

• “Monitoring my home’s air quality (CO2, PM2.5, Temp/Humidity) with AirGradient’s DIY sensor” 作者：Jeff Geerling
• “AirGradient ONE Kit Review – An open-source indoor air quality monitor” 作者：CNX Software

直到今年，AirGradient 终于发布了官方刷写说明，不过还是藏得比较深。

测试环境

以下步骤在 Debian 13.0 上测试通过，不过在任何类似 Debian/Ubuntu 的系统上应该都能通用。

安装依赖包

首先，安装所需的基础软件包：

sudo apt update && \
  sudo apt install -y \
    git \
    curl \
    python3 \
    python3-serial

安装 arduino-cli

接下来，安装 Arduino CLI 工具：

ARDUINO_CLI_VERSION='1.2.2'
ARDUINO_BIN_DIR="${HOME}/.local/arduino-cli"

mkdir -p "${ARDUINO_BIN_DIR}" && \
  curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh \
  | BINDIR="${ARDUINO_BIN_DIR}" sh -s "${ARDUINO_CLI_VERSION}"
export PATH="${PATH}:${ARDUINO_BIN_DIR}"

要验证安装是否成功，可以打印 arduino-cli 的版本信息：

$ arduino-cli version
arduino-cli  Version: 1.2.2 Commit: c11b9dd5 Date: 2025-04-22T13:51:01Z

下载 ESP32 依赖库

AirGradient ONE 依赖于 ESP32 的 Arduino 库。截至本文撰写时，AirGradient 尚不兼容 Arduino 3.x 版本，因此必须使用最新的 2.x 稳定版。

ARDUINO_ESP32_VERSION='2.0.17'

arduino-cli config init \
  --additional-urls https://espressif.github.io/arduino-esp32/package_esp32_index.json && \
  arduino-cli core install "esp32:esp32@${ARDUINO_ESP32_VERSION}"

查找设备路径

接下来，需要找到 AirGradient ONE 的设备路径。最简单的查找方法是：

1. 运行 dmesg --follow
2. 通过 USB 将 AirGradient ONE 连接到电脑
3. 在 dmesg 的输出中查找出现的设备路径

在我的系统上，显示效果如下：

$ sudo dmesg --follow
[517021.978880] usb 1-4: New USB device found, idVendor=303a, idProduct=1001, bcdDevice= 1.01
[517021.978884] usb 1-4: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[517021.978894] usb 1-4: Product: USB JTAG/serial debug unit
[517021.978896] usb 1-4: Manufacturer: Espressif
[517021.978898] usb 1-4: SerialNumber: D8:3B:DA:1A:EE:C4
[517022.017678] cdc_acm 1-4:1.0: ttyACM0: USB ACM device
                                 ^^^^^^^
                                 Path name

根据这段输出，我的系统上 AirGradient ONE 的路径是 /dev/ttyACM0：

AIRGRADIENT_PATH='/dev/ttyACM0'

让设备路径可写

接下来，确保我对 AirGradient 的设备文件有写入权限：

sudo chmod a+rw "${AIRGRADIENT_PATH}"

此时 AirGradient 路径的权限应该如下所示：

$ ls -l "${AIRGRADIENT_PATH}"
crw-rw-rw- 1 root dialout 166, 0 Aug 10 10:34 /dev/ttyACM0
 ^^^^^^^^

我还会把自己加入 dialout 用户组，以便拥有对该路径的写入权限：

sudo adduser "$(whoami)" dialout

获取 AirGradient 源码

接下来，我会查看 AirGradient 官方刷写页面，确认最新的正式发布版本。

# Current production release, as of this writing.
AIRGRADIENT_RELEASE='3.3.8'

拿到版本号后，就可以从 AirGradient 的 GitHub 仓库拉取源码了：

git clone --recurse-submodules \
  --branch "${AIRGRADIENT_RELEASE}" \
  --depth 1 \
  https://github.com/airgradienthq/arduino.git \
  ~/airgradient-one

向 AirGradient ONE 设备刷入固件

最后，就可以向设备刷入固件了：

cd ~/airgradient-one && \
  arduino-cli compile \
    --verbose \
    --fqbn esp32:esp32:esp32c3:CDCOnBoot=cdc,PartitionScheme=min_spiffs,DebugLevel=info \
    --library . \
    --port "${AIRGRADIENT_PATH}" \
    --verify \
    --upload \
    examples/OneOpenAir/OneOpenAir.ino

如果刷写成功，设备会重启，并在过程结束时看到如下输出：

Wrote 1753792 bytes (967231 compressed) at 0x00010000 in 14.7 seconds (effective 952.3 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...

可选：查看串口日志输出

在 AirGradient 连接到电脑期间，可以通过 arduino-cli monitor 命令经由串口查看其日志输出：

$ arduino-cli monitor --port "${AIRGRADIENT_PATH}"
Using default monitor configuration for board: esp32:esp32:heltec_wifi_kit_32_V3
Monitor port settings:
  baudrate=9600
  bits=8
  dtr=on
  parity=none
  rts=on
  stop_bits=1

Connecting to /dev/ttyACM0. Press CTRL-C to exit.
[1] Standard Particle PM 2.5 = 7.00 ug/m3
[1] Particle Count 0.3 = 1298.5
[1] Particle Count 0.5 = 383.5
[1] Particle Count 1.0 = 39.7
[1] Particle Count 2.5 = 2.0
[1] Particle Count 5.0 = 2.0
[1] Particle Count 10 = 0.0

替代方案：使用 Nix flake

如果你是 Nix 爱好者，也可以用 Nix 的方式来完成上述所有步骤。我创建了一个 Nix flake 来自动化整个流程：

• 我的 AirGradient ONE 开发用 Nix flake

需要刷写时，只需运行：

nix run .#flash

需要查看串口输出时，则运行：

nix run .#monitor

我不确定这个 Nix flake 在不同系统上的兼容性如何，所以你可能还需要针对自己的系统做一些调整。

总结

希望这些步骤能让你更轻松地刷写 AirGradient ONE 设备，并按自己的需求定制固件。