mcpField
E
esp32-debugging

esp32-debugging

github.com/laurigates開発7310 回インストール今日更新
リポジトリ

esp32-debugging について

esp32-debuggingは、ESP-IDFプロジェクト向けのデバッグスキルです。ビルドエラー、実行時クラッシュ、メモリ問題、周辺機器の通信障害を調べる手順と、ビルドやモニターのコマンドを示します。

主な機能

  1. 01ビルドエラーと実行時クラッシュの分析
  2. 02メモリとスタック問題の調査
  3. 03I2C、SPI、UART障害の診断
  4. 04ビルドとシリアルモニターのコマンド
  5. 05ESP-IDF設定項目の提示

活用シーン

  1. 01ESP-IDFのビルド失敗の調査
  2. 02Guru Meditation Errorの解釈
  3. 03スタックやメモリのクラッシュ調査
  4. 04I2Cやシリアル通信問題の診断

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/laurigates/mcu-tinkering-lab --skill esp32-debugging

インストール後、Claude Code で/esp32-debuggingを入力して読み込まれたか確認します。

詳細

ESP32 ファームウェアのデバッグガイド

このスキルを使用するタイミング

次の場合にこのスキルを適用します。

  • ESP-IDF プロジェクトでコンパイルエラーが発生した
  • 実行時にパニックが発生した、または「Guru Meditation Error」メッセージが表示された
  • メモリ関連のクラッシュやスタックオーバーフローが発生した
  • I2C／SPI／UART の通信に失敗した
  • シリアルモニターの出力を解釈する必要がある

$ARGUMENTS には、エラーメッセージや問題の背景情報が含まれる場合があります。

デバッグの手順

まず状況を確認する

$ARGUMENTS からエラーの内容がわからない場合は、次の情報をユーザーに尋ねます。

  1. エラーメッセージまたはパニック出力の全体
  2. ビルドしているプロジェクト
  3. 最近のコード変更
1. コンパイルエラーの分析

エラーを取得するため、クリーンビルドを実行します。

just <project>::build 2>&1 | tail -100

インクルードの不足

fatal error: driver/gpio.h: No such file or directory

修正方法：main/CMakeLists.txt の REQUIRES にコンポーネントを追加します。

idf_component_register(
    SRCS "main.c"
    REQUIRES driver
)

未定義の参照

undefined reference to 'some_function'

修正方法：関数を含むコンポーネントが REQUIRES または PRIV_REQUIRES に含まれていることを確認します。

型エラー 関数の宣言と実装の間で型が一致していない箇所を確認します。

2. 実行時パニックの分析

Guru Meditation Error のパターン

エラー原因修正方法
StoreProhibited無効なメモリへの書き込みポインターの初期化を確認します
LoadProhibited無効なメモリからの読み取りnull ポインターを確認します
InstrFetchProhibited関数ポインターの破損コールバックの割り当てを確認します
IntegerDivideByZeroゼロ除算ゼロチェックを追加します
Double exception、バックトレースが CORRUPTED、A0 が認識可能な定数（例：0x10000000）呼び出し元のフレームに向かってスタックバッファーがオーバーフローしている状態。VLA または範囲外のインデックスでアクセスされたローカル配列が原因です。カナリアは下端のみを監視します最後のログ行からパニックまでのコードを確認し、直前に呼び出されたドライバーで A0 の最上位バイトを調べます。.claude/rules/gated-init-paths.md を参照してください

スタックオーバーフロー

Guru Meditation Error: Core 0 panic'ed (Stack overflow)

修正方法：タスク作成時にスタックサイズを増やします。

xTaskCreatePinnedToCore(task_fn, "name", 4096, NULL, 5, NULL, 0);
//                                        ^^^^ increase this

スタック破壊

Stack smashing detected

修正方法：ローカルバッファーのオーバーフローです。配列の境界と文字列操作を確認します。

このメッセージを表示するには、CONFIG_COMPILER_STACK_CHECK_MODE_* を有効にする必要があります。無効の場合（robocar-unified のデフォルト設定）、同じオーバーフローでも、代わりにバックトレースが破損した二重例外として報告されます。上記の表を参照してください。変更を加えていないファイルを -fsanitize=address を指定してコンパイルするホストテストを作成し、修正を固定します（packages/robocar/unified/test/test_pca9685_multi.c をテンプレートとして使用します）。

3. メモリのデバッグ

ヒープ使用量を確認する

ESP_LOGI(TAG, "Free heap: %lu", esp_get_free_heap_size());
ESP_LOGI(TAG, "Min free heap: %lu", esp_get_minimum_free_heap_size());

よくあるメモリの問題

  • メモリリーク：malloc() の後に free() が呼び出されていない
  • 二重解放：同じメモリを二度解放している
  • 解放後使用：解放済みのメモリにアクセスしている
4. 通信のデバッグ

I2C の問題

E (1234) i2c: i2c_master_cmd_begin(xxx): I2C_NUM error

チェックリスト：

  • I2C アドレスの形式（7 ビットと 8 ビット）を確認します
  • SDA／SCL の GPIO ピンを確認します
  • プルアップ抵抗（通常 4.7K）があることを確認します
  • クロック周波数の互換性を確認します

シリアル／UART の問題

  • ボーレートが一致していない
  • TX／RX が逆になっている
  • グラウンド接続がない

デュアルコントローラーの同期（I2C）

  • 両方のコントローラーが動作していることを確認します
  • I2C アドレスが一致していることを確認します
  • GPIO ピンの設定を確認します
5. デバッグ用のビルドコマンド
# Clean build to eliminate stale objects
just <project>::clean && just <project>::build

# Start serial monitor
just <project>::monitor PORT=/dev/cu.usbserial-0001
6. 便利な ESP-IDF 設定オプション

​sdkconfig.defaults または menuconfig で有効にします。

  • CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT — 再起動前にパニック情報を出力します
  • CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK — スタックオーバーフローを早期に検出します
  • CONFIG_HEAP_POISONING_COMPREHENSIVE — ヒープの破損を検出します

よくある修正方法

症状修正方法
スタックオーバーフローxTaskCreate のタスクスタックサイズを増やします
メモリリークfree() の呼び出し漏れを確認します
I2C のタイムアウト接続、プルアップ、アドレスを確認します
起動時のクラッシュCONFIG_ESP_MAIN_TASK_STACK_SIZE を 8192 以上に増やします

コメント

Markdown 対応