Arduino/libraries/Firmata/readme.md

   1 # Firmata
   2
   3 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/firmata/arduino?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   4
   5 Firmata is a protocol for communicating with microcontrollers from software on a host computer. The [protocol](https://github.com/firmata/protocol) can be implemented in firmware on any microcontroller architecture as well as software on any host computer software package. The Arduino repository described here is a Firmata library for Arduino and Arduino-compatible devices. If you would like to contribute to Firmata, please see the [Contributing](#contributing) section below.
   6
   7 # Contents
   8
   9 - [Usage](#usage)
  10 - [Firmata Client Libraries](#firmata-client-libraries)
  11 - [Updating Firmata in the Arduino IDE - Arduino 1.6.4 and higher](#updating-firmata-in-the-arduino-ide---arduino-164-and-higher)
  12 - [Cloning Firmata](#cloning-firmata)
  13 - [Updating Firmata in the Arduino IDE - older versions (<= 1.6.3 or 1.0.x)](#updating-firmata-in-the-arduino-ide---older-versions--163-or-10x)
  14   - [Mac OSX:](#mac-osx)
  15   - [Windows](#windows)
  16   - [Linux](#linux)
  17 - [Using the Source code rather than release archive (only for versions older than Arduino 1.6.3)](#using-the-source-code-rather-than-release-archive-only-for-versions-older-than-arduino-163)
  18 - [Contributing](#contributing)
  19
  20 ## Usage
  21
  22 There are two main models of usage of Firmata. In one model, the author of the Arduino sketch uses the various methods provided by the Firmata library to selectively send and receive data between the Arduino device and the software running on the host computer. For example, a user can send analog data to the host using ``` Firmata.sendAnalog(analogPin, analogRead(analogPin)) ``` or send data packed in a string using ``` Firmata.sendString(stringToSend) ```. See File -> Examples -> Firmata -> AnalogFirmata & EchoString respectively for examples.
  23
  24 The second and more common model is to load a general purpose sketch called StandardFirmata (or one of the variants such as StandardFirmataPlus or StandardFirmataEthernet depending on your needs) on the Arduino board and then use the host computer exclusively to interact with the Arduino board. StandardFirmata is located in the Arduino IDE in File -> Examples -> Firmata.
  25
  26 ## Firmata Client Libraries
  27 Most of the time you will be interacting with Arduino with a client library on the host computers. Several Firmata client libraries have been implemented in a variety of popular programming languages:
  28
  29 * processing
  30   * [https://github.com/firmata/processing](https://github.com/firmata/processing)
  31   * [http://funnel.cc](http://funnel.cc)
  32 * python
  33   * [https://github.com/MrYsLab/pymata-aio](https://github.com/MrYsLab/pymata-aio)
  34   * [https://github.com/MrYsLab/PyMata]([https://github.com/MrYsLab/PyMata)
  35   * [https://github.com/tino/pyFirmata](https://github.com/tino/pyFirmata)
  36   * [https://github.com/lupeke/python-firmata](https://github.com/lupeke/python-firmata)
  37   * [https://github.com/firmata/pyduino](https://github.com/firmata/pyduino)
  38 * perl
  39   * [https://github.com/ntruchsess/perl-firmata](https://github.com/ntruchsess/perl-firmata)
  40   * [https://github.com/rcaputo/rx-firmata](https://github.com/rcaputo/rx-firmata)
  41 * ruby
  42   * [https://github.com/hardbap/firmata](https://github.com/hardbap/firmata)
  43   * [https://github.com/PlasticLizard/rufinol](https://github.com/PlasticLizard/rufinol)
  44   * [http://funnel.cc](http://funnel.cc)
  45 * clojure
  46   * [https://github.com/nakkaya/clodiuno](https://github.com/nakkaya/clodiuno)
  47   * [https://github.com/peterschwarz/clj-firmata](https://github.com/peterschwarz/clj-firmata)
  48 * javascript
  49   * [https://github.com/jgautier/firmata](https://github.com/jgautier/firmata)
  50   * [https://github.com/rwldrn/johnny-five](https://github.com/rwldrn/johnny-five)
  51   * [http://breakoutjs.com](http://breakoutjs.com)
  52 * java
  53   * [https://github.com/kurbatov/firmata4j](https://github.com/kurbatov/firmata4j)
  54   * [https://github.com/4ntoine/Firmata](https://github.com/4ntoine/Firmata)
  55   * [https://github.com/reapzor/FiloFirmata](https://github.com/reapzor/FiloFirmata)
  56 * .NET
  57   * [https://github.com/SolidSoils/Arduino](https://github.com/SolidSoils/Arduino)
  58   * [http://www.acraigie.com/programming/firmatavb/default.html](http://www.acraigie.com/programming/firmatavb/default.html)
  59 * Flash/AS3
  60   * [http://funnel.cc](http://funnel.cc)
  61   * [http://code.google.com/p/as3glue/](http://code.google.com/p/as3glue/)
  62 * PHP
  63   * [https://github.com/ThomasWeinert/carica-firmata]()
  64   * [https://github.com/oasynnoum/phpmake_firmata](https://github.com/oasynnoum/phpmake_firmata)
  65 * Haskell
  66   * [http://hackage.haskell.org/package/hArduino](http://hackage.haskell.org/package/hArduino)
  67 * iOS
  68   * [https://github.com/jacobrosenthal/iosfirmata](https://github.com/jacobrosenthal/iosfirmata)
  69 * Dart
  70   * [https://github.com/nfrancois/firmata](https://github.com/nfrancois/firmata)
  71 * Max/MSP
  72   * [http://www.maxuino.org/](http://www.maxuino.org/)
  73 * Elixir
  74   * [https://github.com/kfatehi/firmata](https://github.com/kfatehi/firmata)
  75 * Modelica
  76   * [https://www.wolfram.com/system-modeler/libraries/model-plug/](https://www.wolfram.com/system-modeler/libraries/model-plug/)
  77 * Go
  78   * [https://github.com/kraman/go-firmata](https://github.com/kraman/go-firmata)
  79 * vvvv
  80   * [https://vvvv.org/blog/arduino-second-service](https://vvvv.org/blog/arduino-second-service)
  81 * openFrameworks
  82   * [http://openframeworks.cc/documentation/communication/ofArduino/](http://openframeworks.cc/documentation/communication/ofArduino/)
  83 * Rust
  84   * [https://github.com/zankich/rust-firmata](https://github.com/zankich/rust-firmata)
  85
  86 Note: The above libraries may support various versions of the Firmata protocol and therefore may not support all features of the latest Firmata spec nor all Arduino and Arduino-compatible boards. Refer to the respective projects for details.
  87
  88 ## Updating Firmata in the Arduino IDE - Arduino 1.6.4 and higher
  89
  90 If you want to update to the latest stable version:
  91
  92 1. Open the Arduino IDE and navigate to: `Sketch > Include Library > Manage Libraries`
  93 2. Filter by "Firmata" and click on the "Firmata by Firmata Developers" item in the list of results.
  94 3. Click the `Select version` dropdown and select the most recent version (note you can also install previous versions)
  95 4. Click `Install`.
  96
  97 ### Cloning Firmata
  98
  99 If you are contributing to Firmata or otherwise need a version newer than the latest tagged release, you can clone Firmata directly to your Arduino/libraries/ directory (where 3rd party libraries are installed). This only works for Arduino 1.6.4 and higher, for older versions you need to clone into the Arduino application directory (see section below titled "Using the Source code rather than release archive"). Be sure to change the name to Firmata as follows:
 100
 101 ```bash
 102 $ git clone git@github.com:firmata/arduino.git ~/Documents/Arduino/libraries/Firmata
 103 ```
 104
 105 *Update path above if you're using Windows or Linux or changed the default Arduino directory on OS X*
 106
 107
 108 ## Updating Firmata in the Arduino IDE - older versions (<= 1.6.3 or 1.0.x)
 109
 110 Download the latest [release](https://github.com/firmata/arduino/releases/tag/2.5.7) (for Arduino 1.0.x or Arduino 1.5.6 or higher) and replace the existing Firmata folder in your Arduino application. See the instructions below for your platform.
 111
 112 *Note that Arduino 1.5.0 - 1.5.5 are not supported. Please use Arduino 1.5.6 or higher (or Arduino 1.0.5 or 1.0.6).*
 113
 114 ### Mac OSX:
 115
 116 The Firmata library is contained within the Arduino package.
 117
 118 1. Navigate to the Arduino application
 119 2. Right click on the application icon and select `Show Package Contents`
 120 3. Navigate to: `/Contents/Resources/Java/libraries/` and replace the existing
 121 `Firmata` folder with latest [Firmata release](https://github.com/firmata/arduino/releases/tag/2.5.7) (note there is a different download
 122 for Arduino 1.0.x vs 1.6.x)
 123 4. Restart the Arduino application and the latest version of Firmata will be available.
 124
 125 *If you are using the Java 7 version of Arduino 1.5.7 or higher, the file path
 126 will differ slightly: `Contents/Java/libraries/Firmata` (no Resources directory).*
 127
 128 ### Windows:
 129
 130 1. Navigate to `c:/Program\ Files/arduino-1.x/libraries/` and replace the existing
 131 `Firmata` folder with the latest [Firmata release](https://github.com/firmata/arduino/releases/tag/2.5.7) (note there is a different download
 132 for Arduino 1.0.x vs 1.6.x).
 133 2. Restart the Arduino application and the latest version of Firmata will be available.
 134
 135 *Update the path and Arduino version as necessary*
 136
 137 ### Linux:
 138
 139 1. Navigate to `~/arduino-1.x/libraries/` and replace the existing
 140 `Firmata` folder with the latest [Firmata release](https://github.com/firmata/arduino/releases/tag/2.5.7) (note there is a different download
 141 for Arduino 1.0.x vs 1.6.x).
 142 2. Restart the Arduino application and the latest version of Firmata will be available.
 143
 144 *Update the path and Arduino version as necessary*
 145
 146 ### Using the Source code rather than release archive (only for versions older than Arduino 1.6.3)
 147
 148 *It is recommended you update to Arduino 1.6.4 or higher if possible, that way you can clone directly into the external Arduino/libraries/ directory which persists between Arduino application updates. Otherwise you will need to move your clone each time you update to a newer version of the Arduino IDE.*
 149
 150 If you're stuck with an older version of the IDE, then follow these keep reading otherwise jump up to the "Cloning Firmata section above".
 151
 152 Clone this repo directly into the core Arduino application libraries directory. If you are using
 153 Arduino 1.5.x or <= 1.6.3, the repo directory structure will not match the Arduino
 154 library format, however it should still compile as long as you are using Arduino 1.5.7
 155 or higher.
 156
 157 You will first need to remove the existing Firmata library, then clone firmata/arduino
 158 into an empty Firmata directory:
 159
 160 ```bash
 161 $ rm -r /Applications/Arduino.app/Contents/Resources/Java/libraries/Firmata
 162 $ git clone git@github.com:firmata/arduino.git /Applications/Arduino.app/Contents/Resources/Java/libraries/Firmata
 163 ```
 164
 165 *Update paths if you're using Windows or Linux*
 166
 167 To generate properly formatted versions of Firmata (for Arduino 1.0.x and Arduino 1.6.x), run the
 168 `release.sh` script.
 169
 170 ## Contributing
 171
 172 If you discover a bug or would like to propose a new feature, please open a new [issue](https://github.com/firmata/arduino/issues?sort=created&state=open). Due to the limited memory of standard Arduino boards we cannot add every requested feature to StandardFirmata. Requests to add new features to StandardFirmata will be evaluated by the Firmata developers. However it is still possible to add new features to other Firmata implementations (Firmata is a protocol whereas StandardFirmata is just one of many possible implementations).
 173
 174 To contribute, fork this repository and create a new topic branch for the bug, feature or other existing issue you are addressing. Submit the pull request against the *master* branch.
 175
 176 If you would like to contribute but don't have a specific bugfix or new feature to contribute, you can take on an existing issue, see issues labeled "pull-request-encouraged". Add a comment to the issue to express your intent to begin work and/or to get any additional information about the issue.
 177
 178 You must thoroughly test your contributed code. In your pull request, describe tests performed to ensure that no existing code is broken and that any changes maintain backwards compatibility with the existing api. Test on multiple Arduino board variants if possible. We hope to enable some form of automated (or at least semi-automated) testing in the future, but for now any tests will need to be executed manually by the contributor and reviewers.
 179
 180 Use [Artistic Style](http://astyle.sourceforge.net/) (astyle) to format your code. Set the following rules for the astyle formatter:
 181
 182 ```
 183 style = ""
 184 indent-spaces = 2
 185 indent-classes = true
 186 indent-switches = true
 187 indent-cases = true
 188 indent-col1-comments = true
 189 pad-oper = true
 190 pad-header = true
 191 keep-one-line-statements = true
 192 ```
 193
 194 If you happen to use Sublime Text, [this astyle plugin](https://github.com/timonwong/SublimeAStyleFormatter) is helpful. Set the above rules in the user settings file.