原标题：基于树莓派的自制MIDI键盘（教程）

基于树莓派的自制 MIDI 键盘教程：从零开始搭建你的音乐控制器

音乐创作与表演在现代科技的加持下变得前所未有的自由与便捷。MIDI（Musical Instrument Digital Interface，乐器数字接口）技术作为连接数字乐器与电脑的桥梁，在其中扮演着举足轻重的角色。拥有一款称手的 MIDI 键盘，是许多音乐爱好者和制作人的梦想。市面上虽然不乏各种商业化的 MIDI 键盘，但通过自制的方式，你不仅能深入理解其工作原理，更能根据个人需求进行高度定制，打造独一无二的音乐工具。本教程将引导你使用功能强大的树莓派作为核心，一步步构建属于你自己的 MIDI 键盘。

一、 项目概述与基本原理

自制 MIDI 键盘的核心思想是将物理按键的触发信号，通过微控制器（如树莓派）处理，转换成符合 MIDI 协议的数字信号，并通过 USB 或其他接口发送给计算机或MIDI设备。这个过程主要涉及以下几个关键环节：

1. 输入端： 键盘按键（可以是物理琴键、触点开关等）捕捉用户的演奏动作。

2. 信号采集与处理： 树莓派读取按键状态，并根据按键的按下、释放等事件，生成相应的 MIDI 消息。

3. MIDI 消息生成： 根据 MIDI 协议，将按键事件映射为音符开/关（Note On/Off）、力度（Velocity）等 MIDI 信息。

4. 输出端： 通过 USB 接口，树莓派模拟成一个标准的 USB MIDI 设备，将 MIDI 消息发送给电脑上的 DAW（数字音频工作站）软件或其他支持 MIDI 的应用程序。

选择树莓派作为核心控制器，是因为其强大的处理能力、丰富的 GPIO 接口、成熟的 Linux 生态系统以及广泛的社区支持，使得实现复杂的 MIDI 功能和便捷的编程变得轻而易举。

二、 核心元器件选择与功能解析

搭建一个功能完善的 MIDI 键盘，需要精心地挑选各种元器件。以下是本项目中推荐的核心元器件及其详细功能、选择理由：

2.1 核心控制器：树莓派 (Raspberry Pi)

• 推荐型号： 树莓派 4B (Raspberry Pi 4 Model B) 或 树莓派 5 (Raspberry Pi 5)。

• 功能： 作为整个 MIDI 键盘的“大脑”，负责读取按键输入、处理数据、生成 MIDI 消息并通过 USB 接口发送出去。它运行 Linux 操作系统，可以方便地安装各种开发库和工具。

• 选择理由：

• 强大的处理能力： 树莓派 4B/5 拥有多核处理器和大内存，足以应对实时 MIDI 消息的处理和生成，保证低延迟。

• 丰富的 GPIO 接口： 提供大量的通用输入/输出引脚，用于连接键盘矩阵、LED 指示灯、旋钮、滑块等。

• USB 接口： 内置多个 USB 接口，其中一个可以直接作为 USB MIDI 设备连接到电脑，无需额外的转换器。

• 成熟的生态系统： 拥有庞大的开发者社区，丰富的软件库（如 python-rtmidi 或 alsa-midi 相关库）和详细的文档，大大降低开发难度。

• 低功耗与体积小巧： 适合嵌入到键盘外壳中，实现便携性。

• 元器件功能： 树莓派集成了 CPU、GPU、RAM、网络接口（Wi-Fi 和蓝牙）、USB 控制器以及大量的 GPIO 引脚。对于本项目，我们将主要利用其 GPIO 引脚进行输入扫描，并利用其 USB 控制器模拟 MIDI 设备。

2.2 键盘输入矩阵：按键开关与二极管

• 推荐型号：

• 按键开关： 方形轻触开关 (Tactile Push Button Switches)、薄膜键盘导电胶触点（如果是拆解废弃电子琴）或 定制的机械琴键结构（如果是高端自制）。根据键程和手感需求选择。

