At the request of users, we have created this plugin. The plugin works well with our test Arduino setup. But, because it is impossible for us to test every configuration of Arduino board and the hardware you have connected to it, we have labeled this plugin as a public alpha. That means there it is possible there are bugs that might cause the plugin not to work and/or lead to crashes. We do not recommend using this actor for mission critical performances or installations yet. If you do choose to use this alpha version for such performances, you do so at your own risk.
If you use this plugin and find problems, please post them on the Isadora Community Forum. We'll do our best to solve bug that you find an release updates to this plugin as fast as we can.
Firmata is a piece of software that you can upload to your Arduino board that offers standardized protocol for input and output. When you use Firmata, you are able to receive data from, or send data to, the Arduino pins without writing any additional software. The Isadora Arudino Firmata actor takes advantage of this system to provide input and output from those Arduino pins.
First you need to learn how to attach switches, sensors, LEDs, motors and whatever else you desire to the physical input and output pins on your Arduino board. If you do a Google search for Arduino tutorials you'll find dozens upon dozens of tutorials online (both video and written) that can help you learn more about how to do this. You can also jump directly to the tutorials on the main Arduino site.
Second, you need to have a basic understanding of how the Firmata system works. We found this tutorial on instructables.com to be a good one. It shows you how to establish communications with your board and upload the Firmata firmware to your Arduino. The article then describes how you how you can use the free Firmata Test App to manually test the hardware connected to your Arduino input and output pins.
Third, we strongly recommend that you debug your hardware setups using the Firmata Test App before you try to connect your board to Isadora. We've created a "notarized" version for macOS so that the app will run without issue on macOS Catalina and later. The download links below lead to github release pages where you can get the latest version of the app.
One thing you need to pay attention to when doing the above three steps is the name of the serial port used by the Arduino IDE and/or the Firmata Test App to communicate with your board. You will want to use that same serial port when setting up serial communications in Isadora.
Once you've accomplished these first two steps, you can follow the instructions below to start using the Arduino Firmata actor
If you haven't already done so, please follow the steps in the section above called "How Do I Prepare To Use the Arduino Firmata Actor" before continuing below.
To use the Arduino Firmata actor, you first need to take the following steps.
Double-click on the Scene editor and, in the pop up box that appears, type 'firmata'. You'll see 'Arduino Firmata' appear in the list. Click on that to add the actor to the Scene.
When the Arduino Firmata actor is added to the Scene, or when it is activated by entering a Scene that contains it, it immediately sends a request for information to the Firmata firmware running on your board. If everything is working properly, the Arduino will responds with data that tells the actor things like how many pins your Arduino board has, and what their capabilities are.
If everything is set up properly and the actor receives a response, the 'firmware' output will report the version of the Firmata software running on your Arduino (e.g., 'v2.5'), and the 'status' output will show the word 'connected'.
If the actor does not receive a response from the board, the 'firmware' output will show '???' and the 'status' output will be empty. If this happens, make sure you've enabled the serial port as described in step 2 above, and that the board is physically connected to your computer.
In the Arduino Firmata actor, the following inputs allow you to tell the actor about how many pins of a certain type you need.
Once you have entered the number of inputs and outputs you require, you can click the '-' sign to the left of the word 'gen spec' to trigger that input. This will automatically generate a specification that defines the Firmata input and output pins that the Arduino Firmata actor will offer.
As soon as you trigger the 'gen spec' input, you will see new inputs and outputs appear on the Isadora Firmata actor. For every Arduino pin that functions as an output, you'll see an input on the actor. Likewise, for every Arduino pin that functions as an input, you'll see an output on the Isadora actor.
Perhaps you are now asking, "why does an Arduino input pin generate an output on the Arduino Firmata actor?" Because the Arduino pin is taking data in you need an output on the actor so you can see and use that value. Similarly, an input to the Arduino Firmata actor is added for each Arduino output pin you requested. When you change the values of those actor inputs, they send the value to the corresponding physical output pin on the Arduino board
You're almost done, but you may need to do a little editing of the specification that was generated before it will work properly. Here's an example to show you what we mean.
Let's say that you have three LED's that you want to turn on or off, and that they are connected to digital pins 5, 6 and 7 of the Arduino board. You also have a photocell variable resistor connected to analog input pin A0. (We strongly recommend that you "debug" your setup using the Firmata Test App before continuing. In this example, you'd make sure that you can turn the LEDs on and off, and that the analog input shows a changing value as you apply more or less light to the photocell.)
For this setup, you'd set the 'digital out' input of the Firmata Arduino actor to 3, and the 'analog in' input to 1. Then click the '-' to the left of the words 'gen spec' to trigger that input, and automatically generate the pin specification. After doing this, you see new inputs and outputs are added to the actor that match the requests you made in the 'digital out' and 'analog in' inputs of the actor.
To take a closer look, double-click the center of the Arduino Firmata actor. You'll see something like this in the dialog that opens:
// START OF BOARD CAPABILITIESBetween START OF BOARD CAPABILITIES and END OF BOARD CAPABILITIES, is a helpful list of all the pins Arduino board that were recognized by Firmata. For each pin, it shows you what that pin can do. For example, the list above shows that PIN 2 can function as a digital input, digital output, servo output or pullup input. These lines are regarded as comments because each line starts with a double-slash ('//').
Now look at the PINS 14 through 19 in this list. You'll see that these offer analog input, but that these pin numbers do not match the name shown on the physical Arduino board (A0, A1, etc.). Here, you simply need to know that first analog input (pin 14) corresponds to A0 on the board, the second corresponds to A1, and so on.
Now we come to the AUTOMATICALLY GENERATED PIN SPECIFICATION which was generated as a result of triggering the 'gen spec' input. The precise defintion of the format for these PIN specifications is below, but hopefully you can already see that Firmata will use PIN 14 for analog input (A0 on your Arduino) and PINS 2, 3 and 4 for the digital outputs.
But here we have a little problem, because you connected your LEDs to pins 5, 6, and 7 of your Arduino board, not pins 2, 3 and 4. To fix this, change PIN 2, PIN 3, and PIN 4 to PIN 5, PIN 6, and PIN 7 in the specification. Once you've done this, you can click the OK button to close the dialog.
If you like, you can also edit the first bit of text you see between the double-quotes. This is the name of the input or output as display by the Arduino Firmata actor.
Given our hardware setup we described in this example, you should now be able to turn the LEDs on and off using the actor inputs labeled "pin X: digital output" and see the value coming from Arduino pin A0 at the actor output labeled "pin 14: analog input".
We hope that this example makes the use of the 'gen spec' input clear, and will allow you to easily create your own specifications for your Arduino hardware setup.
To send or receive data using the Ardunio Firmata actor, you must provide a specification that defines which pins on the Arduino are inputs and outputs, and the the type of data input or output from that pin. The specification follows the following format
PIN NUMBER ["name"] TYPE DIRECTION [MINIMUM MAXIMUM [INIT_VALUE]] ["help"]
(Parameters in square brackets are optional.)
The meaning of these parameters is as follows:
| PARAMETER | DESCRIPTION |
|---|---|
| PIN | Each specification line must begin with the word 'pin'. |
| NUMBER | The integer number of the pin on the Arduino, from 1 to 128. |
| "name" | Optional property name enclosed in double-quotes. This will be displayed by the corresponding actor input or output. |
| TYPE | One the following: DIGITAL, ANALOG. Indicates the type of data the pin will send or receive. | DIRECTION |
Either INPUT or OUTPUT. This parameter indicates whether the Arduino pin will receive input or send output. Each Arduino INPUT pin you define will generate in a corresponding output on this actor. Each Arduino OUTPUT pin you define will generate an input on this actor. When you pass a value to one of the actor inputs, it is sent out of the corresponding Arduino OUTPUT pin. When a new value arrives at one of the Arduino INPUT pins, it will be sent to the corresponding actor output. |
| MINIMUM | (Optional) The integer minimum value for the corresponding actor input or output. |
| MAXIMUM | (Optional) The integer maximum value for the corresponding actor input or output. |
| INIT_VALUE | (Optional) The integer initialize value for the corresponding actor input. If you specify this value for an actor output (i.e., an Arduino INPUT PIN), it is ignored |
| "help" | The help string for that will be displayed in the information view for this input or output, enclosed by double-quotes. |
The examples below define two input pins and one output.
// Here is an example pin specification for the Arduino Firmata actor
pin 1 "a in" input analog 0 255 0 "This is the analog input from A0 on the Arduino."
pin 2 "dig in" input digital "This is the digital input from pin 2 on the Arduino."
pin 3 "a out" output digital "This is the digital output to pin 3 of the Arduino"