Flash an AirGradient ONE from the Command Line

2025-08-23

コマンドラインからAirGradient ONEに書き込む

自宅の空気質を測定するため、AirGradient ONEの室内空気質モニターを2台購入しました。AirGradientのデバイスはオープンソースなので、自分でカスタムファームウェアを書き込み、AirGradient独自のクラウドダッシュボードにデータを送信するのではなく、空気質のデータをローカルで収集できます。

オフィスには、CO2と汚染物質を測定するためAirGradient ONEの空気質モニターを置いています。

既存のファームウェア書き込み手順では、扱いにくいGUIプログラムであるArduino IDEを使う必要があります。

AirGradient ONEの既存の書き込み手順は、扱いにくいGUIプログラムであるArduino IDEに依存しています。

コマンドラインからAirGradientのデバイスに書き込む手順は見つけられず、方法を把握するのに数時間かかりました。そこで、ここに手順をまとめます。

余談：AirGradientがなぜそんなに騒がれているのか、よくわからない

フォーラムの議論でAirGradientの話題が出るたびに、誰もが製品に期待しているように見えます。私が使ったAirGradient ONEは、平凡なものでした。ソフトウェアには非常に多くのバグがあり、ドキュメントも乏しいです。それでも、オープンソースの完成品の空気質モニターを販売している会社は、私が見つけた限りではAirGradientだけでした。だから、2台目のAirGradientモニターも購入しました。

AirGradientは何年もの間、AirGradient ONEにソフトウェアを書き込む手順を公開しようともしませんでした。私は次のブログ記事を読んで、その方法を学びました。

「AirGradientのDIYセンサーで自宅の空気質（CO2、PM2.5、温度／湿度）を監視する」（Jeff Geerling）
「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を実行する
AirGradient ONEをUSB経由でシステムに接続する
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リポジトリにある最新のリリースタグと一致していません。3.3.9をテストしたところ、2台ともCO2と温度を測定できませんでした。そのため、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デバイスへの書き込みや、好みに合わせたファームウェアのカスタマイズに役立てば幸いです。