• 二极管： 1N4148 小信号开关二极管。

• 功能：

• 按键开关： 检测用户按下琴键的动作。

• 二极管： 在键盘矩阵中，每个按键都需要串联一个二极管，用于防止“鬼影”和“遮蔽”效应，确保每个按键的独立识别。当多个按键同时按下时，如果没有二极管，电流可能会通过未按下的按键反向流回，导致误判（鬼影），或者阻止某些按键的信号被正确读取（遮蔽）。

• 选择理由：

• 按键开关： 根据成本、手感、寿命和易用性选择。轻触开关成本低廉，易于焊接，适合初期原型开发。如果追求专业手感，可以考虑定制机械键轴。

• 二极管： 1N4148 是非常常见的通用小信号开关二极管，成本低廉，易于获取，并且其反向恢复时间短，适用于高速信号切换，完美满足键盘矩阵扫描的需求。

• 元器件功能： 按键开关在按下时闭合电路，提供一个电信号。二极管利用其单向导电性，确保电流只沿一个方向流动，从而在复杂的键盘矩阵中隔离每个按键的信号。

2.3 信号扩展与复用：MCP23017 I2C GPIO 扩展器（可选，用于大型键盘）

• 推荐型号： Microchip MCP23017。

• 功能： 如果你的 MIDI 键盘有大量的按键（例如超过 20-30 个），树莓派的 GPIO 引脚可能不够用。MCP23017 是一款 16 通道 I/O 扩展器，可以通过 I2C 总线与树莓派通信，从而扩展更多的 GPIO 引脚，用于连接更多的按键、旋钮等。

• 选择理由：

• 节省 GPIO 引脚： 只需使用树莓派的两个 I2C 引脚（SDA 和 SCL）即可控制 16 个额外的 GPIO。一个树莓派可以连接多个 MCP23017 芯片，进一步扩展。

• 简化布线： 减少了从树莓派直接引出的线缆数量，使得电路布局更整洁。

• 易于编程： 有成熟的 Python 库（如 smbus2 和特定的 MCP23017 库）支持，方便读取和控制。

• 元器件功能： MCP23017 内部包含两个 8 位 I/O 端口（PortA 和 PortB），每个端口的引脚都可以独立配置为输入或输出。它通过 I2C 协议接收来自树莓派的命令，以读取按键状态或控制输出。

2.4 模拟输入：ADC 模数转换器 (如 MCP3008)（用于力度感应、旋钮、滑块）

• 推荐型号： Microchip MCP3008 (8 通道 10 位 SPI 接口 ADC)。

• 功能： 树莓派的 GPIO 引脚只能读取数字信号（高电平/低电平），无法直接读取模拟信号（如电位器产生的连续电压变化）。ADC 的作用是将模拟电压信号转换为数字信号，供树莓派读取。这对于实现按键力度感应（通过压敏电阻或光电传感器）、音高弯音轮、调制轮以及各种参数旋钮和滑块至关重要。

• 选择理由：

• SPI 接口： MCP3008 使用 SPI（串行外设接口）与树莓派通信，速度快且稳定。

• 多通道： 8 个模拟输入通道，足以满足大部分 MIDI 键盘的扩展需求（如力度、弯音、调制、音量等）。

• 10 位精度： 提供 1024 个离散值，对于 MIDI 127 级的力度和控制器值来说，精度绰绰有余。

• 成本效益： 价格合理，性能稳定。

• 元器件功能： MCP3008 接收一个模拟电压输入，然后通过内部的采样保持电路和模数转换器将其转换为一个数字值，并通过 SPI 总线以串行数据的形式发送给树莓派。

2.5 MIDI 输出指示：LED 指示灯与限流电阻

• 推荐型号：

• LED： 任意颜色 3mm 或 5mm 发光二极管。

• 限流电阻： 根据 LED 的正向电压和所需亮度选择，通常为 220 欧姆到 1k 欧姆 之间。

• 功能：

• LED： 提供视觉反馈，例如指示 MIDI 信号传输状态、电源状态、模式切换等。

