STM32 MCU：PlatformIOの設定

いつものAIとセットアップ

Gemini・その他のAI

質問文をコピーして、いつものAIに貼り付け。キットの確認から動作確認まで、一つずつ進められます。

質問文をコピーして、Geminiの入力欄に貼り付けてください。

質問文を確認

Leafonyの初期設定を日本語で1段階ずつ案内してください。まず目的（出荷デモ／開発）、キット名、写真または装着リーフ型番・組立状態・全給電元を確認。必要な書換え履歴・OS・ツールも聞いてください。どのLEDや画面が変化したか、何を交換したかを確認し、見えないボタンを不存在と断定しないでください。操作1つと成功の目安を示し、結果を待つ。Basic Kit 2の未変更AVRデモはBasic Kit手順へ。書換え前に上書きを説明して意向確認。組替え前は全電源OFF。USBリーフの自動リセット対応・ポート使用アプリも確認。仕様は現行の公式URLで検証し、観測と推測を区別。転送先を読み、読めなければ本文やエラーを求めてください。

ページ: STM32 MCU：PlatformIOの設定

URL: https://docs.leafony.com/environment/stm32/platformio/

はじめ方: https://docs.leafony.com/getting-started/

Basic Kitのデモ: https://docs.leafony.com/getting-started/basic/

開発環境: https://docs.leafony.com/environment/

概要・見出し（抜粋）: PlatformIOでAP03 STM32 MCUリーフの開発環境を整え、プログラムを書き込む手順です。 / はじめに / 用意するもの / 事前準備 / 1. VS CodeとPlatformIO IDEをインストールする

はじめに

このページでは、STM32 MCUリーフ（AP03）にプログラムを書き込み、シリアルモニターで動作を確認する手順を説明します。作成するプログラムは、1秒ごとにHello Worldを表示するものです。

プログラムの作成・ビルドには、Visual Studio Code（VS Code）と拡張機能のPlatformIO IDEを使います。書き込みにはSTM32CubeProgrammerを使い、USBリーフ経由でパソコンと接続します。

ソフトウェアは、各公式サイトで配布されている最新の安定版をインストールしてください。以前の手順にあったSTM32CubeProgrammerの旧バージョン指定は不要です。

用意するもの

STM32 MCUリーフ（AP03 / STM32L452REI6）
USBリーフ
データ通信対応のUSBケーブル
Windows、macOS、またはLinuxのパソコン
インターネット接続

Basic Kit 2を使う場合は、組み込まれているAVR MCUリーフをSTM32 MCUリーフに交換します。

事前準備

1. VS CodeとPlatformIO IDEをインストールする

VS Codeのインストール

VS Codeの公式ダウンロードページから、使用するOS・CPUに合ったインストーラーを入手して実行します。
拡張機能一覧の表示

VS Codeを起動し、左側の拡張機能を開きます。
PlatformIO IDEのインストール

PlatformIO IDEを検索し、発行元がPlatformIOの拡張機能をインストールします。
初期セットアップの完了確認

セットアップの完了まで待ちます。再起動の案内が表示された場合は、VS Codeを再起動します。

PlatformIO Coreとシリアルモニターは、PlatformIO IDEに含まれています。対応するOSではPythonも自動で用意されます。

Pythonのインストールを求められた場合は、PlatformIO公式のPython導入手順に従ってください。Linuxではpython3-venvも必要です。

次の拡張機能は、必要に応じて追加します。

日本語表示：Japanese Language Pack for Visual Studio Code
グラフ表示：Teleplot

操作の詳細はPlatformIO IDEの公式ドキュメントも参照してください。

2. STM32CubeProgrammerをインストールする

STM32CubeProgrammerは、STM32 MCUにプログラムを書き込むソフトウェアです。ST公式のダウンロードページから、使用するOSに合った最新版を入手してインストールします。

このページでは、PlatformIOからSTM32CubeProgrammerのコマンドラインツールを直接呼び出します。Arduino IDEやArduino IDE用のボードパッケージを別途インストールする必要はありません。

インストール後は、次の実行ファイルの場所を確認しておきます。platformio.iniの設定で、その場所をupload_commandに指定します。

OS	実行ファイル
Windows	インストール先の`bin/STM32_Programmer_CLI.exe`
macOS	`STM32CubeProgrammer.app`内の`Contents/Resources/bin/STM32_Programmer_CLI`
Linux	インストール先の`bin/STM32_Programmer.sh`

3. プロジェクトの保存先を決める

保存先には、半角英数字で構成したローカルフォルダーを推奨します。パスの扱いによるトラブルを避けるためです。Windowsでの例はC:/PlatformIO/Projectsです。

