# firmata protocol

**Repository Path**: tinytaro/firmata-protocol

## Basic Information

- **Project Name**: firmata protocol
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Firmata 协议文档

[![Join the chat at https://gitter.im/firmata/protocol](https://badges.gitter.im/firmata/protocol.svg)](https://gitter.im/firmata/protocol?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Firmata 是一种用于从计算机（或智能手机/平板等）上的软件与微控制器进行通信的协议。该协议可以在任何微控制器架构的固件中实现，也可以在任何计算机软件包中实现（见下面的客户端库列表）。

Firmata 基于 MIDI 消息格式（midi message format），其命令字节为 8 位，数据字节为 7 位。例如，MIDI 的 Channel Pressure（命令：0xD0）消息长度为 2 字节，在 Firmata 中命令 0xD0 用于启用对一个数字端口（8 个引脚的集合）的报告。MIDI 和 Firmata 的版本都是 2 字节长，但含义显然不同。在 Firmata 中，消息的字节数必须与对应的 MIDI 消息一致。MIDI 的 System Exclusive（Sysex）消息长度可以是任意的，因此在整个 Firmata 协议中，Sysex 消息被最广泛地使用。

本仓库包含 Firmata 协议的文档。协议核心在 `protocol.md` 文件中描述。针对特定功能的文档分布在各个独立的 markdown 文件中（例如 `i2c.md`、`accelStepperFirmata.md`、`servos.md` 等）。添加到 `proposals` 目录下的文件是尚未定稿的新功能提案。查看 `feature-registry.md` 获取已记录 Firmata 功能的完整列表。

理论上，Firmata 协议可以为任何微控制器平台实现。不过目前最完整的实现是在 Arduino（包括与 Arduino 兼容的微控制器）上。已知的 Firmata 微控制器平台实现包括：

* [Firmata for Arduino](https://github.com/firmata/arduino)
* [Firmata for Spark.io](https://github.com/firmata/spark)

*注意：我确信还有其它实现。如果你知道其他实现，请提交一个 pull request 更新此 README 文件，或打开 issue 提供要添加的链接。*

## Firmata 客户端库
有若干客户端库实现了 Firmata 协议。这些库用于从计算机、智能手机或平板等设备与运行在微控制器平台上的 Firmata 固件通信。下面列出已实现的 Firmata 客户端库：

* processing
  * [https://github.com/firmata/processing]
* python
  * [https://github.com/MrYsLab/pymata4]
  * [https://github.com/MrYsLab/pymata-express]
  * [https://github.com/firmata/pyduino]
  * [https://github.com/lupeke/python-firmata]
  * [https://github.com/tino/pyFirmata]
* perl
  * [https://github.com/ntruchsess/perl-firmata]
  * [https://github.com/rcaputo/rx-firmata]
* ruby
  * [https://github.com/hardbap/firmata]
  * [https://github.com/PlasticLizard/rufinol]
* clojure
  * [https://github.com/nakkaya/clodiuno]
  * [https://github.com/peterschwarz/clj-firmata]
* javascript
  * [https://github.com/jgautier/firmata]
  * [http://breakoutjs.com]
  * [https://github.com/rwldrn/johnny-five]
* java
  * [https://github.com/4ntoine/Firmata]
  * [https://github.com/kurbatov/firmata4j]
  * [https://github.com/reapzor/FiloFirmata]
  * [https://github.com/mattjlewis/diozero/tree/main/diozero-provider-firmata]
* .NET
  * [https://github.com/SolidSoils/Arduino]
  * [https://github.com/dotnet/iot]
* PHP
  * [https://bitbucket.org/ThomasWeinert/carica-firmata]
  * [https://github.com/oasynnoum/phpmake_firmata]
* Haskell
  * [http://hackage.haskell.org/package/hArduino]
* iOS
  * [https://github.com/jacobrosenthal/iosfirmata]
* Dart
  * [https://github.com/nfrancois/firmata]
* Max/MSP
  * [http://www.maxuino.org/]
* Elixir
  * [https://github.com/kfatehi/firmata]
* Modelica
  * [https://www.wolfram.com/system-modeler/libraries/model-plug/]
* golang
  * [https://github.com/kraman/go-firmata]
* Qt/QML
  * [https://github.com/callaa/qfirmata]
* Android/Kotlin
  * [https://github.com/xujiaao/android-firmata]
* Smalltalk
  * [https://github.com/pharo-iot/Firmata] 
* LabVIEW
  * [https://github.com/KMurphs/labview-client-for-firmata] 
* vvvv/VL
  * [https://github.com/vvvv/VL.IO.Firmata]

*注意：并非每个客户端库都支持最新版本的 Firmata 协议及本仓库描述的所有功能。*

## 贡献

要提交新功能提案，请创建一个 markdown 文件并在文件名末尾附加 “-proposal”。提交一个 pull request 将该提案添加到仓库。

要修改现有协议，请提交一个包含你提议变更的 pull request。请在 pull request 描述中提供变更的理由。

起草新提案时的一些建议：

* 查看 `feature-registry.md` 了解如何提出新功能以及请求功能 ID。
* 如有多个消息，请根据需要使用子命令（第三字节）。参见 `accelStepperFirmata.md`，注意其中使用 `0x62` 作为功能 ID，并且每节都有枚举的子命令（0x00 = config，0x01 = zero，0x02 = step 等）。
* 只要这些可选值都位于消息末尾，Sysex 消息中包含可选值是可以的。请参见 `serial-1.0.md` 中 `SERIAL_CONFIG` 消息的字节 6 和 7。
* 尽量保持你的 Sysex 消息越短越好。
* 如有必要请进行位打包。参见 `encoder.md` 中“报告编码器位置”的响应消息示例（也注意该示例如何在响应消息之后进行文档说明……如果你的提案使用位打包，请提供类似的文档）。
* 如果你的提案使用了可用的非 Sysex MIDI 消息，则该消息的字节数必须与 MIDI 消息的字节数相对应。然而其含义不必相同。但如果 MIDI 消息使用通道（例如 Note Off（0x80）），则 Firmata 消息也必须使用通道，因为 MIDI 解析器可能会期望如此。