• 限流电阻： 串联在 LED 和电源之间，限制通过 LED 的电流，防止 LED 因电流过大而烧毁。

• 选择理由： LED 成本低廉，易于集成，能够直观地显示设备状态。限流电阻是任何 LED 电路中必不可少的保护元件。

• 元器件功能： LED 在有足够电流通过时发光。电阻通过欧姆定律 (V=IR) 限制电路中的电流。

2.6 连接与供电：面包板/PCB、杜邦线、USB 数据线、电源适配器

• 推荐型号：

• 面包板： 标准无焊面包板（用于原型开发）。

• PCB： 定制 PCB 板（用于最终产品）。

• 杜邦线： 公对公、公对母、母对母杜邦线。

• USB 数据线： USB A 转 USB C/Micro B 数据线（根据树莓派型号选择）。

• 电源适配器： 5V 3A (树莓派 4B/5) 或 5V 2.5A (树莓派 3B+) USB 电源适配器。

• 功能：

• 面包板/PCB： 用于搭建和固定电路。面包板适合初期快速原型验证，PCB 适合最终产品的稳定性和美观度。

• 杜邦线： 连接各个元器件。

• USB 数据线： 连接树莓派和电脑，传输 MIDI 信号和供电。

• 电源适配器： 为树莓派提供稳定的电力。

• 选择理由：

• 面包板： 无需焊接，方便调整电路布局和测试。

• PCB： 一旦设计定型，定制 PCB 可以使电路更紧凑、稳定、可靠，并具有专业外观。

• 杜邦线： 方便连接和调试。

• USB 数据线： 树莓派的供电和 MIDI 通信都通过 USB 进行。

• 电源适配器： 树莓派对电源质量有较高要求，选择足够电流的适配器是保证稳定运行的关键。劣质电源可能导致树莓派重启或运行不稳定。

• 元器件功能： 面包板和 PCB 提供一个物理平台，用于元器件的电气连接。杜邦线是导线，用于连接不同元器件的引脚。USB 数据线同时传输电力和数据。电源适配器将交流电转换为树莓派所需的直流电。

2.7 外壳：木材、亚克力、3D 打印材料等

• 功能： 保护内部电路，提供稳固的键盘结构，提升美观度和用户体验。

• 选择理由： 根据预算、美学偏好和加工难度选择。

• 木材： 质感好，易于加工，适合手工爱好者。

• 亚克力： 现代感强，可以激光切割，精度高。

• 3D 打印： 最具定制性，可以设计出复杂的结构和造型。

• 元器件功能： 提供机械支撑和保护。

三、 电路设计与连接

电路设计是自制 MIDI 键盘的核心环节，它决定了按键信号如何被树莓派正确读取。

3.1 键盘矩阵连接

这是最关键的部分。为了节省树莓派的 GPIO 引脚，我们通常采用矩阵扫描的方式来连接按键。

• 原理： 键盘矩阵将按键排列成行（Row）和列（Column）的形式。树莓派通过轮流向某一行发送高电平信号，然后读取所有列的电平状态。如果某列检测到高电平，则表示该行与该列交叉处的按键被按下。

• 二极管的重要性： 如前所述，每个按键都需要串联一个二极管。二极管的带条纹的一端（阴极）应连接到行线，另一端（阳极）连接到按键。当按键按下时，电流只能从行线经过二极管流向列线，反之则不能。这确保了在同时按下多个键时，不会出现电流回流导致误判。

• 连接示例（以 4x4 矩阵为例，扩展到更多键位同理）：

• 选择树莓派的 GPIO 引脚作为行线和列线。

• 例如，使用 GPIO 17, 27, 22, 23 作为行输出 (Rows Output)，使用 GPIO 24, 25, 5, 6 作为列输入 (Columns Input)。

• 每个按键的一端连接到对应的行线，另一端串联一个 1N4148 二极管，二极管的另一端连接到对应的列线。