ユーザーフォルダーやOneDriveの場所は、パソコンによって異なります。設定例のパスを使う前に、実際の保存先を確認してください。

このページのコマンドは、PlatformIO Core CLIのターミナルで実行します。VS Code左側のPlatformIO → Quick Access → Miscellaneous → PlatformIO Core CLIから開いてください。

PlatformIO Homeで使う既定の保存先も変更できます。次はC:/PlatformIO/Projectsへの変更例です。コマンドの実行後、VS Codeを再起動してください。

pio settings set projects_dir "C:/PlatformIO/Projects"

macOS・Linuxでは、引用符内を保存先フォルダーの絶対パスに置き換えてください。変更後の保存先は新規プロジェクトに適用され、既存プロジェクトは移動しません。詳細はprojects_dirの公式説明を参照してください。

クイックスタート

1. プロジェクトとボード定義を用意する

ボード定義には、Leafony配布のファイルを使います。この定義には、AP03用のピン配置とシリアル通信設定が含まれています。PlatformIOに登録されているLeafony Systems AP03とは内容が異なります。

プロジェクトフォルダーの作成

保存先にSTM32_Hello_World_Pjtという空のフォルダーを作ります。VS Codeのファイル → フォルダーを開くで、このフォルダーを開きます。
ボード定義のダウンロード

ボード定義のリポジトリでCode → Download ZIPを選びます。ダウンロードしたZIPを展開します。
配置先フォルダーの作成

プロジェクトの直下にboards、variants、srcを作ります。variantsの中にはSTM32L4xxを作ります。
ボード定義のコピー

展開したフォルダー直下のLEAFONY_AP03.jsonをboardsにコピーします。同じ場所にあるLEAFONY_AP03フォルダー全体を、variants/STM32L4xxにコピーします。ファイル名・フォルダー名は、大文字と小文字も合わせてください。
設定ファイルとソースファイルの作成

プロジェクトの直下にplatformio.ini、srcの中にmain.cppを作ります。内容は、この後の手順で記述します。

配置後の構成は次のとおりです。

STM32_Hello_World_Pjt/
├── platformio.ini
├── boards/
│   └── LEAFONY_AP03.json
├── variants/
│   └── STM32L4xx/
│       └── LEAFONY_AP03/
│           ├── PeripheralPins.c
│           ├── PinNamesVar.h
│           ├── generic_clock.c
│           ├── ldscript.ld
│           ├── variant_generic.cpp
│           ├── variant_generic.h
│           ├── variant_LEAFONY_AP03.cpp
│           └── variant_LEAFONY_AP03.h
└── src/
    └── main.cpp

PlatformIOは、ボード定義をプロジェクト内のboardsフォルダーから読み込みます。.platformio/packagesや.platformio/platformsのファイルを上書きする必要はありません。

別のプロジェクトでも同じ定義を使えます。boardsとvariantsをコピーし、次のplatformio.iniの設定を適用してください。

2. 接続するシリアルポートを調べる

リーフの組み立て

USBケーブルを外した状態で、STM32 MCUリーフとUSBリーフを組み立てます。構成は接続例を参照してください。
パソコンへの接続

USBリーフとパソコンをUSBケーブルで接続します。
シリアルポート一覧の表示

PlatformIO Core CLIで、次のコマンドを実行します。

pio device list

表示されたポート名を、次の書き込み設定に使います。複数ある場合は、USBケーブルの抜き差しで増減するポートが接続先です。

OS	ポート名の例
Windows	`COM3`
macOS	`/dev/cu.usbserial-XXXXXXXX`
Linux	`/dev/ttyUSB0`

ポートが表示されない場合は、ケーブルのデータ通信対応とUSBリーフの接続状態を確認してください。ドライバーの確認手順は、よくある質問にあります。

Linuxでは、ポートへのアクセス権も必要です。設定方法はPlatformIO公式の案内を参照してください。

3. platformio.iniを設定する

次は、WindowsでポートがCOM3の場合の設定例です。platformio.iniに貼り付け、upload_portと書き込みツールのパスを自分の環境に合わせて変更してください。

[env:leafony_ap03]
platform = ststm32
board = LEAFONY_AP03
framework = arduino
board_build.variants_dir = variants

upload_protocol = custom
upload_port = COM3
upload_command = "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_Programmer_CLI.exe" -c port=$UPLOAD_PORT br=115200 -w "$SOURCE" 0x08000000 -v

monitor_port = ${this.upload_port}
monitor_speed = 115200

macOSでは、上のupload_portとupload_commandの2行を次のように置き換えます。ポート名のXXXXXXXXは実際の値に変更します。

