PlatformIO on Ubuntu — Arduino/ESP32開発のVSCode統合環境

開発環境

この記事のポイント

  • Ubuntu 24.04 は PEP 668 の制約があるため python3 -m venv で仮想環境を作ってから pip install platformio する
  • 実測で PlatformIO Core 6.1.19（Python 3.12.3）がインストールされることを確認
  • pio project init --board uno --ide vscode 一発でVSCode設定・ディレクトリ構造が自動生成される
  • ESP32 は --board az-delivery-devkit-v4 等のボードIDを指定するだけで対応プラットフォームが自動インストールされる
  • pio home で起動するブラウザUIからボード・ライブラリを検索できる

PlatformIO は Arduino IDE の「わかりやすいが機能不足」という問題を解消してくれる、組み込み開発向けのCLI＆VSCode統合ツールです。Arduino Uno から ESP32・Raspberry Pi Pico まで、ひとつの設定ファイル platformio.ini で複数のターゲットボードを管理できます。

今回は Ubuntu 24.04 LTS（Docker公式イメージ）で実際にインストールし、バージョン 6.1.19 が正常動作することを実測で確認しました。Ubuntu 22.04 との違いもまとめています。

動作確認済み環境

Ubuntu 24.04.1 LTS（docker run –rm ubuntu:24.04）/ Ubuntu 22.04 LTS 比較あり / 2026-06-22 実測

PlatformIO と Arduino IDE の違い

Arduino IDE はシンプルさが魅力ですが、ファイルが一枚のスケッチに限られ、バージョン管理・テスト・外部エディタとの連携が苦手です。PlatformIO はその部分を補います。

  • VSCode で書いてターミナルで pio run、という普通の開発フローが使える
  • ライブラリをコードで宣言管理（platformio.ini に書けば pio lib install 一発）
  • Arduino・ESP-IDF・mbed など複数フレームワークを同じツールで扱える
  • pio test でユニットテストも動く

正直、Arduino IDE から乗り換えるとき「設定ファイルが増えて面倒くさい」と感じましたが、一度 platformio.ini の書き方を覚えれば、プロジェクトを git で管理できるようになるのでそれ以上の価値がありました。

Ubuntu 24.04 でのインストール手順

手順1：前提パッケージのインストール

PlatformIO は Python パッケージとして提供されています。Ubuntu 24.04 には Python 3.12 が同梱されていますが、仮想環境作成用の python3-venv が別途必要です。




ubuntu@linuxlab: ~
$ sudo apt update && sudo apt install -y python3 python3-venv
Setting up python3.12 (3.12.3-1ubuntu0.13) …
Setting up python3-venv (3.12.3-0ubuntu2.1) …
$ python3 –version
Python 3.12.3

手順2：仮想環境を作成して PlatformIO をインストール

Ubuntu 24.04 は PEP 668 によりシステム Python への直接 pip install が禁止されています。python3 -m venv で仮想環境を作り、その中にインストールします。




ubuntu@linuxlab: ~
$ python3 -m venv /opt/pio_env
$ source /opt/pio_env/bin/activate
(pio_env) $
(pio_env) $ pip install platformio
Successfully installed ajsonrpc-1.2.0 bottle-0.13.4 click-8.3.3
colorama-0.4.6 marshmallow-3.26.1 platformio-6.1.19
pyserial-3.5 requests-2.34.2 starlette-0.52.1 uvicorn-0.40.0
Ubuntu 24.04 での PlatformIO インストール実ログ（実測）
Ubuntu 24.04 での PlatformIO インストール実ログ（実測）

注意：Ubuntu 24.04 で起きる PEP 668 エラー

仮想環境なしで pip3 install platformio を実行すると error: externally-managed-environment というエラーが出ます。これは意図的な制約です。必ず python3 -m venv で仮想環境を用意してください。

手順3：インストール確認




ubuntu@linuxlab: ~
(pio_env) $ pio –version
PlatformIO Core, version 6.1.19
(pio_env) $ pio system info
PlatformIO Core 6.1.19
Python 3.12.3-final.0
System Type linux_x86_64
Platform Linux-6.8.0-83-generic-x86_64-with-glibc2.39

pio system info で環境情報が出ればインストール成功です。Python 3.12.3-final.0 / linux_x86_64 を確認しました。

Ubuntu 22.04 との違い

PlatformIO Core のバージョン（6.1.19）は両方で同じです。違いはインストール方法と Python バージョンです。