• 列线通常需要连接到树莓派的内部上拉电阻，或者外部连接一个下拉电阻，以确保在按键未按下时，引脚状态为低电平。树莓派的 GPIO 可以通过软件配置内部上拉/下拉电阻。

3.2 ADC 连接（用于模拟输入）

如果你需要力度感应、弯音轮或调制轮，就需要连接 ADC。

• MCP3008 与树莓派的 SPI 连接：

• VCC (MCP3008) -> 3.3V (树莓派)

• GND (MCP3008) -> GND (树莓派)

• CLK (MCP3008) -> SCLK (GPIO 11) (树莓派)

• DOUT (MCP3008) -> MISO (GPIO 9) (树莓派)

• DIN (MCP3008) -> MOSI (GPIO 10) (树莓派)

• CS (MCP3008) -> CE0 (GPIO 8) 或 CE1 (GPIO 7) (树莓派) (片选引脚，用于选择特定的 SPI 设备)

• 模拟传感器连接：

• 压敏电阻 (FSR)： 用于力度感应。一个 FSR 串联一个固定电阻（形成分压器），然后连接到 MCP3008 的一个模拟输入通道。FSR 的电阻值随压力变化而变化，从而改变分压点的电压。

• 电位器： 用于弯音轮、调制轮、音量旋钮等。电位器的两端分别连接 3.3V 和 GND，中间的滑动端连接到 MCP3008 的一个模拟输入通道。滑动电位器时，滑动端的电压会线性变化。

3.3 LED 指示灯连接

• LED 的长引脚（阳极）连接到限流电阻，限流电阻的另一端连接到树莓派的一个 GPIO 输出引脚。

• LED 的短引脚（阴极）连接到 GND。

• 通过控制 GPIO 引脚的高低电平，可以点亮或熄灭 LED。

3.4 电源连接

• 树莓派通过其 USB Type-C (树莓派 4B/5) 或 Micro USB (树莓派 3B+) 接口供电。

• 确保使用足电流的电源适配器，例如树莓派 4B 建议使用 5V 3A 的适配器。

四、 软件开发：树莓派上的 MIDI 编程

软件是 MIDI 键盘的灵魂，它将硬件信号转化为音乐语言。

4.1 树莓派系统配置

1. 烧录操作系统： 使用 Raspberry Pi Imager 工具将 Raspbian OS（现在更名为 Raspberry Pi OS）烧录到 MicroSD 卡。

2. 启用 SPI 和 I2C： 在树莓派系统启动后，通过 sudo raspi-config 命令，在 "Interface Options" 中启用 SPI 和 I2C 接口，这是与 ADC 和 MCP23017 通信所必需的。

3. 更新系统： sudo apt update && sudo apt upgrade 确保系统和软件包都是最新版本。

4. 安装 Python 和相关库： 树莓派通常预装 Python。你需要安装用于 MIDI 通信和 GPIO 控制的 Python 库。

• GPIO 控制： pip install RPi.GPIO 或 pip install lgpio (对于新的树莓派版本)。

• SPI 通信 (MCP3008)： pip install spidev。

• I2C 通信 (MCP23017)： pip install smbus2 和 pip install adafruit-circuitpython-mcp230xx (Adafruit 库封装了 MCP23017 的复杂操作)。

• MIDI 通信： pip install python-rtmidi 是一个流行的 Python MIDI 库，支持跨平台。它能让树莓派作为 USB MIDI 设备出现。

4.2 软件逻辑概述

核心的软件逻辑将包括以下几个部分：

1. GPIO 初始化： 配置所有用于键盘矩阵扫描的 GPIO 引脚为输入或输出模式，并设置内部上拉/下拉电阻。

2. MIDI 接口初始化： 使用 python-rtmidi 库创建一个 MIDI 输出端口，让树莓派能够发送 MIDI 消息。

3. 键盘矩阵扫描循环：

• 在一个无限循环中，依次将每一行设置为高电平。

• 读取所有列的电平状态。

• 根据读取到的状态，判断哪个按键被按下或释放。

