1. この記事でわかること

M5Stack Core2 の開発環境整備
- ドライバの導入
- VSCodeと拡張機能を使った環境整備
簡単な M5Stack Core2 の動作確認 (Lチカ)
著者がつまずいた色々 (ディレクトリ構成、ビルドエラーなど)

対象者：ある程度VSCodeでの開発に慣れている人向け

2. はじめに

2.1. 作業環境

PC
- OS : Windows 11
- CPU : AMD Ryzenシリーズ
  - Apple Mチップシリーズでなければ、命令セットアーキテクチャ (ISA) がCISC(x86/x64 : Intel, AMD) なのでたぶん同じ
  - ちなみに M2 チップはRISCなのでライブラリが対応してないと実行できない（2025年1月22日時点では実行できた）
- 開発環境：VSCode + PlatformIO
  - Arduino, ESP-IDF などの開発環境もあるが、今回は「VSCode + PlatformIO」を採用
M5Stack Core2 v1.1

3. 実作業

3.1. 実行環境の作成

3.1.1. ドライバの導入（必要に応じて）

M5Stack Core2とPCをUSBケーブルで接続すると、COMポートとして認識される必要がある
もし認識されない場合は、以下のドライバ（CP210x）をインストール

CP210x USB to UART Bridge VCP Drivers

このドライバをインストール後、デバイスマネージャーでCOMポートを確認

適切なドライバを探す方法

商品ページ（M5Stack Core2 v1.1）のUSBドライバの部分に以下の記載がある。

ページ上部の「ソフトウェア」>「Device USB Driver」（リンク）から該当のドライバを選択してダウンロードしてインストールする

3.1.2. VSCodeで拡張機能の導入

VSCodeを起動し、以下の拡張機能をインストール

3.1.2.1. PlatformIO IDE

VSCodeの拡張機能検索で「PlatformIO IDE」と検索し、インストール。
PlatformIO IDEは、マイコン開発を支援する強力なツールで、ライブラリ管理やビルド、書き込みを簡単に行うことができる。

3.1.2.2. Serial Monitor

VSCodeの拡張機能検索で「Serial Monitor」と検索し、インストール。
Serial Monitorは、M5Stack Core2から出力されるシリアル通信の内容を表示するためのツールになる。
デバッグ時に役立ちます。

3.2. サンプルコードの作成

3.2.1. プロジェクトの作成

PlatformIO IDEをインストール後、画像のような操作で「New Project」までアクセスする。左下の小さい家のアイコンが楽。
表示されたメニューから「New Project」を選択し、以下の設定でプロジェクトを作成します。

プロジェクト名: 任意の名前を入力 (例: M5Core2_Blinky)
Board: M5Stack Core2 を選択
Framework: デフォルトのままでOK

プロジェクトの作成が完了するまで、しばらくお待ちください。

3.2.2. 必要なライブラリをプロジェクトに導入する

M5Stack Core2を制御するために、必要なライブラリ M5Core2 をプロジェクトに導入します。

VSCodeの左下にあるPlatformIOアイコン（左下の小さい家のアイコン）をクリックしHomeに移動
表示されるメニューから「Libraries」を選択
検索バーに M5Core2 と入力し、検索結果から M5Core2 by m5stack を選択
Add to Project ボタンをクリックし、先ほど作成したプロジェクトに追加

重要な注意点:
ライブラリ M5Core2 の最新バージョンでは、ビルドが失敗する事例が確認されています。
そのため、本記事では安定して動作する ver. 0.1.8 を指定して導入します。
バージョンに関する情報は、スイッチサイエンスの商品ページにも記載がありますので、参考にしてください。（詳しく追いきれてないです orz ）

3.2.3. コーディング（Lチカ）

ライブラリの導入が完了したら、src/main.cpp ファイルに以下のサンプルコードを記述します。
このコードは、M5Stack Core2のディスプレイを制御する基本的な方法を示しており、Lチカよろしく、ディスプレイを黒白切り替えるコードになっています。

#include <M5Core2.h>

void setup() {
  M5.begin(); // M5Core2の初期化
  M5.Lcd.fillScreen(BLACK); // 画面を黒で塗りつぶす
}

void loop() {
  M5.Lcd.fillScreen(WHITE); // 画面を白で塗りつぶす
  delay(500); // 500ミリ秒待機
  M5.Lcd.fillScreen(BLACK); // 画面を黒で塗りつぶす
  delay(500); // 500ミリ秒待機
}

3.3. ビルドと書き込み

VSCodeの左下にあるPlatformIOのアイコンをクリックします。
表示されたメニューから、まず Build ボタンをクリックしてコードをコンパイルします。
ビルドが成功すると、ターミナルに SUCCESS と表示されます。

