Arduino General Purpose Pin Configuration

Arduinos have many available pins for connecting to other devices. These pins are modal - they can be configured to be one of many different types of pins (input, output, PWM, etc.). Many Arduino peripheral devices can be incorporated into the Virtual Wiring system using these standard pin types.

There are a set of Scripts in the Arduino PinTypes Script directory for Arduino pin naming and configuration. Running a certain Script will create a certain type of Arduino pin with user assigned terminal names and user defined Arduino pin numbers.

All the PinTypes Scripts take a common set of required parameters. The parameters define the Arduino getting the new pins, the pin names, and the Arduino pin numbers for each pin. The common parameters are as follows:

arduino_id : the ID of the Arduino which owns the pins we are adding and defining. This is the same as the ID supplied by the "id" parameter when adding an Arduino to the system.
names : a comma separated string of pin names. These names will be assigned to the Arduino terminals we are configuring.
pins : a comma separated string of pin numbers, one number for each name in the 'names' parameter.

Each Script in the PinTypes Script directory defines a different type of Arduino pin.

Configuring Analog Input Pins
Configuring Digital Input Pins
Configuring Digital Output Pins
Configuring Pulse Width Modulated (PWM) Output Pins
Configuring Schmitt Triggered Input Pins
Configuring Servo Output Pins
Configuring Shift Output Pins

Configuring Analog Input Pins

Arduino analog inputs are sampled every analog_sample_ms milliseconds (see Arduino Installation) and are sent to the Virtual Wiring System. Analog pins are defined and named using the AnalogInputs Script. In addition to the required parameters, it takes an optional set of parameters which are:

value_type : (nil/"raw"/"percent"). Determines what type of value is emitted (before any scaling). nil will emit the voltage on the pin; "raw" will emit the actual value from the A/D (0-1023); "percent" will emit the percentage of the value of its maximum value (100 * raw / 1023).
scaler : scales the analog output value to another value (see Function and Scaling Parameters)
on_change : (true/false). Determines whether the analog terminal is updated every sample period or only when its value is different from the last.

Running the AnalogInputs Script with the parameters listed below will add an analog input with a 0-100 percentage output:

arduino_id: "my_arduino"
names: "analog0"
pins:"A0"
value_type: "percentage"
on_change: true

Normally the "pins" parameter would take an Arduino pin number (1,2,3, etc.). Pin numbers are supported as analog input pin numbers, but they are somewhat undesirable. In the Arduino Firmata implementation, analog pin numbers start where digital pin numbers leave off. So for an Uno, which has 14 digital pins (starting at 0), the first analog pin number would be pin 14. For a Mega, with 54 digital pins, the first analog pin number would be pin 54. Instead of requiring board type dependent pin numbering when defining analog inputs, symbolic pin numbering (using the symbols A0, A1, A2, etc.) is also supported.

Configuring Digital Input Pins

Digital input pins accept true/false type logic values and emit on/off values on their terminals. Digital inputs are defined using the DigitalInputs Script. In addition to the required parameters, digital inputs accept the following optional parameters:

pullup : (true/false). Determines if the input is pulled up or not. Arduino inputs have an optional ~20K internal pullup resister. With digital inputs, it's generally a good idea to use pullups.
debounce : (true/false). Many digital input sources (mechanical switches, for example), "chatter" when they switch. Electrically speaking, true/false transitions are accompanied by a burst of true/false values. This phenomena, also called "switch bounce" is filtered out when the debounce parameter is true.

Running the DigitalInputs Script with the parameters listed below will add two digital input pins with pullups to the Arduino with the ID "another_arduino":

arduino_id: "another_arduino"
names: "in1, in2"
pins:"2,3"
pullup: true
debounce: false

Configuring Digital Output Pins

Digital output pins generate logic values in response to on/off values on their terminals. Digital outputs are defined using the DigitalOutputs Script.

Running the DigitalOutputs Script with the parameters listed below will add two digital output pins to the Arduino with ID "yet_another_arduino":

arduino_id: "yet_another_arduino"
names: "out1, out2"
pins:"2,3"

Configuring Pulse Width Modulated (PWM) Output Pins

Pulse width modulated pins generate PWM signals in response to 0 to 100 values, or the values "on" or "off" ("on" is the same as a value of 100, and "off" is the same as a value of 0). A value of 0 will turn the PWM pin fully off and a value of 100 will turn the the pin fully on. Values in between determine the percentage of "on" time relative to the overall period of the signal (the duty cycle). PWM outputs are defined using the PWMOutputs Script.

Running the PWMOutputs Script with the parameters listed below will add two PWM output pins:

arduino_id: "still_yet_another_arduino"
names: "pwm1, pwm2"
pins:"3,5"

Configuring Schmitt Triggered Input Pins

Analog input pins can be configured to act like Schmitt triggers. A Schmitt trigger is a device with a digital output whose state is a function of whether its input is above (on) or below (off) an analog voltage or threshold. In addition, the Schmitt trigger modifies its threshold according to its output state, so that a noisy input doesn't cause its output to oscillate. The amount of noise immunity is determined by a hysteresis value. When the output is on, the threshold will be at its center threshold minus 1/2 the hysteresis value. When the output is off, the threshold will be at its center threshold plus 1/2 the hysteresis value.