• 消抖 (Debouncing)： 按键按下或释放时，由于机械触点的物理特性，可能会产生短暂的抖动信号。必须通过软件延时或状态机算法进行消抖，以避免发送重复的 MIDI 消息。

• 记录按键的当前状态和上一次状态，以便检测按键的边缘触发（按下或释放）。

4. 模拟信号读取与映射 (如果包含 ADC)：

• 定期从 MCP3008 读取模拟通道的数字值。

• 将这些值映射到 MIDI 协议的 0-127 范围内。例如，力度感应会将 0-1023 的 ADC 值映射到 MIDI 0-127。

5. MIDI 消息生成与发送：

• Note On/Off 消息： 当检测到按键按下时，发送一个 Note On 消息，包含音符编号（MIDI Note Number，例如 C4 是 60）和力度值。当按键释放时，发送一个 Note Off 消息，包含音符编号和力度值（通常为 0）。

• Control Change (CC) 消息： 用于发送旋钮、滑块等控制器的值。包含控制器编号和控制器值。

• Pitch Bend (弯音) 消息： 用于弯音轮，值范围更大 (0-16383)，中点为 8192。

• 使用 python-rtmidi 的 send_message() 函数发送这些 MIDI 字节数据。

6. LED 控制： 根据程序状态或 MIDI 信号（如接收到 MIDI 时钟信号或发送 MIDI 消息时），控制 GPIO 引脚高低电平以点亮或熄灭 LED。

4.3 关键 MIDI 消息格式

MIDI 消息由一系列字节组成，每个字节通常在 0-127 之间。

• Note On 消息： [0x9n, note_number, velocity]

• 0x9n: 状态字节，其中 n 是 MIDI 通道号 (0-15)。

• note_number: 音符编号 (0-127)，例如 60 代表 C4。

• velocity: 力度值 (0-127)，0 代表 Note Off，大于 0 代表 Note On。

• Note Off 消息： [0x8n, note_number, velocity]

• 0x8n: 状态字节，其中 n 是 MIDI 通道号 (0-15)。

• note_number: 音符编号 (0-127)。

• velocity: 通常为 0。

• Control Change 消息： [0xBn, controller_number, controller_value]

• 0xBn: 状态字节，其中 n 是 MIDI 通道号 (0-15)。

• controller_number: 控制器编号 (0-127)，每个编号对应不同的功能，例如 7 是音量，10 是声像。

• controller_value: 控制器值 (0-127)。

• Pitch Bend 消息： [0xE n, lsb, msb]

• 0xEn: 状态字节，其中 n 是 MIDI 通道号 (0-15)。

• lsb: 最低有效字节。

• msb: 最高有效字节。

• Pitch Bend 值为 0-16383，通常由 lsb + (msb << 7) 组合而成。

五、 外壳制作与组装

外壳是自制 MIDI 键盘的“门面”和保护。

5.1 设计考虑

• 尺寸与布局： 根据琴键数量、旋钮、滑块以及树莓派和电路板的大小，合理规划外壳的尺寸。

• 按键固定： 确保按键能够牢固地安装在外壳上，并且手感良好。

• 端口预留： 为树莓派的 USB、电源、HDMI 等接口预留开孔。

• 散热： 如果长时间使用，考虑为树莓派预留散热孔或安装散热片。

• 美观性： 考虑整体外观，可以进行喷漆、贴纸等装饰。

5.2 制作方法

1. 图纸设计： 使用 CAD 软件（如 Fusion 360, SketchUp, Inkscape）绘制详细的结构图，包括孔位、尺寸等。

2. 材料切割与加工：

• 木材： 使用锯、钻、砂纸等工具进行切割、打磨和组装。

• 亚克力： 送到专业的激光切割店进行切割，或者使用亚克力切割刀手工切割。

• 3D 打印： 使用 3D 打印机打印设计好的模型部件。

3. 元器件固定： 将焊接好的电路板、树莓派等用螺丝或热熔胶固定在外壳内部。

4. 按键安装： 将琴键或开关固定在外壳面板上，确保按键下方的触点能够正确连接到键盘矩阵。

