Basic tutorial on Firefly.

1. Getting Started with Firefly
The City University of New York
Architectural Technology Dept.
written by Anthony Gonzalez

2. GettingStartedwithFirefly
2
Introduction
Firefly is a suite of software tools written for the
Grasshopper plug-in that enable you to drive
parametric values through sensor data via an Arduino
microcontroller. In addition to slaving parameters of a
GrasshopperdefinitiontothatofanArduino-connected
sensor (or creating a mathematical relationship
between a sensor measurement and a controlled
parameter), Firefly also enables parameters to behave
as outputs that drive actuation (eg. motors, LEDS,
etc.). Thus, using Firefly, there is potential for two-way
communication where not only can you determine the
state of external physical conditions and use that data
to construct and/or manipulate responsive virtual
models, you can also use those same virtual models
and their parameters as outputs that control the state
of responsive physical environments.
The Firefly Installation files are available at http://
www.fireflyexperiments.com/download

3. GettingStartedwithFirefly
3
Preparing for Firefly Communication
Assuming you have already installed the Arduino
IDE and your Arduino board is currently connected
to your workstation, you must now upload the Firefly
Firmata sketch to the Arduino board. Firmata is what
is described as a “generic protocol for communicating
with microcontrollers from software on a host
computer.” In other words, by uploading the Firefly
Firmata sketch you are essentially embedding a
prewritten program onto the Arduino board that allows
Firefly to both read from and write to the Arduino’s pins.
Once uploaded, you can move away from the Arduino
IDE and create all programmatic behavior through the
visual programming language of Grasshopper.
The Firefly Firmata is available at http://www.
fireflyexperiments.com/download

4. GettingStartedwithFirefly
4
The Firefly Toolbar
Fig. 1 shows the Firefly toolbar as it is in Grasshopper.
As you can see, Firefly actually adds more functionality
to Grasshopper than just Arduino communication.
As seen in Fig. 1, Firefly provides components to
interface with audio input, send & receive data over a
network, and even open up a webcam feed. However,
the components we are concerned about here are
in the panel to the far left (shows in Fig. 2). These
are components specifically related to your Arduino
microcontroller (ignore the Wii object). Depending on
the model of Arduino board you are using, the most
important component to become familiar with is
either the UNO or MEGA component along with its two
variations: READ and WRITE.
Fig. 1 -Firefly Toolbar
Fig. 2 -Firefly Toolbar

5. GettingStartedwithFirefly
5
The Virtual Arduino
The functionality of the physical Arduino board
(specific pins behaving as either INPUTS or OUTPUTS)
is virtually represented within Firefly as two separate
components (as shown in Fig. 3 & Fig. 4).
Through this simple binary implementation, Firefly
has already designated which pins on the Arduino
board can behave as INPUTS (those assigned to
the ‘Read’ component) and those pins which can
behave as OUTPUTS (those assigned to the ‘Write’
component). While this limits a certain amount of
flexibility in choosing which pins behave in which
manner (like when coding in the Arduino IDE), with
this “hard-coded” approach conflict is averted and the
extra step of assigning behavior to the specific pins
you plan to use is eliminated. Notice in the ‘Read’
object, all six analog pins are available to read, which
makes perfect sense since analog pins are meant
for sensing (measuring voltage) and even in the
Arduino IDE voltage values other than HIGH or LOW
cannot actually be written to analog pins. In addition
to interfacing with analog pins, the ‘Read’ component
interfaces with three digital pins: DPin2, DPin4, and
DPin7. Now look at the ‘Write” component and notice
the absence of analog pins (perfectly legitimate)
and the inclusion of nine digital pins: DPin3, DPin5,
DPin6, DPin8, DPin9, DPin10, DPin11, DPin12, and
DPin13. Digital pins 2, 4, 7 are excluded from the
‘Write’ component because they have already been
designated by Firefly as INPUTS (by their inclusion in
the ‘Read’ component). When wiring, make sure to
note that digital pins 0 and 1 are reserved for serial
communication and are not represented in either the
‘Read’ or ‘Write’ components.
Fig. 3 -Uno Read Component Fig. 4 -Uno Write Component