upload_port = /dev/cu.usbserial-XXXXXXXX
upload_command = "/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/Resources/bin/STM32_Programmer_CLI" -c port=$UPLOAD_PORT br=115200 -w "$SOURCE" 0x08000000 -v

Linuxでは、インストール先の絶対パスと実際のポート名を指定します。次はユーザー名がuserの場合の例です。

upload_port = /dev/ttyUSB0
upload_command = "/home/user/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_Programmer.sh" -c port=$UPLOAD_PORT br=115200 -w "$SOURCE" 0x08000000 -v

設定の意味は次のとおりです。

設定	意味
`[env:leafony_ap03]`	ビルド環境名（生成ファイルの保存先にも使用）
`board = LEAFONY_AP03`	ボード定義`boards/LEAFONY_AP03.json`の選択
`board_build.variants_dir`	ピン配置などの読み込み元フォルダー
`upload_protocol = custom`	`upload_command`による書き込み方法の指定
`$UPLOAD_PORT`	PlatformIOがポート名に置き換える変数
`$SOURCE`	PlatformIOがファームウェアのパスに置き換える変数
`0x08000000`	フラッシュメモリーの書き込み開始アドレス
`-v`	書き込み内容を検証するオプション
`monitor_port`	シリアルモニターの接続先（例では書き込みと同じポート）
`monitor_speed`	シリアルモニターの通信速度（例では115200 bps）

$UPLOAD_PORTと$SOURCEは、設定例のまま記述してください。PlatformIOが書き込み時に置き換えます。monitor_speedは、プログラムのSerial.begin()と同じ値にします。

コマンドの仕様はPlatformIOのupload_commandとSTM32CubeProgrammerのCLIマニュアルを参照してください。

4. プログラムを作成する

src/main.cppに次のコードを記述し、保存します。

#include <Arduino.h>

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

void loop() {
  Serial.println("Hello World");
  delay(1000);
}

5. ビルドする

VS Code左側のPlatformIO → PROJECT TASKS → leafony_ap03 → General → Buildを実行します。プロジェクトが認識されない場合は、platformio.iniのあるフォルダーを開き直してください。

ターミナルを使う場合は、プロジェクトのフォルダーで次を実行します。

pio run -e leafony_ap03

初回のビルドには、数分かかることがあります。コンパイラーやArduinoフレームワークなどをダウンロードするためです。

ビルド完了の目印は、ログ末尾のSUCCESSと、次のファイルの生成です。

.pio/build/leafony_ap03/firmware.bin

複数のプロジェクトやビルド環境を開いている場合は、実行対象がSTM32_Hello_World_Pjtのleafony_ap03であることを確認してください。

6. STM32 MCUに書き込む

シリアルポートの解放

シリアルモニターやTeleplotなど、同じポートを使うアプリを閉じます。PlatformIOのシリアルモニターは、そのターミナルでCtrl+Cを押すと終了します。
プログラムスイッチの切り替え

STM32 MCUリーフのスイッチをProgram側に切り替え、LEDの点灯を確認します。
書き込みモードへの移行

リセットスイッチを押します。 Program側への切り替え後にリセットすると、書き込みモードに入ります。
プログラムの書き込み

PROJECT TASKS → leafony_ap03 → General → Uploadを実行します。

ターミナルから書き込む場合は、手順4で次のコマンドを実行します。

pio run -e leafony_ap03 -t upload

STM32 MCUリーフのプログラムスイッチ、リセットスイッチ、LEDの位置

書き込みの成否は、STM32CubeProgrammerのログで確認します。ポートへの接続、書き込み、検証のすべてが成功していることを確かめてください。

検証成功時のメッセージの例を示します。表記はツールのバージョンによって異なります。

Download verified successfully

SUCCESSが表示されても、タイムアウトや検証エラーがある場合は書き込みをやり直します。ポートを使うアプリを閉じ、Program側でリセットしてから再度Uploadしてください。

7. Hello Worldの表示を確認する

プログラムスイッチの切り替え

書き込み完了後、スイッチをRun側に戻し、LEDの消灯を確認します。
プログラムの起動

リセットスイッチを押します。
シリアルモニターの起動

PROJECT TASKS → leafony_ap03 → General → Monitorを実行します。

ターミナルからシリアルモニターを開く場合は、手順3で次のコマンドを実行します。

pio device monitor -e leafony_ap03

次のように1秒ごとに表示されれば完了です。

Hello World
Hello World
Hello World

既存のサンプルを使う

