Flash an AirGradient ONE from the Command Line

2025-08-23

透過命令列刷寫 AirGradient ONE

原文由 Michael Lynch 于 2025-08-23 發布，訂閱此部落格

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

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

現有的韌體刷寫文件要求你使用 Arduino IDE，一套笨重的圖形介面程式：

現有刷寫 AirGradient ONE 的說明都仰賴 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” by Jeff Geerling
“AirGradient ONE Kit Review – An open-source indoor air quality monitor” by 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 儲存庫抓取原始碼：

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