Ubuntu 22.04 vs 24.04 PlatformIO インストール比較（実測）
Ubuntu 22.04 vs 24.04 PlatformIO インストール比較（実測）

Ubuntu 22.04 では Python 3.10.12 が使われており、PEP 668 の制約がないため pip3 install platformio で直接インストールできます。ただし root で実行した場合は警告が出ます。Ubuntu 24.04 を使う場合は仮想環境が必須と覚えておくと混乱しません。

VSCode 拡張機能のインストール

ターミナルから PlatformIO Core をインストールしたら、VSCode の拡張機能「PlatformIO IDE」も追加します。VSCode の拡張機能タブで platformio と検索し、「PlatformIO IDE」（公式・著者: PlatformIO Labs）をインストールしてください。

拡張機能をインストールすると左サイドバーにアリのアイコン（PlatformIO）が追加されます。ここからプロジェクト作成・ビルド・書き込みをGUIで操作できます。ターミナルの pio コマンドと拡張機能は同じ設定ファイル（platformio.ini）を共有するため、どちらから操作しても結果は同じです。

注意：パスの設定

仮想環境内の pio を VSCode 拡張が認識しない場合があります。which pio でパスを確認し、VSCode の設定 platformio-ide.pioHome に反映してください。もしくは仮想環境を ~/.platformio に作ると自動認識されます。

はじめてのプロジェクト：Arduino Uno

手順1：pio project init でプロジェクトを作る

空のディレクトリを作り、pio project init を実行するとプラットフォームのダウンロードから設定ファイル生成まで自動で進みます。




ubuntu@linuxlab: ~
(pio_env) $ mkdir myproject && cd myproject
(pio_env) $ pio project init –board uno –ide vscode
The following files/directories have been created in /home/ubuntu/myproject
include – Put project header files here
lib – Put project specific (private) libraries here
src – Put project source files here
platformio.ini – Project Configuration File
Resolving uno dependencies…
Platform Manager: Installing atmelavr
Platform Manager: atmelavr@5.2.0 has been installed!
Tool Manager: Installing platformio/toolchain-atmelavr @ ~1.70300.0

atmelavr@5.2.0（Arduino Uno 向けプラットフォーム）と対応ツールチェーンが自動でダウンロードされました。

pio project init 後のプロジェクト構造（実測）
pio project init 後のプロジェクト構造（実測）

手順2：platformio.ini を確認する

生成された platformio.ini の中身がプロジェクトの核心です。




ubuntu@linuxlab: ~/myproject
(pio_env) $ cat platformio.ini
; PlatformIO Project Configuration File
; https://docs.platformio.org/page/projectconf.html

[env:uno]
platform = atmelavr
board = uno
framework = arduino

[env:uno] という環境名、ボード、フレームワークの3行がすべてです。ESP32 に切り替えるなら [env:esp32dev] board = az-delivery-devkit-v4 framework = arduino と書き換えるだけです。

手順3：スケッチを書いてビルドする

src/main.cpp に Arduino スケッチを書きます。




ubuntu@linuxlab: ~/myproject
// src/main.cpp
#include <Arduino.h>

void setup() {
Serial.begin(9600);
}

void loop() {
Serial.println(“Hello from PlatformIO!”);
delay(1000);
}

書いたら pio run でビルドします。書き込みは pio run --target upload、シリアルモニタは pio device monitor です。

ESP32 開発の場合

ESP32 向けプロジェクトも手順は同じで、ボードIDだけ変えます。pio boards espressif32 を実行して確認した対応ボードの一部を紹介します。

ボードID MCU クロック フラッシュ モジュール名
az-delivery-devkit-v4 ESP32 240MHz 4MB AZ-Delivery ESP-32 Dev Kit C V4
esp32cam ESP32 240MHz 4MB AI Thinker ESP32-CAM
featheresp32 ESP32 240MHz 4MB Adafruit ESP32 Feather
featheresp32-s2 ESP32S2 240MHz 4MB Adafruit ESP32-S2 Feather
adafruit_feather_esp32_v2 ESP32 240MHz 8MB Adafruit Feather ESP32 V2

ボード一覧は pio boards espressif32 で確認できます。ESP32 系だけで多数のボードが登録されており、4D Systems・AI Thinker・Adafruit など様々なメーカーのモジュールに対応しています。

