flowchart TB APP["アプリケーション(このハンズオンで書く main/ のコード)"] NIM["NimBLE ホスト(BLE のプロトコルスタック)"] IDF["ESP-IDF コンポーネント<br/>(nvs_flash, esp_timer, esp_log ...)"] RTOS["FreeRTOS(タスク・キュー・タイマー)"] CTRL["BLE コントローラ(Espressif 提供のバイナリ)"] HW["ESP32-C3 ハードウェア(無線回路)"] APP --> NIM --> CTRL --> HW APP --> IDF --> RTOS --> HW NIM --> RTOS
1 開発環境と ESP-IDF の基本
1.1 ESP32-C3
ESP32-C3 は Espressif Systems の Wi-Fi + BLE 対応マイコンです。
| 項目 | 内容 |
|---|---|
| CPU | 32 bit RISC-V シングルコア、最大 160 MHz |
| メモリ | SRAM 400 KB、Flash はモジュール・ボードによる(XIAO ESP32C3 は 4 MB) |
| 無線 | Wi-Fi 4 (2.4 GHz)、Bluetooth 5 (LE)。Bluetooth Classic には非対応 |
| USB | USB Serial/JTAG を内蔵(USB-UART 変換チップなしで書き込み・ログ・デバッグができる) |
同じ ESP32 の名前でも、初代 ESP32 は Xtensa コアで Bluetooth Classic も使えますが、C3 は RISC-V コアで BLE 専用です。BLE のコードは ESP-IDF の上ではほぼ共通に書けます。
Seeed Studio XIAO ESP32C3 は、基板上にアンテナがなく、付属の 外付けアンテナ(U.FL コネクタ) を使う設計です。付けずに動かすと、数十 cm 離れただけでスキャンに出てこない・接続が切れる、といった症状になります。
1.2 ESP-IDF とは
ESP-IDF (Espressif IoT Development Framework) は、Espressif の公式開発フレームワークです。Arduino の ESP32 コアも、内部では ESP-IDF を使っています。
Arduino との大きな違い:
| Arduino | ESP-IDF | |
|---|---|---|
| 入口 | setup() と loop() |
app_main()(戻ってもよい。戻ったあともほかのタスクは動き続ける) |
| ビルド | Arduino IDE / PlatformIO | CMake + Ninja(idf.py コマンドが包んでいる) |
| 設定 | ほぼなし | sdkconfig(Kconfig)。BLE を使うかどうかもここで決める |
| 部品 | ライブラリ | コンポーネント(components/ や main/ の単位で CMake に登録) |
| OS | 隠れている | FreeRTOS が前提。タスク・キュー・タイマーを直接使う |
1.3 ESP-IDF のインストール
このハンズオンは ESP-IDF v6.0.1 で動作を確認しています。インストール方法は 2 通りあります。
1.3.1 VS Code の拡張機能を使う(おすすめ)
- VS Code をインストールする
- 拡張機能 ESP-IDF(Espressif Systems 製)をインストールする
- コマンドパレット(
Cmd/Ctrl + Shift + P)から ESP-IDF: Configure ESP-IDF Extension を実行し、バージョン v6.0.1 を選んでインストールする(ESP-IDF 本体、ツールチェーン、Python 環境がまとめて入る。数 GB・数十分かかる)
インストールが終わると、VS Code の下のステータスバーに ターゲット(esp32c3)・ポート・ビルド・書き込み・モニタ のボタンが並びます。
1.3.2 コマンドラインで使う
ESP-IDF Installation Manager (EIM) などでインストールすると、~/.espressif/ の下に ESP-IDF 本体とツールが入ります。ターミナルを開くたびに、環境を有効にするスクリプトを読み込みます。
# macOS / Linux (bash / zsh)。パスはインストール先に合わせる
source ~/.espressif/tools/activate_idf_v6.0.1.sh
# 確認
idf.py --versionVS Code のボタンも、裏では idf.py を呼んでいます。以降の説明は idf.py のコマンドで書きますが、VS Code のボタンに読み替えて構いません。
1.4 サンプルの入手
firmware.zip を展開すると、次のフォルダが入っています。
firmware/
├── step1_hello/ 第 1 章 ログを出すだけ
├── step2_advertise/ 第 5 章 アドバタイズ
├── step3_notify/ 第 6 章 GATT サービスと Notify
├── step4_command/ 第 7 章 コマンドと応答
├── step5_pairing/ 第 9 章 パスキーペアリング
└── step6_event_driven/ 第 10 章 イベント駆動構成(完成形)
各ステップは 独立した ESP-IDF プロジェクト です。VS Code では、ステップのフォルダ(例: step1_hello)を フォルダとして開いて ください。
1.5 プロジェクトの構成
Step 1 を例に、ESP-IDF プロジェクトの最小構成を見てみましょう。
step1_hello/
├── CMakeLists.txt プロジェクト全体の定義
├── sdkconfig.defaults 設定の初期値(自分で書く)
└── main/
├── CMakeLists.txt main コンポーネントの定義
└── main.c app_main() を書く
ビルドすると、次のものが自動で作られます(どちらも配布物には含めていません)。
build/— ビルド成果物sdkconfig— 全設定項目の 実際の値。sdkconfig.defaultsと既定値から生成される
1.5.1 トップの CMakeLists.txt
# ESP-IDF プロジェクトの定型文(この 3 行の順番は変えない)
cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(step1_hello)ESP-IDF のプロジェクトはこの 3 行が定型です。project() の名前が、出力されるファイル名(build/step1_hello.bin)になります。
1.5.2 main/CMakeLists.txt
idf_component_register(SRCS "main.c"
INCLUDE_DIRS ".")idf_component_register() で、このコンポーネントのソースファイル と ヘッダの検索パス を登録します。BLE を使う Step 2 以降では、次のように 依存するコンポーネント も書きます。
idf_component_register(SRCS "main.c"
INCLUDE_DIRS "."
PRIV_REQUIRES bt nvs_flash esp_timer)PRIV_REQUIRES に書いたコンポーネントのヘッダだけが #include できるようになります(bt = Bluetooth、nvs_flash = 不揮発ストレージ、esp_timer = 高分解能タイマー)。
1.5.3 sdkconfig.defaults
CONFIG_IDF_TARGET="esp32c3"Step 1 では、ターゲット(チップの種類)だけを指定しています。BLE を使うステップでは、ここに Bluetooth を有効にする設定 が加わります(第 4 章)。
1.6 Step 1:Hello ESP-IDF
/*
* Step 1: Hello ESP-IDF
*
* - app_main() から始まる
* - ESP_LOGI でシリアルにログを出す
* - vTaskDelay で 1 秒待つ(待っている間 CPU は他のタスクに譲られる)
*/
#include <stdint.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_chip_info.h"
#define TAG "STEP1"
void app_main(void)
{
esp_chip_info_t chip;
esp_chip_info(&chip);
ESP_LOGI(TAG, "Hello ESP-IDF! cores=%d revision=%d", chip.cores, chip.revision);
uint32_t count = 0;
while (1) {
ESP_LOGI(TAG, "count = %lu", (unsigned long)count);
count++;
// 1000 ms 待つ。待たずに回り続けるとタスクウォッチドッグが警告を出す
vTaskDelay(pdMS_TO_TICKS(1000));
}
}app_main()は、ESP-IDF が起動処理を終えたあと main タスク の中で呼ばれるESP_LOGI(TAG, ...)はログ出力。Iは Info で、ほかにESP_LOGE(Error)、ESP_LOGW(Warning)、ESP_LOGD(Debug)などがある。時刻とタグが自動で付くvTaskDelay()は FreeRTOS の「このタスクを指定時間休ませる」関数。pdMS_TO_TICKS(1000)で 1000 ms をティック数に変換している
while (1) の中で待たないと
FreeRTOS には、各タスクが CPU を独占していないかを見張る タスクウォッチドッグ があります。vTaskDelay() を入れずに無限ループすると、アイドルタスクが動けなくなり、数秒後に task_wdt: Task watchdog got triggered という警告が出ます。Arduino の loop() と違い、待つときは OS に CPU を返す のが基本です。
1.6.1 ビルド・書き込み・モニタ
cd firmware/step1_hello
idf.py set-target esp32c3 # 初回だけ。sdkconfig が作られる
idf.py build # ビルド
idf.py -p PORT flash monitor # 書き込んでからシリアルモニタを開くPORT は、macOS なら /dev/tty.usbmodem*、Linux なら /dev/ttyACM0、Windows なら COM3 のような名前です。モニタを抜けるときは Ctrl + ] を押します。
次のように 1 秒ごとにログが出れば成功です。
I (285) STEP1: Hello ESP-IDF! cores=1 revision=4
I (285) STEP1: count = 0
I (1285) STEP1: count = 1
I (2285) STEP1: count = 2
かっこの中の数字は、起動からの経過時間 [ms] です(数値やリビジョンはボードによって異なります)。
ESP32-C3 は通常、USB Serial/JTAG 経由で自動的にダウンロードモードに入ります。それでも失敗するときは、BOOT ボタンを押したまま RESET ボタンを押して離し、そのあと BOOT を離してから、もう一度書き込みます。書き込み後は RESET ボタンで通常起動に戻します。
1.7 よく使う idf.py コマンド
| コマンド | 内容 |
|---|---|
idf.py set-target esp32c3 |
ターゲットを設定(sdkconfig と build/ を作り直す) |
idf.py build |
ビルド |
idf.py -p PORT flash |
書き込み |
idf.py -p PORT monitor |
シリアルモニタ(Ctrl + ] で終了) |
idf.py menuconfig |
設定画面(sdkconfig を対話的に編集する) |
idf.py fullclean |
build/ を消す |
idf.py -p PORT erase-flash |
Flash 全体を消去(NVS に保存したボンディング情報も消える) |
idf.py size |
メモリ使用量の概要 |
- ESP-IDF の入口は
app_main()。裏では FreeRTOS が動いている - 設定は
sdkconfig。自分で書くのはsdkconfig.defaults - コンポーネントは
idf_component_register()で登録し、使うものはPRIV_REQUIRESに書く - ループの中では
vTaskDelay()などで 待って CPU を返す