LeafonyのPlatformIOサンプル集から、使いたいサンプルを入手します。VS Codeでは、リポジトリ全体ではなく、各サンプルのplatformio.iniがあるフォルダーを開いてください。

サンプルにも、クイックスタートと同じボード定義と書き込み設定が必要です。例えばSTM32_Hello_World_Pjtを使う場合は、プロジェクト内にboardsとvariantsを配置し、platformio.iniをこのページの設定に合わせます。既存のlib_depsやbuild_flagsにはサンプル固有の設定があるため、内容を確認して引き継いでください。

upload_commandが古いArduino15/.../STM32Tools/1.4.0/...を参照している場合は、現在インストールしているSTM32CubeProgrammerを直接呼び出す設定に置き換えます。

既存プロジェクトのST STM32やライブラリは、次のコマンドで更新できます。実行前にライブラリの対応条件を確認し、platformio.iniのバージョン指定を調整してください。その後、プロジェクトのフォルダーでコマンドを実行します。

pio pkg update

依存パッケージは、platformio.iniで指定したバージョンの範囲内で更新されます。詳しくはpio pkg updateの公式説明を参照してください。

ライブラリ

追加のライブラリは、platformio.iniのlib_depsに記述します。使用する[env:...]セクション内に、必要なライブラリを指定してください。すでにlib_depsがある場合は、その一覧に追記します。

次は指定方法の例です。Hello Worldの例には追加ライブラリは不要です。

lib_deps =
    adafruit/Adafruit Unified Sensor
    adafruit/Adafruit BusIO
    https://github.com/Leafony/TBGLib

GitHubのURLからライブラリをインストールするには、Gitも必要です。Gitのインストール後にVS Codeを再起動し、ターミナルでgit --versionを実行できることを確認してください。

以下は主なライブラリの参照先です。使用するリーフ・機能に必要なものだけ追加してください。

リーフ・機能	ライブラリ
BLE	TBGLib
4-Sensors	Adafruit Unified Sensor、Adafruit BusIO、HTS221、ClosedCube OPT3001、Adafruit LIS3DH
LCD	ST7032
RTC & microSDのRTC	RTClib
STM32内蔵RTC・低消費電力	STM32duino RTC、STM32duino Low Power
LTE-M	LteLeafV4
Wi-Fi	WiFi101Leafony
LoRa・署名通信	arduino-LoRa、arduino-tca9536、SparkFun ATECCX08a

古いサンプルのライブラリ指定について

ライブラリは、使用するArduinoフレームワークに対応したバージョンを選びます。ST STM32 20.0.0では、STM32 Arduino Coreが3.0.0に更新されました。

STM32RTCの要件とSTM32LowPowerの要件に従い、Core 3.xでは両ライブラリの2.xを使います。

; STM32 Arduino Core 3.xでRTC・低消費電力機能を使う場合
lib_deps =
    stm32duino/STM32duino RTC@^2.0.0
    stm32duino/STM32duino Low Power@^2.0.0

Core 2.xを使う既存プロジェクトでは、両ライブラリの1.xを使います。古いサンプルに@1.2.0などの指定がある場合も、各ライブラリのREADMEでCoreとの対応条件を確認してください。

使用中のCoreのバージョンは、ビルドログのPACKAGESにあるframework-arduinoststm32の行で確認できます。

AVR用のMsTimer2はSTM32 MCUでは使いません。STM32でタイマ割り込みを使う場合は、HardwareTimerを参照してください。

CPUの周波数を16MHzに変更する

Leafony配布のボード定義を使うと、CPUは通常80MHzで動作します。16MHzに変更する手順は次のとおりです。

クロック設定用ファイルの追加

Leafonyのleafony_tools .cppをダウンロードし、プロジェクトのsrc/leafony_tools.cppとして保存します。配布元のファイル名には拡張子の前に空白があるため、保存時に空白を取り除いてください。
ビルドフラグの追加

platformio.iniの使用する[env:...]セクションに次を追加します。すでにbuild_flagsがある場合は、その一覧に-D CPUCLOCK_LOWを追加します。
```
build_flags =
    -D CPUCLOCK_LOW
```
確認用プログラムの書き込みと周波数の確認

src/main.cppを次の内容に変更し、再度ビルド・書き込みを行います。書き込み後はプログラムスイッチをRun側に戻し、リセットします。シリアルモニターに16000000と表示されれば、16MHzへの変更は完了です。
```
#include <Arduino.h>

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

void loop() {
  Serial.println(HAL_RCC_GetHCLKFreq());
  delay(1000);
}
```

80MHzに戻す場合は、-D CPUCLOCK_LOWを削除して再ビルド・書き込みします。board_build.f_cpuだけを変更しても、実際のクロック設定は切り替わりません。

