Flash an AirGradient ONE from the Command Line

2025-08-23

透過命令列刷寫 AirGradient ONE

我買了兩台 AirGradient ONE 室內空氣品質監測器來測量家中的空氣品質。AirGradient 的裝置是開源的，因此你可以自行刷寫客製化韌體，並在本地端收集空氣數據，而不必將資料傳送到 AirGradient 專屬的雲端儀表板。

我在辦公室放了一台 AirGradient ONE 空氣品質監測器，用來測量二氧化碳和污染物。

現有的韌體刷寫文件要求你使用 Arduino IDE，這是一套笨重的 GUI 程式：

現有的 AirGradient ONE 刷寫說明仰賴 Arduino IDE 這套笨重的 GUI 程式。

我找不到透過命令列刷寫 AirGradient 裝置的說明，花了好幾個小時才摸索出來，因此我在下方整理了操作步驟。

題外話：我不太懂大家為何如此追捧 AirGradient

每次在論壇討論中看到有人提到 AirGradient，大家似乎都對他們的產品感到很興奮。我覺得我的 AirGradient ONE 表現平庸。軟體錯誤非常多，文件也相當稀少。但他們是我目前找到唯一一家販售現成且開源的空氣品質監測器的公司，所以我還是又買了第二台 AirGradient 監測器。

多年來，AirGradient 一直沒有提供將軟體刷寫到 AirGradient ONE 上的說明。我是從以下這幾篇部落格文章學會做法的：

“Monitoring my home’s air quality (CO2, PM2.5, Temp/Humidity) with AirGradient’s DIY sensor”（《使用 AirGradient DIY 感測器監測家中空氣品質（CO2、PM2.5、溫濕度）》），作者為 Jeff Geerling（傑夫·吉爾林）
“AirGradient ONE Kit Review – An open-source indoor air quality monitor”（《AirGradient ONE 套件評測——一款開源室內空氣品質監測器》），作者為 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 的裝置路徑。尋找裝置路徑最簡單的方法是：

執行 dmesg --follow
透過 USB 將我的 AirGradient ONE 連接到電腦
在 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 網站上的最新版本與AirGradient 的 GitHub 儲存庫上最新的 release 標籤不一致。當我測試 3.3.9 時，我的兩台裝置都無法測量二氧化碳和溫度，因此我不確定 3.3.9 是否是已知有問題的版本。

取得版本號後，我從 AirGradient 的 GitHub 儲存庫抓取 AirGradient 原始碼：

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

注意：若要清除 AirGradient ONE 裝置上的永久性資料（即硬重置，包含設定資料），請在 --fqbn 旗標的結尾加上 ,EraseFlash=all。

如果刷寫成功，我會看到裝置重新啟動，並在流程結束時看到以下輸出：

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 裝置，並依自己的需求客製化韌體。