6. GettingStartedwithFirefly
6
Reading & Writing to Pins
While the ‘Read’ and “Write’ components are
critical to interfacing with the Arduino board, in
turn, these components depend on other smaller
components in order to operate properly. Before any
kind of communication can take place between the
Arduino board and Grasshopper (or any other piece
of software) a serial port must be opened for that
communication to take place.
The ‘Open Port’ component (shown in Fig. 5)
establishes and opens a port over which
communication will take place between the Arduino
board and Grasshopper. This component requires
three input parameters: Open, Port, and Baud. Open
accepts a “Boolean” value (True or False) which is
easiest to interface with using the “Boolean Toggle”
parameter (under Params > Special) while Port and
Baud accept “Integer” parameters (under Params >
Primitive). The significance of each parameter is self
explanatory: the “Boolean” opens and closes the
connection respectively, the Port “Integer” tells the
component which communication port the Arduino
board is actually connected to, and the Baud “Integer”
tells the port at what transmission speed to operate
(this rate must match the rate defined in the Firefly
Firmata sketch which by default is 115200). The
number assigned to the communication port used by
your Arduino board can be determined in two different
ways: using the Device Manager or through Firefly’s
“Ports Available” component (shown in Fig. 6).
Fig. 5 -Open Port Component Fig. 6 -Ports Available Component

7. GettingStartedwithFirefly
7
Reading & Writing
Uno Read
Once you have determined the correct port number,
have entered that number into the “Integer”
parameter connected to the “Open Port” component,
and have set the Open property of that component
to True, you are now ready to begin communicating
with the Arduino board. Let’s look at the “Uno Read”
component again (shown in Fig. 7).
Although you have already established and opened a
port over which communication between the Arduino
board and Grasshopper can take place, both the
“Uno Read” and “Uno Write” components require a
clear directive to actually begin utilizing that open
port. This directive is defined through two required
input parameters: Start and Port. The Start input
expects a “Boolean” value and the Port input expects
an “Integer” value (naturally, the corresponding port
number of the line of communication you have already
opened in the “Open Port” component). In addition to
initializing the “Uno Read” component, you must also
define how often to check for updated values from the
Arduino board. This is accomplished by connecting a
“Timer” object directly to the “Uno Read” component.
The “Timer” object sends pulses at a set interval (in
this case every 20ms) to the “Uno Read” component,
which essentially command the component to retrieve
new values for each of the Arduino board’s input pins.
Now let’s set our “Boolean Toggle” to True and connect
some text panels to our component outputs for some
feedback and… you’re now reading values from our
Arduino board’s input pins (as shown in Fig. 8).
Fig. 7 -Uno Read Component Fig. 8 -Uno Read Component

8. GettingStartedwithFirefly
8
Reading & Writing
Uno write
Using the “Uno Read” component you’ve now used
Firefly as an input to retrieve data from the Arduino
board’s output pins. With this data, you can drive
any parameter of your Grasshopper definition in any
manner that you desire. The counterpart to “Uno
Read” is the “Uno Write” component (shown in Fig. 9)
which allows you to use Firefly as an output that can
send data to the Arduino board’s input pins.
If you remember how to initialize and begin sending
pulses to the “Uno Read” component, then you’ll have
no trouble getting the “Uno Write” component up and
running. Notice the two input parameters Start and
Port as well as the “Timer” object connected directly
to the “Uno Write” component. The obvious difference
here is the number of inputs available, which
correspond to the pins you can control on the Arduino
board from Grasshopper. Each digital pin input
parameter (eg. DPin13) expects either a “Boolean”
or “Integer” value. As in most if not all programming
languages, True evaluates to 1, False evaluates to
0, and vice versa. In addition, any non-zero integer
evaluates to True.
Taking a closer look at the input parameters of “Uno
Write” you’ll notice a small variation on specific digital
pins, specifically the tilde (~). The tilde defines pins
that can be used for either digital input (0 or 1 / false
or true) or PWM (pulse width modulation). In brief,
PWM uses square waves to simulate analog values
by modulating the time the signal is high by the time
the signal is low. These pins can accept integers other
than 0 or 1 and are great for fading LED’s, controlling
motors, etc. By right-clicking the input parameters you
can set how each digital pin should behave (shown in
Fig. 10).
The Out output parameter is included here in order
to demonstrate that the “Uno Write” component
continually writes data to all of the Arduino board’s
input pins regardless of whether you are actually
changing one or all of the “Uno Write” input
parameters.
Fig. 9 -Uno Write Component
Fig. 10 -Set Pin to PWM