[TUBUYAKI]CursorとPlatformIOが動かない？

Arduino, Tubuyaki, プログラミング / By /

PlatformIO環境構築まとめ

2025/12/20、久々にCursor上でArduinoのプロジェクトにタッチしたところ、Cursor＊PlatformIOでエラー続発。あれがない、これがない…など。さんざんCursor君AIと試した結果、なんとか利用できるようになったので忘備録としてまとめておきます。
Mictrosoftが悪いんだよこれも。VSCodeのForkアプリの締め出しを始めたらしく、いろいろなものが利用不可になってた(InteliSense(バージョン限定)、PlatformIO(Extensionsに表示されない)＜ここがミソ)。以下情報は2025/12現在のものであり、半年後にはリンク消滅、変更などが想定されます。お気をつけあれ。
以下はAtom S3を用いたCANプロジェクトの例です。適宜読み替えてご利用ください。
Cursor君AI、神ですよ。これググるだけで調べてたら2日は必要でしたけど、Cursor君のおかげで3時間でした。課金($20)の価値はありますね。きついけどｗ

概要

M5Stack AtomS3 (ESP32-S3) 向けのPlatformIO開発環境の構築と、安定動作のための設定をまとめます。

1. PlatformIO設定 (platformio.ini)

基本設定

[env:m5stack-atoms3]
platform = espressif32
board = m5stack-atoms3
framework = arduino

COMポート設定

upload_port = COM4
monitor_port = COM4
monitor_speed = 115200
  • 注意: COMポート番号は環境に応じて変更してください
  • アップロードとモニターで同じポートを使用

シリアルモニター設定

monitor_filters = 
    send_on_enter
  • Enterキーで改行文字を送信するフィルター
  • デフォルトはCRLF（\r\n）が送信される
  • LF（\n）のみを送信したい場合は、コマンドラインで pio device monitor --eol LF を使用

USB CDC設定（重要）

build_flags = 
    -DARDUINO_USB_MODE=1
    -DARDUINO_USB_CDC_ON_BOOT=1
  • ESP32-S3のUSB CDC（USB Serial）を使用するために必須
  • この設定がないと、USBシリアル通信が動作しない

ライブラリ依存関係

lib_deps = 
    m5stack/M5Unified@^0.1.0
  • M5Unifiedライブラリを使用（M5AtomS3用の統合ライブラリ）

2. PlatformIO拡張機能のインストール

VSIXファイルからの直接インストール（必須）

重要: PlatformIO拡張機能は、Cursorの拡張機能マーケットプレイスからは正規の最新版をインストールできません。マーケットプレイスには個人製作の古いバージョンのPlatformIO IDE for Cursorしか存在せず、正規の最新版を使用するには、PlatformIO公式サイトからVSIXファイルをダウンロードしてインストールする必要があります。

インストール手順

  1. VSIXファイルのダウンロード

    • PlatformIO公式サイトからVSIXファイルをダウンロード
    • ダウンロードURL: https://platformio.org/install/ide?install=vscode
    • またはGitHubリリースページ: https://github.com/platformio/platformio-vscode-ide/releases
    • 最新版を使用することを推奨（マーケットプレイスには古いバージョンしかないため）
    • v3.3.4

  2. VSIXファイルのインストール方法

    方法1: コマンドパレットからインストール（推奨）

    • Cursorを開く
    • コマンドパレットを開く（Ctrl+Shift+P または F1）
    • Extensions: Install from VSIX... を入力して選択
    • ダウンロードしたVSIXファイル（.vsix）を選択
    • インストールが完了するまで待つ

    方法2: ドラッグ&ドロップ

    • Cursorを開く
    • 拡張機能ビューを開く（Ctrl+Shift+X）
    • ダウンロードしたVSIXファイルを拡張機能ビューにドラッグ&ドロップ
    • インストールが完了するまで待つ

    方法3: コマンドラインからインストール

    code --install-extension platformio.ide-<version>.vsix
    • またはCursorの場合は：
    cursor --install-extension platformio.ide-<version>.vsix

  3. 確認

    • 拡張機能一覧でPlatformIO IDEがインストールされていることを確認
    • 再起動後、PlatformIOアイコンがサイドバーに表示されることを確認
    • 拡張機能の詳細で、正規のPlatformIO IDE（platformio.platformio-ide）がインストールされていることを確認

注意事項

  • Cursorの拡張機能マーケットプレイスには個人製作の古いバージョンしかないため、使用しないこと
  • 必ずPlatformIO公式サイトからVSIXファイルをダウンロードしてインストールすること
  • インストール後、Cursorを再起動すること

3. IntelliSenseの構築

C/C++拡張機能のバージョン指定（必須）

重要: PlatformIOが正しく動作するには、C/C++拡張機能のバージョン1.23.6が必要です。このバージョン以外では、PlatformIOとの互換性の問題が発生し、IntelliSenseが正しく動作しません。