Schmitt trigger inputs are defined using the SchmittInputs Script in the PinTypes directory. Rather than define hysteresis and threshold values in terms of voltages, this implementation uses percentages, where 100% is the highest measurable voltage and 0% is the lowest (usually 0 volts).

The SchmittInputs Script takes the following optional parameters:

threshold : a 0 to 100 percentage value which sets the center point for switching. A value of 50 sets the threshold to halfway between the highest and lowest switching points.
hysteresis : a 0 to 100 percentage value which determines how much the threshold will be affected by its output state. The larger the value, the less the output will be affected by noisy inputs. If this value is too large, the output may not be affected by the signal of interest at all.

Running the SchmittInputs Script with the parameters listed below will add two Schmitt trigger input pins with a 1/4 threshold and a 10% hysteresis. They will be added to the Arduino with the ID "my_arduino".

arduino_id: "my_arduino"
names: "s1, s2"
pins: "A0,A1"
threshold: 25
hysteresis: 10

Configuring Servo Output Pins

Servo output pins are digital output pins suitable for controlling a servo. If one connects a servo to an Arduino servo output pin and puts a 0-180 value on the servo terminal of this device, the physical servo will rotate from 0-180 degrees (the actual range and rotation will be somewhat dependent on the servo).

At the time of this writing, Firmata supports the servo function on any of an Arduino Uno's lowest 12 available digital I/O pins (D2-D13). Larger Arduinos (megas) support more pins, but if you stick with using only pins D2-D13 as servo outputs, the function should work consistently across most kinds of Arduinos.

Running the ServoOutputs Script with the parameters listed below will add a servo pin to pin D2 of the Arduino with ID "arduino".

arduino_id: "arduino"
names: "servo_1"
pins: 2

Configuring Shift Output Pins

Sometimes it is necessary to serialize a data value out an Arduino pin. A common application is connecting an Arduino to a shift register. There are also many peripheral devices which interface with a serialized output. To support these devices, there are Shift Output Pins.

Shifting involves a data pin, which shifts out the data, and also a clock pin. The clock pin strobes the data into whatever device is using it. Less commonly, there is a framing pin, which frames some group of data bits with frame values. The framing pin doesn't change value while data is being clocked. A common application of a framing pin is to load data into a shift register after all the data has been clocked into it.

A Shift Output has a data pin, a clock pin, and an optional framer pin. If there is a framer pin, there are optional frame start and frame end values for the frame. The Shift Output also has parameters which tell it how to shift. It has a bit length parameter, which tells it how many data bits to shift, and a shift direction parameter, which tells it which end of a value to shift out first.

Shift Outputs are built by running the ShiftOutputs Script. The Script takes the parameters listed below. Unlike the other Scripts on this page, the ShiftOutputs Script does not have a "pins" parameter.

clock_pins: a comma separated string of pin numbers, one pin for each Shift Output.
data_pins: a comma separated string of pin numbers, one pin for each Shift Output.
num_bits: the number of bits to clock out for each value (should be a multiple of 8).
msb_first: the direction to clock the data. If msb_first is false, clocks the data least significant byte, least significant bit first. If msb_first is true, clocks the data most significant byte, most significant bit first.
framer_pins: a comma separated string of pin numbers. This can be an empty string, or it must have one pin for each Shift Output.
frame_start: an 8 bit value that is shifted out before clocking starts. Usually the frame start value is either 0xFF (frame start is a high), or 0x0 (frame start is a low). If frame start is nil, no framing will be shifted out at the start of a frame.
frame_end: an 8 bit value that is shifted out after clocking ends. Usually the frame end value is either 0xFF (frame end is a high), or 0x0 (frame end is a low). If frame end is nil, no framing will be shifted out at the end of a frame.

Note: Shift Outputs are implemented by sending bit banging commands to the Arduino, which means that they are not terribly fast. If you have a need to clock out data values larger than 32 bits, you may find that your Shift Output is introducing delays into your system. Someday, Firmata may support bit shifting, and Shift Outputs may run an order of magnitude faster.

The following parameters for the ShiftOutputs Script builds 2 Shift Outputs. When one of these Shift Outputs receives a value on its name terminal, it starts by setting its framer bit low, then it shifts out 8 bits of data (msb first), and then it sets its framer bit high. The first Shift Output (named "so1") uses pin 3 for its clock, pin 4 for its data, and pin 5 for its framer. The second Shift Output (named "so2") uses pin 6 for its clock, pin 7 for its data, and pin 8 for its framer. The Shift Outputs are added to an Arduino with ID "arduino".

arduino_id: "arduino"
names: "so1, so2"
num_bits: 8
msb_first: true
clock_pins: "3, 6"
data_pins: "4, 7"
framer_pins: "5, 8"
frame_start: 0
frame_end: 0xFF