ESP32 でプロジェクトを作る場合、pio project init --board az-delivery-devkit-v4 を実行します。初回はネットワークから espressif32 プラットフォームがダウンロードされるため数分かかります。生成される platformio.ini の中身は platform = espressif32 / board = az-delivery-devkit-v4 / framework = arduino の3行です（Arduino Uno の場合と同じ構造）。

PlatformIO Home — ブラウザから操作する

pio home を実行すると http://localhost:8008 で Web UI が起動します。ボード検索・ライブラリ追加・プロジェクト管理がブラウザから操作できます。




ubuntu@linuxlab: ~
(pio_env) $ pio home
Tool Manager: contrib-piohome@3.4.4 has been installed!
Open PlatformIO Home in your browser => http://0.0.0.0:8008/
PIO Home has been started. Press Ctrl+C to shutdown.
PlatformIO Home ホーム画面（実撮影）
PlatformIO Home ホーム画面（実撮影）

Boards タブでは対応ボードを絞り込み検索できます。「ESP32」で検索すると ESP32-S2・ESP32-S3 なども一覧で確認できます。

PlatformIO Home Boards 画面（実撮影）
PlatformIO Home Boards 画面（実撮影）

Libraries タブでは登録ライブラリ（DHT sensor library・OLED driver 等）をキーワード検索し、ワンクリックで platformio.ini への追加指示を表示してくれます。

PlatformIO Home Libraries 画面（実撮影）
PlatformIO Home Libraries 画面（実撮影）

PlatformIO の依存パッケージ

インストール時に一緒に入るパッケージの内訳です。pyserial がシリアル通信（書き込み・モニタ）を担い、uvicorn＋starlette が PlatformIO Home の Web サーバを動かしています。

PlatformIO 6.1.19 依存パッケージ一覧（実測）
PlatformIO 6.1.19 依存パッケージ一覧（実測）

よくあるエラーと解決策

①「error: externally-managed-environment」が出る

Ubuntu 24.04 で仮想環境なしに pip3 install platformio を実行すると発生します。




ubuntu@linuxlab: ~
$ pip3 install platformio
error: externally-managed-environment
× This environment is externally managed
hint: See PEP 668 for the full story.

解決策：python3 -m venv /opt/pio_env && source /opt/pio_env/bin/activate で仮想環境を作ってから pip install platformio を実行してください。

②「pio: command not found」になる

仮想環境を activate せずにターミナルを開き直したときに起きます。ログインシェルに source /opt/pio_env/bin/activate を追記するか、~/.bashrc に以下を加えると毎回自動で activate されます。




ubuntu@linuxlab: ~
$ echo ‘source /opt/pio_env/bin/activate’ >> ~/.bashrc
$ source ~/.bashrc
$ pio –version
PlatformIO Core, version 6.1.19

③ USB シリアルが認識されない（/dev/ttyUSB0 が出ない）

Linux でマイコンを USB 接続してもデバイスが見えないときは、ユーザーを dialout グループに追加することで解決することがほとんどです。




ubuntu@linuxlab: ~
$ sudo usermod -aG dialout $USER
# ログアウト→ログインし直して反映
$ pio device list
/dev/ttyUSB0
Hardware ID: USB VID:PID=2341:0043 SER=…

参考：ビルド速度の目安（sysbench）

PlatformIO のビルド速度はホストの CPU 性能に直結します。今回の実測環境（Docker ubuntu:24.04）でのCPUベンチ結果を参考として載せます。

sysbench CPU ベンチ結果（実測）
sysbench CPU ベンチ結果（実測）

sysbench CPU は 平均 13,877 events/sec（threads=2、10秒×3回）でした。Arduino Uno のスケッチなら数秒、ESP32 の大きめなプロジェクトでも30〜60秒程度でビルドが完了します。

まとめ

  • Ubuntu 24.04 での PlatformIO インストールは python3 -m venv /opt/pio_env → pip install platformio の順で実施する
  • インストールされるバージョンは PlatformIO Core 6.1.19（Python 3.12.3）
  • pio project init --board uno --ide vscode でプロジェクトと VSCode 設定が一括生成される
  • ESP32 への切り替えも platformio.ini のボードIDを変えるだけ
  • pio home で起動する Web UI からボード・ライブラリを検索できる
  • USB 書き込みには dialout グループへの追加が必要

開発が進んだらVPSで継続的インテグレーション環境を組むのも選択肢のひとつです。LinuxLab では VPS 比較記事も用意しています。


Vultr 公式サイトでプランを確認する →

関連：Ubuntu サーバー初期設定ガイド

コメント

タイトルとURLをコピーしました