シリアルプロッター

シリアル出力の数値は、VS Code拡張機能のTeleplot for VSCodeでグラフ表示できます。次の例では、起動後の経過秒数を表示します。

Teleplotのインストール

VS Codeの拡張機能でTeleplotを検索し、上記リンクの拡張機能をインストールします。
グラフ表示用プログラムの書き込みと起動

src/main.cppを次のコードに変更し、ビルド・書き込みを行います。書き込み後はプログラムスイッチをRun側に戻し、リセットします。
```
#include <Arduino.h>

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

void loop() {
  Serial.print(">seconds:");
  Serial.println(millis() / 1000.0f);
  delay(100);
}
```
Teleplotの起動

PlatformIOのシリアルモニターを閉じ、VS Codeのコマンドパレットからteleplot: Start teleplot sessionを実行します。
シリアルポートへの接続とグラフの確認

Teleplotの左上で接続するシリアルポートとボーレート115200を選択し、Openで接続します。secondsの値がグラフに表示されることを確認してください。

Teleplotは、>変数名:数値に改行を付けたシリアル出力をグラフ化します。上のコードではSerial.println()が改行を付けるため、別途\nを書く必要はありません。

次にプログラムを書き込む前には、Teleplotの接続を閉じてください。

波形を表示する例はSTM32_Teleplot_Example_1も参照できます。

Arduino IDEのスケッチを移すときの注意

PlatformIOでsrc/main.cppを使う場合は、通常のC++の規則に従って記述します。

ファイル先頭への#include <Arduino.h>の追加
呼び出し前の自作関数の定義、またはプロトタイプ宣言の追加
スケッチに必要なライブラリのlib_depsへの追加

例えば、関数をsetup()の後に定義したい場合は、次のように宣言します。

#include <Arduino.h>

void printMessage();

void setup() {
  Serial.begin(115200);
  printMessage();
}

void loop() {
}

void printMessage() {
  Serial.println("Hello World");
}

STM32CubeProgrammerの画面から書き込む

ビルドしたファイルは、STM32CubeProgrammerのGUIからも書き込めます。

ビルドと生成ファイルの確認

プロジェクトをビルドし、.pio/build/leafony_ap03/firmware.binが生成されていることを確認します。[env:...]の名前を変更した場合は、パス中のleafony_ap03もその名前になります。
書き込みモードへの切り替え

シリアルポートを使っているアプリを閉じます。STM32 MCUリーフのプログラムスイッチをProgram側に切り替え、リセットします。
UART接続の設定

STM32CubeProgrammerを起動し、次の設定でConnectをクリックします。

項目設定値
接続方式 UART
ポート STM32 MCUリーフを接続したシリアルポート
ボーレート 115200
Parity Even
Data bits 8
Stop bits 1
Flow control OFF
書き込みファイルと開始アドレスの指定

Erasing & Programmingを開き、File pathに手順1で生成したfirmware.bin、開始アドレスに0x08000000を指定します。
書き込みと検証結果の確認

Verify programmingを有効にしてStart Programmingをクリックします。書き込み後に検証が成功したことを確認してください。
プログラムの起動と動作確認

Disconnectで切断し、プログラムスイッチをRun側に戻してリセットします。PlatformIOのシリアルモニターで動作を確認します。

項目	設定値
接続方式	UART
ポート	STM32 MCUリーフを接続したシリアルポート
ボーレート	`115200`
Parity	Even
Data bits	8
Stop bits	1
Flow control	OFF

困ったときには

症状	確認すること
`UnknownBoard`やvariantのファイルが見つからない	`boards/LEAFONY_AP03.json`と`variants/STM32L4xx/LEAFONY_AP03/`の配置、ファイル名の大文字・小文字、`board_build.variants_dir`の確認
`pio`コマンドが見つからない	PlatformIO Core CLIからのターミナルの開き直し
書き込みツールが見つからない	`upload_command`に指定したインストール先の確認、空白を含む実行ファイルのパスを囲む引用符の確認
ポートを開けない	`upload_port`の確認、同じポートを使うシリアルモニター・Teleplot・STM32CubeProgrammerのGUIなどの接続終了、Linuxではポートへのアクセス権の確認
接続時にタイムアウトする	Program側への切り替えとリセット後のUpload再実行、改善しない場合はUSBケーブルの再接続とポート名の再確認
書き込み後に何も表示されない	Run側への切り替え後のリセット、`monitor_port`の確認
表示が文字化けする	`monitor_speed`と`Serial.begin()`の通信速度の統一（このページの例は115200）