avr/interrupt.h: No such file でビルド失敗（VarSpeedServo が ESP32 で動かない）

初出: 2026-05-19

症状

pio run で以下のエラー：

.pio/libdeps/m5stack-cores3/VarSpeedServo/VarSpeedServo.cpp:71:10:
  fatal error: avr/interrupt.h: No such file or directory
 #include <avr/interrupt.h>
          ^~~~~~~~~~~~~~~~~
compilation terminated.

原因（噛み砕き）

Arduino の世界には2つの大きな系統がある:

1. AVR系（Arduino Uno / Nano など）— Atmel 社の 8bit マイコン
2. ESP32系（M5Stack / スタックちゃん）— Espressif 社の 32bit マイコン

両方とも「Arduino っぽく書ける」けど、CPUの命令も周辺機能の制御方法もまったく違う。

サーボを動かすライブラリ VarSpeedServo は、AVR系の タイマ割り込み という機能（avr/interrupt.h ヘッダ）を直接叩く実装になっている。ESP32 にはその AVR 専用ヘッダ自体が存在しないので、#include <avr/interrupt.h> の時点でファイルが無くてコンパイルが止まる。

「Arduino 互換」と書いてあっても、ハードウェア依存のライブラリは移植が必要。

対処

ESP32 向けに作られた別のサーボライブラリに差し替える。

候補1: madhephaestus/ESP32Servo（推奨）

• 一番よく使われている。ESP32 の LEDC（PWM）を内部で使う
• API は Arduino Servo にほぼ互換

# platformio.ini
lib_deps =
  madhephaestus/ESP32Servo@^3.0.6

#include <ESP32Servo.h>

Servo head;
void setup() {
  head.attach(13);   // GPIO 13 にサーボを接続
  head.write(90);    // 90度に向ける
}

候補2: ArminJo/ServoEasing

• 「ゆっくり動かす」「加減速をつける」みたいなイージング機能つき
• スタックちゃんっぽい「自然な首振り」を作るならこっち

lib_deps =
  ArminJo/ServoEasing@^3.4.0

#include <ServoEasing.hpp>

ServoEasing head;
void setup() {
  head.attach(13);
  head.setEasingType(EASE_QUADRATIC_IN_OUT);
  head.startEaseTo(45, 30);  // 45度まで秒速30度で動かす
}

当面の対応（このリポジトリでやっていること）

サーボはまだ実装段階ではないので、platformio.ini から VarSpeedServo を コメントアウト して TODO を残してある：

lib_deps =
  m5stack/M5Unified@^0.2.5
  m5stack/M5GFX@^0.2.5
  meganetaaan/M5Stack-Avatar@^0.10.0
  ; TODO: ESP32 対応のサーボライブラリに差し替え
  ; 候補: madhephaestus/ESP32Servo, ArminJo/ServoEasing

Issue #5 / #8 でサーボ駆動を実装するタイミングで、どちらを採用するか決める。

学び

• Arduino ライブラリ選びは「対応プラットフォーム」を必ず確認する
• PlatformIO のレジストリだと右側に対応プラットフォームのバッジが出る
• GitHub の README に Tested on: Arduino Uno としか書かれていない古いライブラリは ESP32 で動かないことが多い
• 困ったら GitHub Issues で ESP32 を検索してみる（先人が同じ問題で躓いてる）