5. 最终组装： 将所有部件组装起来，确保线路连接牢固，外壳封闭良好。

六、 测试与调试

完成硬件组装和软件编程后，进行全面的测试和调试是必不可少的步骤。

6.1 硬件测试

1. 电源测试： 确保树莓派能正常启动，LED 指示灯正常工作。

2. GPIO 测试： 编写简单的 Python 脚本，测试每个 GPIO 引脚的输入/输出功能，确保能正确读取按键状态和控制 LED。

3. 键盘矩阵测试： 逐个按压每个按键，使用调试输出（例如 print() 语句）查看树莓派是否能正确识别每个按键的按下和释放。特别注意是否有“鬼影”或漏检的现象，这通常与二极管的连接或消抖算法有关。

4. ADC 测试 (如果适用)： 旋转旋钮、滑动滑块或按压力度传感器，观察读取到的 ADC 值是否在预期范围内且变化平滑。

6.2 软件调试

1. MIDI 端口识别： 将树莓派连接到电脑，查看电脑的设备管理器（Windows）或 aplaymidi -l / aconnect -l (Linux) / Audio MIDI Setup (macOS) 是否能识别到树莓派作为一个 USB MIDI 设备。

2. MIDI 消息测试：

• 使用 MIDI 监视器软件： 在电脑上安装 MIDI 监视器软件（如 MIDI-OX (Windows), MIDI Monitor (macOS), qmidiroute (Linux)）。

• 打开监视器，按下自制 MIDI 键盘上的按键，观察是否能接收到正确的 Note On/Off 消息，包括音符编号和力度值。

• 测试旋钮、滑块、弯音轮等，检查是否能发送正确的 Control Change 或 Pitch Bend 消息。

3. 延迟测试： 观察按键按下到声音产生之间的延迟。过高的延迟可能意味着软件处理效率低下或 USB 连接问题。

4. 稳定性测试： 长时间运行，看是否有崩溃、数据丢失或按键失效的情况。

七、 进一步扩展与高级功能

一旦你成功搭建了基本的 MIDI 键盘，你可以考虑添加更多高级功能，使其更具专业性：

• 多八度切换： 添加按键或开关，用于快速切换键盘的音高八度。

• 移调功能： 实现音高微调或半音移调。

• 多模式切换： 通过按键组合或旋钮，切换键盘的不同工作模式（例如，演奏模式、控制器模式、编程模式）。

• OLED 显示屏： 集成一块小的 OLED 屏幕，用于显示当前八度、模式、参数值等信息。

• MIDI Out 接口： 如果需要连接传统的 MIDI 设备，可以增加一个 MIDI Out 接口（需要一个 MIDI DIN 5 针连接器和光耦隔离电路，如 6N137）。

• 复音触后 (Polyphonic Aftertouch)： 这需要更复杂的按键传感器和软件算法，能够感应每个单独按键的压力变化，并发送相应的 MIDI 消息。

• 琶音器/和弦模式： 在树莓派上编写算法，实现自动琶音或和弦演奏功能。

• 踏板输入： 增加踏板接口，用于延音踏板或表情踏板。

• 电池供电： 如果希望便携使用，可以考虑加入锂电池和充电管理模块。

八、 总结与展望

自制基于树莓派的 MIDI 键盘是一个极具挑战性但回报丰厚的项目。它不仅能让你亲手打造一款个性化的音乐工具，更能在过程中深入学习电子、编程和音乐 MIDI 协议的知识。从选择合适的元器件，到精心设计电路，再到编写高效的软件代码，每一步都需要你的耐心和创造力。

完成这个项目后，你将不仅仅拥有一个能发出声音的键盘，更拥有了深入理解数字音乐世界的一把钥匙。你可以根据自己的需求，不断地迭代和优化你的设计，将其打造成一个功能更加强大、更加符合你个人演奏习惯的专业级音乐控制器。希望本教程能够为你提供一个清晰的指引，助你开启这段充满乐趣的创客之旅！