インストール手順

  1. 既存のC/C++拡張機能をアンインストール

    • Cursorの拡張機能一覧（Ctrl+Shift+X）を開く
    • C/C++ 拡張機能を検索
    • インストールされている場合は、右クリックして「アンインストール」
    • C/C++ Extension Pack もアンインストール（競合の可能性があるため）

  2. バージョン1.23.6のVSIXファイルをダウンロード

    • GitHubリリースページからバージョン1.23.6のVSIXファイルをダウンロード
    • ダウンロードURL: https://github.com/microsoft/vscode-cpptools/releases/tag/v1.23.6
    • ファイル名: cpptools-win32.vsix または cpptools-win64.vsix（OSに応じて選択）
    • 重要: 必ずバージョン1.23.6を使用すること
    • v1.23.6

  3. VSIXファイルからインストール

    • コマンドパレット（Ctrl+Shift+P）を開く
    • Extensions: Install from VSIX... を入力して選択
    • ダウンロードしたVSIXファイル（cpptools-win32.vsix または cpptools-win64.vsix）を選択
    • インストールが完了するまで待つ

  4. 自動更新の無効化（重要）

    • 拡張機能一覧で C/C++ を右クリック
    • Extension Settings を選択
    • Update: Mode を manual に設定
    • これにより、自動更新でバージョンが上がることを防ぐ

バージョン情報

  • C/C++ Extension: v1.23.6（必須）
  • 注意:
    • このバージョン以外ではPlatformIOが正しく動作しない
    • 最新版（v2.x.x以降）では、PlatformIOとの互換性の問題が報告されている
    • 自動更新を無効化して、バージョンが上がらないようにすること

IntelliSenseの初期化

  1. プロジェクトを開く

    • PlatformIOプロジェクトのフォルダをVS Code/Cursorで開く

  2. PlatformIOの初期化を待つ

    • PlatformIOが自動的に compile_commands.json を生成するまで待つ
    • 初回は数分かかる場合がある

  3. IntelliSenseの確認

    • C/C++ファイルを開き、コード補完やエラー表示が動作することを確認
    • 問題がある場合は、VS Code/Cursorを再起動

4. VS Code/Cursor設定

.vscode/settings.json

{
    "clangd.enable": false,
    "C_Cpp.intelliSenseEngine": "default"
}
  • 重要: clangdを無効化して、デフォルトのC/C++ IntelliSenseを使用
  • clangdとPlatformIOのIntelliSenseが競合するため、無効化が必要

IntelliSense設定の注意点

  • .vscode/c_cpp_properties.json は自動生成されるため、手動編集は不要
  • compile_commands.json は PlatformIO が自動生成
  • 手動で設定を追加すると、ビルドエラーやIntelliSenseエラーの原因になる可能性がある

.vscode/extensions.json（推奨）

{
    "recommendations": [
        "platformio.platformio-ide"
    ],
    "unwantedRecommendations": [
        "ms-vscode.cpptools-extension-pack"
    ]
}
  • cpptools-extension-pack は競合の可能性があるため、不要な推奨として設定

5. コード実装上の対策

USB CDC初期化

// ESP32-S3ではUSB CDCを使用する場合、少し待機が必要
delay(100);
Serial.begin(115200);
Serial.setTimeout(100);
while (!Serial && millis() < 3000) {
    delay(10);
}
  • USB CDCの初期化には時間がかかるため、待機処理が必要
  • Serial.setTimeout(100) でタイムアウトを設定

GPIOピン定義

#define CAN_TX_PIN GPIO_NUM_4
#define CAN_RX_PIN GPIO_NUM_5
  • 整数リテラル（4, 5）ではなく、GPIO_NUM_4, GPIO_NUM_5 を使用
  • gpio_num_t 型が必要な関数に渡すため

色定義（RGB565形式）

#define COLOR_GREEN  0x07E0  // 緑色
#define COLOR_YELLOW 0xFFE0  // 黄色
#define COLOR_RED    0xF800  // 赤色
#define COLOR_BLUE   0x001F  // 青色
  • M5UnifiedのディスプレイはRGB565形式（16ビット）
  • 色定数（GREEN, YELLOWなど）が正しく動作しない場合があるため、RGB565値を直接指定

6. シリアル通信の注意点

改行文字の処理

  • PlatformIOのシリアルモニターはデフォルトでCRLF（\r\n）を送信
  • コード側で \n と \r の両方に対応する必要がある
  • TeraTermなど他のターミナルソフトではLF（\n）のみを送信する場合がある

シリアルバッファの処理

while (Serial.available() > 0) {
    char c = Serial.read();
    if (c == '\n' || c == '\r') {
        // 行の終わりを処理
    }
}
  • \r\n の場合は \r を処理後、\n を読み飛ばす処理が必要

7. トラブルシューティング

IntelliSenseエラーが表示される

  • 原因: clangdとPlatformIOのIntelliSenseの競合
  • 対策: .vscode/settings.json で clangd.enable: false を設定

USBシリアルが動作しない

  • 原因: USB CDC設定が不足
  • 対策: build_flags に -DARDUINO_USB_MODE=1 と -DARDUINO_USB_CDC_ON_BOOT=1 を追加

