Arduino MIDI 琶音器：模块化固件 + 欧几里得节奏 + 硬件可扩展设计

项目演进

• v1 (2019.03)：Arduino Nano 单文件固件，7 滑锅 + 7 按钮控制调性、和弦、琶音型、速度、八度等，DIN-5 MIDI 输出驱动 Korg Volca Keys。
• v2 (2019.06)：重构为**模块化 C++ 库**（arpeggio2），剥离硬件抽象层，可移植至 Teensy、ESP32、STM32 甚至 PC 模拟器；新增**欧几里得节奏生成器**，支持多轨复合节奏。
• 硬件兼容性保持：原 Fritzing 原理图（arpeggiator_LICtzK2a2Q.fzz）仍适用于新固件。

硬件架构

音乐理论速查（固件内置）

• **12 平均律音名**：C C# D D# E F F# G G# A A# B（MIDI note 0~11）。
• **七音调式模式**：Ionian(大调)、Dorian、Phrygian、Lydian、Mixolydian、Aeolian(小调)、Locrian —— 由全/半音步长模板生成。
• **三和弦构成**：级数 1-3-5（大三和弦）/ 1-♭3-5（小三和弦）/ 1-♭3-♭5（减三和弦）等，按调式自动生成七个级数和弦。
• **琶音型**：上行、下行、上下行、随机、欧几里得分布（如 E(3,8) = ●○●○●○○○）。
• **同步模式**：INT_SYNC（内部 BPM 滑锅）或 EXT_SYNC（Volca SYNC IN/OUT 5V 脉冲，上升沿触发步进）。

模块化代码结构（arpeggio2 库核心类）

// 核心数据结构
struct Note { uint8_t pitch; uint8_t vel; uint16_t dur; }; // 音高、力度、时长(tick)
class Scale   { /* 根音+模式 → 音级数组 */ };
class Chord   { /* 级数+调式 → 音符集合 */ };
class Arpeggiator {
  Scale scale; Chord chord; EuclidRhythm rhythm;
  uint8_t style, steps, octaveRoot, octaveChord;
  void setParams(...);           // 映射电位器值
  void triggerChord(uint8_t deg); // 按钮回调
  Note nextNote();               // 每 tick 调用，返回下一音符或休止
};

// 硬件抽象层 (HAL) 示例
class Hal {
  virtual uint16_t readPot(uint8_t ch) = 0;
  virtual bool     readBtn(uint8_t ch) = 0;
  virtual void     midiSend(uint8_t status, uint8_t d1, uint8_t d2) = 0;
  virtual void     ledSet(uint8_t idx, bool on) = 0;
  virtual uint32_t millis() = 0;
};
// Arduino 实现见 hal_arduino.cpp

欧几里得节奏算法（Bjorklund 算法）

将 k 个 onset 尽可能均匀分布在 n 个步长中，生成传统非洲/巴尔干/电子音乐常用节奏型。

std::vector euclid(int n, int k) { // n=步长, k=onset数
  std::vector> seq;
  for (int i=0;i flat;
  for (auto &v: seq) flat.insert(flat.end(), v.begin(), v.end());
  return flat; // 长度 n, 含 k 个 true
}

固件移植指南

1. 实现 Hal 纯虚类（读电位器、读按钮、发 MIDI、驱动 LED、取毫秒数）。
2. 实例化 Arpeggiator，主循环以 1 ms tick 调用 nextNote()，非零则 midiSend(0x90, note.pitch, note.vel)；note.dur 到期后发 0x80 Note Off。
3. 电位器平滑：val = val*0.9 + analogRead()*0.1 防抖。
4. 按钮边沿检测：上升沿触发 triggerChord()。

实战调试技巧

• MIDI Monitor（macOS）或 MIDI-OX（Windows）监控输出消息。
• Volca Keys GLOBAL → MIDI CH 设为 1，SYNC 选 AUTO。
• 电位器行程映射：map(analog, 0, 1023, min, max)，建议加死区 ±5。
• 欧几里得参数（n, k）映射到第 6、7 个电位器，实时重算节奏序列。

资源链接

• GitHub 源码（含模块化库、HAL 示例、Arduino 完整固件）：raszhivin/arpeggio2
• Fritzing 原理图与 PCB：项目附件 arpeggiator_LICtzK2a2Q.fzz
• 在线琶音器原型（Web Audio API）：Web Demo

一句话总结：从单片机单文件到跨平台 C++ 库，Arduino MIDI 琶音器 v2 以模块化架构支撑调式、和弦、欧几里得节奏、内外同步，是电子音乐控制器开发的优秀参考实现。