|
1 | | -#ConfigurableFirmata |
2 | | - |
3 | | -[](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 | | -##Usage |
8 | | - |
9 | | -There are three primary 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. |
10 | | - |
11 | | -The second and more common model is to load a general purpose sketch called StandardFirmata 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. |
12 | | - |
13 | | -The third and more experimental model is **ConfigurableFirmata**. ConfigurableFirmata is a branch of Firmata that breaks features such as Digital Input, Digital Output, Analog Input, Analog Output, I2C, etc into [individual classes](https://github.com/firmata/arduino/tree/configurable/utility) making it easier to mix and match standard features with custom features. You configure your sketch by adding or removing various include statements. See the [ConfigurableFirmata.ino](https://github.com/firmata/arduino/blob/configurable/examples/ConfigurableFirmata/ConfigurableFirmata.ino) file for an example that includes all available features. You are also able to choose between a Serial connection or an Ethernet connection type. |
14 | | - |
15 | | -##Firmata Client Libraries |
16 | | -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: |
17 | | - |
18 | | - |
19 | | -* procesing |
20 | | - * [https://github.com/firmata/processing] |
21 | | - * [http://funnel.cc] |
22 | | -* python |
23 | | - * [https://github.com/firmata/pyduino] |
24 | | - * [https://github.com/lupeke/python-firmata] |
25 | | - * [https://github.com/tino/pyFirmata] |
26 | | - * [https://github.com/MrYsLab/PyMata] |
27 | | -* perl |
28 | | - * [https://github.com/ntruchsess/perl-firmata] |
29 | | - * [https://github.com/rcaputo/rx-firmata] |
30 | | -* ruby |
31 | | - * [https://github.com/hardbap/firmata] |
32 | | - * [https://github.com/PlasticLizard/rufinol] |
33 | | - * [http://funnel.cc] |
34 | | -* clojure |
35 | | - * [https://github.com/nakkaya/clodiuno] |
36 | | - * [https://github.com/peterschwarz/clj-firmata] |
37 | | -* javascript |
38 | | - * [https://github.com/jgautier/firmata] |
39 | | - * [http://breakoutjs.com] |
40 | | - * [https://github.com/rwldrn/johnny-five] |
41 | | -* java |
42 | | - * [https://github.com/4ntoine/Firmata] |
43 | | - * [https://github.com/shigeodayo/Javarduino] |
44 | | - * [https://github.com/kurbatov/firmata4j] |
45 | | -* .NET |
46 | | - * [https://github.com/SolidSoils/Arduino] |
47 | | - * [http://www.imagitronics.org/projects/firmatanet/] |
48 | | -* Flash/AS3 |
49 | | - * [http://funnel.cc] |
50 | | - * [http://code.google.com/p/as3glue/] |
51 | | -* PHP |
52 | | - * [https://bitbucket.org/ThomasWeinert/carica-firmata] |
53 | | - * [https://github.com/oasynnoum/phpmake_firmata] |
54 | | -* Haskell |
55 | | - * [http://hackage.haskell.org/package/hArduino] |
56 | | -* iOS |
57 | | - * [https://github.com/jacobrosenthal/iosfirmata] |
58 | | -* Dart |
59 | | - * [https://github.com/nfrancois/firmata] |
60 | | - |
61 | | -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. |
62 | | - |
63 | | -##Updating Firmata in the Arduino IDE |
64 | | -The version of firmata in the Arduino IDE contains an outdated version of Firmata. To update Firmata, download the latest [Configurable Firmata release](https://github.com/firmata/arduino/releases/tag/v2.6.2) (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. |
65 | | - |
66 | | -*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).* |
67 | | - |
68 | | -###Mac OSX: |
69 | | - |
70 | | -The Firmata library is contained within the Arduino package. |
71 | | - |
72 | | -1. Navigate to the Arduino application |
73 | | -2. Right click on the application icon and select `Show Package Contents` |
74 | | -3. Navigate to: `/Contents/Resources/Java/libraries/` and replace the existing |
75 | | -`Firmata` folder with latest [ConfigurableFirmata release](https://github.com/firmata/arduino/releases/tag/v2.6.2) (note there is a different download |
76 | | -for Arduino 1.0.x vs 1.5.x) |
77 | | -4. Restart the Arduino application and the latest version of Firmata will be available. |
78 | | - |
79 | | -If you are using the Java 7 version of Arduino 1.5.7 or higher, the file path |
80 | | -will differ slightly: `Contents/Java/libraries/Firmata` (no Resources directory). |
81 | | - |
82 | | -###Windows: |
83 | | - |
84 | | -1. Navigate to `c:/Program\ Files/arduino-1.x/libraries/` and replace the existing |
85 | | -`Firmata` folder with the latest [ConfigurableFirmata release](https://github.com/firmata/arduino/releases/tag/v2.6.2) (note there is a different download |
86 | | -for Arduino 1.0.x vs 1.5.x). |
87 | | -2. Restart the Arduino application and the latest version of Firmata will be available. |
88 | | - |
89 | | -*Update the path and arduino version as necessary* |
90 | | - |
91 | | -###Linux: |
92 | | - |
93 | | -1. Navigate to `~/arduino-1.x/libraries/` and replace the existing |
94 | | -`Firmata` folder with the latest [ConfigurableFirmata release](https://github.com/firmata/arduino/releases/tag/v2.6.2) (note there is a different download |
95 | | -for Arduino 1.0.x vs 1.5.x). |
96 | | -2. Restart the Arduino application and the latest version of Firmata will be available. |
97 | | - |
98 | | -*Update the path and arduino version as necessary* |
99 | | - |
100 | | -###Using the ConfigurableFirmata Source code rather than release archive |
101 | | - |
102 | | -Clone this repo directly into the core Arduino libraries directory. If you are using |
103 | | -Arduino 1.5.x, the repo directory structure will not match the Arduino |
104 | | -library format, however it should still compile as long as you are using Arduino 1.5.7 |
105 | | -or higher. |
106 | | - |
107 | | -You will first need to remove the existing Firmata library, then clone firmata/arduino |
108 | | -into an empty Firmata directory and checkout the `configurable` branch: |
109 | | - |
110 | | -```bash |
111 | | -$ rm -r /Applications/Arduino.app/Contents/Resources/Java/libraries/Firmata |
112 | | -$ git clone [email protected]:firmata/arduino.git /Applications/Arduino.app/Contents/Resources/Java/libraries/Firmata |
113 | | -$ git checkout configurable |
114 | | -``` |
115 | | - |
116 | | -*Update paths if you're using Windows or Linux* |
117 | | - |
118 | | -To generate properly formatted versions of Firmata (for Arduino 1.0.x and Arduino 1.5.x), run the |
119 | | -`release.sh` script. |
120 | | - |
121 | | -<a name="contributing" /> |
122 | | -##Contributing |
123 | | - |
124 | | -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). |
125 | | - |
126 | | -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. |
127 | | - |
128 | | -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. |
129 | | - |
130 | | -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. |
131 | | - |
132 | | -Use [Artistic Style](http://astyle.sourceforge.net/) (astyle) to format your code. Set the following rules for the astyle formatter: |
133 | | - |
134 | | -``` |
135 | | -style = "" |
136 | | -indent-spaces = 2 |
137 | | -indent-classes = true |
138 | | -indent-switches = true |
139 | | -indent-cases = true |
140 | | -indent-col1-comments = true |
141 | | -pad-oper = true |
142 | | -pad-header = true |
143 | | -keep-one-line-statements = true |
144 | | -``` |
145 | | - |
146 | | -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. |
| 1 | +**ConfigurableFirmata is been broken out into a separate repository. You'll find it [here](https://github.com/firmata/ConfigurableFirmata).** |
0 commit comments