次に、Upload ボタンをクリックして、コンパイルしたコードをM5Stack Core2に書き込みます。
書き込みが完了すると、M5Stack Core2のディスプレイが0.5秒間隔で点滅し始めます。

もし書き込みがうまくいかない場合は、COMポートの設定などを確認してください。

4. Appendix

4.1. ディレクトリ構成について

PlatformIOのプロジェクトでは、ソースコードはsrcディレクトリ以下に置くのが基本です。
しかし、main.cpp以外のコードをsrcディレクトリ直下に置くと、コンパイルエラーが発生することがあります。
これは、PlatformIOがsrcディレクトリ直下にあるファイルを特別に扱うためです。

解決策として、./lib/myfunc/などlibディレクトリ以下に任意のディレクトリを作成し、そこに自作のコードを置くのが良いです。
例えば、./lib/myfunc/myfunc.cppに自作の関数を記述し、./lib/myfunc/myfunc.hでヘッダーを定義しておけば、main.cppから #include "myfunc.h" で利用できます。

以下のようなディレクトリ構成が推奨されます。

project/
├── lib/
│   └── myfunc/
│       ├── myfunc.cpp
│       └── myfunc.h
├── src/
│   └── main.cpp
├── platformio.ini
└── ...

このようにディレクトリ構成を整理することで、大規模なプロジェクトでもコードの管理が容易になります。

4.2. `platformio.ini` について

platformio.ini は、PlatformIOプロジェクトの設定を記述するファイルです。
主に以下の情報を設定・管理するために使用します。

今回作成したプロジェクトでは次のようになっている。

細かい説明が気になる方は以下を開いてください。

環境設定 ([env:...]):
- ターゲットとなるボードの種類、コンパイラオプション、使用するフレームワークなどを環境ごとに定義します。
- 例えば、[env:m5stack-core2] のように、ボードの種類を環境名として指定します。
ライブラリ依存関係 (lib_deps):
- プロジェクトで使用するライブラリとそのバージョンを指定します。
- lib_deps = m5stack/M5Core2 @ 0.1.8 のように、ライブラリ名とバージョンを明示的に記述することで、特定のバージョンのライブラリを利用できます。（「3.2.2. 必要なライブラリをプロジェクトに導入する」を参照）
- PlatformIOは、この設定に基づいて必要なライブラリを自動的にダウンロードし、プロジェクトに組み込みます。
シリアルポート設定 (monitor_port):
- シリアルモニタで使用するCOMポートを指定します。
- monitor_port = COM3 のように指定することで、特定のCOMポートと接続することができます。
- 通常はPlatformIOが自動で認識しますが、複数のCOMポートが存在する場合は、手動で設定する必要がある場合があります。
ボーレート設定 (monitor_speed):
- シリアルモニタで使用するボーレート（通信速度）を指定します。
- monitor_speed = 115200 のように指定します。M5Stack Core2では通常115200を使用します。
ビルドオプション (build_flags):
- コンパイラやリンカに渡す追加オプションを指定します。
- 特定のコンパイルオプションや、マクロ定義などを追加したい場合に利用します。
その他設定:
- PlatformIOの動作に関わる様々な設定を行うことができます。
- 例えば、アップロード時のオプション、使用するプログラマーなどを指定できます。

platformio.ini の重要性:

platformio.ini は、プロジェクトの設定を管理する上で非常に重要な役割を果たします。
このファイルに設定を記述することで、以下のメリットが得られます。

環境の一貫性: プロジェクトに参加するメンバー間で、開発環境を統一できます。
ライブラリ管理の容易化: 使用するライブラリとそのバージョンを明示的に指定できるため、ライブラリの互換性問題を回避できます。
設定の可視化: プロジェクトの設定内容をファイルで管理できるため、変更履歴を追跡したり、設定内容を共有したりするのが容易になります。

platformio.ini の編集例:

[env:m5stack-core2]
platform = espressif32
board = m5stack-core2
framework = arduino
lib_deps =
    m5stack/M5Core2 @ 0.1.8
monitor_speed = 115200
; monitor_port = COM3

この例では、M5Stack Core2用の環境設定として、ボードの種類、フレームワーク、ライブラリ依存関係、シリアルモニタの速度を設定しています。monitor_port の行はコメントアウトされていますが、必要に応じて有効化してください。

platformio.ini を適切に設定することで、より快適で効率的な組み込み開発が可能になります。
必要に応じて、PlatformIOの公式ドキュメント(https://docs.platformio.org/en/latest/projectconf/index.html) を参照してください。