色が正しく表示されない

  • 原因: 色定数が正しく定義されていない、またはカラー深度の問題
  • 対策: RGB565形式で色を直接指定

シリアルモニターからデータが受信されない

  • 原因: 改行文字の不一致、またはポートの競合
  • 対策:
    • コード側で \n と \r の両方に対応
    • TeraTermなど他のターミナルソフトで動作確認
    • コマンドラインで pio device monitor --eol LF を使用

IntelliSenseが動作しない

  • 原因: C/C++拡張機能のバージョンが1.23.6ではない、またはPlatformIO拡張機能が正しくインストールされていない
  • 対策:
    • C/C++拡張機能をバージョン1.23.6にダウングレード（必須）
    • PlatformIO拡張機能をVSIXファイルから再インストール
    • Cursorを再起動

PlatformIO拡張機能がインストールできない

  • 原因: Cursorの拡張機能マーケットプレイスには個人製作の古いバージョンしかない
  • 対策:
    • PlatformIO公式サイトからVSIXファイルをダウンロード
    • VSIXファイルから直接インストールする
    • マーケットプレイスからはインストールしないこと

VSIXファイルがインストールできない

  • 原因: ファイルパスに問題がある、またはCursorの権限の問題
  • 対策:
    • ファイルパスに日本語や特殊文字が含まれていないか確認
    • 管理者権限でCursorを起動して再試行
    • コマンドパレットから Extensions: Install from VSIX... を使用

8. 推奨される開発フロー

  1. プロジェクト作成

    pio project init --board m5stack-atoms3

  2. 設定ファイルの確認

    • platformio.ini の設定を確認
    • .vscode/settings.json の設定を確認

  3. ビルドとアップロード

    pio run --target upload

  4. シリアルモニター起動

    pio device monitor

    または

    pio device monitor --eol LF

9. 参考情報

  • PlatformIO公式ドキュメント: https://docs.platformio.org/
  • M5Unifiedライブラリ: https://github.com/m5stack/M5Unified
  • ESP32-S3 Arduino Core: https://github.com/espressif/arduino-esp32

10. まとめ

必須設定

  1. PlatformIO拡張機能をVSIXファイルからインストール（公式サイトから）
    • Cursorの拡張機能マーケットプレイスからはインストールしない
  2. C/C++拡張機能をバージョン1.23.6にインストール（必須）
    • このバージョン以外ではPlatformIOが動作しない
    • 自動更新を無効化すること
  3. platformio.ini にUSB CDC設定を追加
  4. .vscode/settings.json でclangdを無効化
  5. USB CDC初期化時に待機処理を追加

推奨設定

  1. COMポートを明示的に指定
  2. シリアルモニターのフィルター設定
  3. RGB565形式で色を直接指定

注意事項

  1. PlatformIO拡張機能はVSIXファイルからインストールする（必須）
    • Cursorの拡張機能マーケットプレイスには個人製作の古いバージョンしかない
    • 必ずPlatformIO公式サイトからVSIXファイルをダウンロードすること
  2. C/C++拡張機能はバージョン1.23.6を使用する（必須）
    • このバージョン以外ではPlatformIOが正しく動作しない
    • 自動更新を無効化して、バージョンが上がらないようにすること
  3. IntelliSense設定は手動編集を避ける
  4. シリアル通信は改行文字の処理に注意
  5. GPIOピン定義は GPIO_NUM_* 形式を使用

11. バージョン情報

必須バージョン

以下のバージョンは必須です。これ以外のバージョンでは動作しません：

  • C/C++ Extension: v1.23.6（必須）

    • ダウンロード先: https://github.com/microsoft/vscode-cpptools/releases/tag/v1.23.6
    • ファイル名: cpptools-win32.vsix または cpptools-win64.vsix
    • 重要: このバージョン以外ではPlatformIOが正しく動作しない

  • PlatformIO IDE: 最新版（推奨、3.3.4で確認済み）

    • ダウンロード先: https://platformio.org/install/ide?install=vscode
    • または: https://github.com/platformio/platformio-vscode-ide/releases
    • 注意: Cursorの拡張機能マーケットプレイスからはインストールできない（個人製作の古いバージョンしかない）
    • VSIXファイルから直接インストールすること

バージョン確認方法

# PlatformIOのバージョン確認
pio --version

# Cursorのバージョン確認
cursor --version

# インストールされている拡張機能のバージョン確認
# Cursorの拡張機能一覧（Ctrl+Shift+X）から確認
# または、コマンドパレットから "Extensions: Show Installed Extensions" を実行

バージョン確認の重要性

  • C/C++ Extension: 拡張機能一覧で「v1.23.6」であることを確認
  • PlatformIO IDE: 拡張機能一覧で「platformio.platformio-ide」であることを確認（個人製作版ではない）

最終更新日: 2024年
対象環境: Windows 10/11, PlatformIO, M5Stack AtomS3 (ESP32-S3)
重要: バージョン番号は実際の環境に応じて確認・調整してください