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 の上ではほぼ共通に書けます。

警告XIAO ESP32C3 はアンテナを付ける

Seeed Studio XIAO ESP32C3 は、基板上にアンテナがなく、付属の 外付けアンテナ(U.FL コネクタ) を使う設計です。付けずに動かすと、数十 cm 離れただけでスキャンに出てこない・接続が切れる、といった症状になります。

1.2 ESP-IDF とは

ESP-IDF (Espressif IoT Development Framework) は、Espressif の公式開発フレームワークです。Arduino の ESP32 コアも、内部では ESP-IDF を使っています。

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

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 の拡張機能を使う(おすすめ)

  1. VS Code をインストールする
  2. 拡張機能 ESP-IDF(Espressif Systems 製)をインストールする
  3. コマンドパレット(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 --version
ヒントどちらでも中身は同じ

VS 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 を返す