Firefly Primer 1.003

FIREFLY Firefly Version 1.
003
CONNECTING ARDUINO + GRASSHOPPER
PRIMER BY JASON K JOHNSON AND ANDREW PAYNE
Firefly Primer - Firefly Version 1.003
By Jason K Johnson and Andrew Payne
Copyright 2010 All Rights Reserved
For use with Grasshopper (build 0.7 or higher)

Last Modified: August 29, 2010 2:49 PM
Check for updates to this Primer at:

www.fireflyexperiments.com
Firefly Primer - Firefly Version 1.003 - Page 2

Introduction
Firefly is a new set of software tools dedicated to bridging the gap between digital and physical
worlds. It allows near real-time data flow between Grasshopper (a parametric modeling plug-in
for Rhino) and the Arduino micro-controller. It will also read/write data to/from internet feeds,
remote sensors and more. What makes Firefly unique is its capacity to turn a traditionally
static digital architecture model into a “live” interface that is in constant communication with
the complex dynamics of the physical world. Sensors and actuators embedded in architectural
space (models, environments and more) can be modulated, controlled and prototyped using
the Firefly / Grasshopper interface.
The Firefly toolbar, Primer and several example files were released in conjunction with the
AA/CCA Biodynamic Structures Summer 2010 Workshop hosted by the CCA in San Francisco
in July 2010. Over the course of the workshop Firefly was beta-tested by over 40 participants.
Although we have worked for months to design, build and test Firefly, we are excited to have
the opportunity to share it with a larger user group. We encourage you to e-mail us comments,
corrections and suggestions: info@fireflyexperiments.com
Thanks and we look forward to hearing from you!
Jason Kelly Johnson

Future Cities Lab / CCA Architecture, San Francisco CA.
www.future-cities-lab.net; www.cca.mlab.net
Andrew Payne
LIFT Architects / Harvard GSD, Cambridge MA.
www.liftarchitects.com
Technical Collaborators:
Robert Lee has made critical contributions to the Firefly project. We want to thank him for his
continued support. A full list of acknowledgements is listed on the Firefly blog.
Image courtesy of: http://www.firefly.org/images/

Ideas
“The apparent veil between the organic and the manufactured has crumpled … What should
we call that common soul between the organic communities we know of as organisms and
ecologies, and their manufactured counterparts of robots, corporations, economies, and
computer circuits? I call those examples, both made and born, “vivisystems” for the lifelikeness
each kind of system holds.”
-Kevin Kelly, Out of Control
“If architects designed a building like a body, it would have a system of bones and muscles and
tendons and a brain that knows how to respond. If a building could change its posture, tighten
its muscles and brace itself against the wind, its structural mass could literally be cut in half.”
-Guy Nordenson, Princeton University / Nordenson and Associates
“We foresee the possibility that most (if not all) architectural space will become responsive
and be animated through intelligent kinetic capacities. Each space will have a series of sensors
which allow the occupational patterns within the space to be registered and fed back into
the intelligent responsive structures. This can operate on many scales and levels. I think what
emerges is a new era within architecture, or between architecture and some other disciplines
…”
-Patrick Schumacher (from an interview conducted by Alessandra Belia on 10 Feb 2004)
“First we build the tools, and then they build us.”

-Marshall McLuhan
Images: Kuka fabrication robot, Aegis Wall, MIT Senseable Cities Lab,
Makerbot personal fabricator, Usman Haque, Future Cities Lab
Table of Contents
Section Contents Page
INTRODUCTION 03
Table of Contents 05
1.0 GETTING STARTED > INSTALLATION 06

Rhino, Grasshopper, Firefly (.gha) Install 06
Arduino, Blink, Firefly Firmata (.pde) Upload 07
2.0 FIREFLY TOOLBAR + COMPONENTS 08

2.1 Open Port 09
2.2 Duemilanove Read 10
2.3 Duemilanove Write 11
2.4 Mega Read 13
2.5 Mega Write 13
2.6 Generic Serial Read 14
2.7 Generic Serial Write 15
2.8 Pachube Read 16
2.9 Wii Nunchuck 17
2.10 Binary Blink 18
2.11 Buffer 19
2.12 Constrain Values 20
2.13 Data Log 21
2.14 Fader One-Way 22
2.15 Fader Two-Way 22
2.16 Playback 23
2.17 Smoothing 24
2.18 Additional Components (Boolean, Slider, Tracker, Remap, Panel, ) 25
3.0 FIREFLY TUTORIALS 28

3.1 Tutorial 01: Basic Reading and Writing 28
3.2 Tutorial 02: Pachube 31
3.X Tutorial 03: GH / Light Sensors + LED Field
3.X Tutorial 04: GH Structural Analysis using Flex Sensors
3.X Tutorial 05: Wind Analysis
3.X Tutorial 06: Wii, Reactavision and other peripherals
Coming soon !
4.0 BASIC ELECTRONICS
4.X Arduino Hardware Overview
4.X Arduino Programming Overview; Hacking the Firefly Firmata (.pde)
4.X Sensors - Analog and Digital
4.X Actuators - Servos, Motors, LEDS
4.X Techniques - Prototyping, Soldering, etc.
4.X Fritzing for Arduino Visualization
5.0 ADDITIONAL RESOURCES 34

5.1 Hardware Suppliers and Related Software 34
5.2 Recommended Web Resources 35
5.3 Recommended Books and Readings 36
6.0 FIREFLY COMMUNITY - Share, Comment, Help 37

1.0 GETTING STARTED > INSTALLATION
First Steps > Dowload and Install Software
You will need to install the following software packages/plug-ins to use Firefly. For Steps 04-05 you will need an
Arduino board and USB cable. For the the purposes of these introductory tutorials we are assuming that you
will be using the Arduino Duemilanove board. Support for other boards will be published in the next version of
the Firefly Primer.
///////////////////////////////////////////////////////
Step 01. Rhino Version 4 - Service Release 8

Download the latest version of Rhino: http://www.rhino3d.com/download.htm
You must have Service Release 8: http://download.rhino3d.com/en/Rhino/4.0/sr/download/
///////////////////////////////////////////////////////
Step 02. Grasshopper (Build 0.7 or higher)

Download the latest build: http://download.rhino3d.com/en/Grasshopper/1.0/wip/rc/download/
///////////////////////////////////////////////////////
Step 03. Firefly (Build 1.002)

Download the latest build, Firefly Primer, and resources: http://www.fireflyexperiments.com
Copy/Paste the file named “Firefly_1.003.gha” into the following folder:
C:\Program Files\Rhinoceros 4.0\Plug-ins\Grasshopper\Components
Confirm the installation: Launch Rhino 4.0 SR8; Type “grasshopper” in the Command prompt; Once
Grasshopper has launched in a new window - confirm that the Firefly tab has been added (see image below).
Congratulations you have installed the Firefly plug-in!!!
Firefly Tab

Step 04. Arduino 0018 Software + Install the Drivers + “Blink” your Arduino Board
Download the latest version: http://www.arduino.cc/en/Main/Software
* If you are using a Mac OSX we recommend that you install Arduino 0018 on the Windows side.
Follow these instructions closely and complete steps #1-6: http://arduino.cc/en/Guide/Windows

A few seconds after the upload finishes, you should see the pin 13 (L) LED on the board start to blink (in
orange). If it does, congratulations! Your Arduino is up-and-running!
Blink Me !!!
USB
Note: If you are having Arduino installation problems visit: http://arduino.cc/en/Guide/Troubleshooting
///////////////////////////////////////////////////////
Step 05a. Firefly Firmata (Build 1.003)

Download the latest Firefly Firmata: http://www.fireflyexperiments.com
Copy/Paste the folder named “Firefly_DUEM_Firmata_1003.pde” into your Arduino Sketchbook folder:
My Documents\Arduino or Username\Documents\Arduino
Note: The first time you run the Arduino software, it will automatically create a directory for your Sketchbook.
You can view or change the location of the sketchbook location with the File > Preferences dialog. The sketches
in your sketchbook can be opened from the File > Sketchbook menu or from the Open button on the toolbar.
Step 05b. Upload Firefly Firmata to your Arduino Board

a. Launch the Arduino 0018 Application
b. Open the Firefly Firmata sketch: File > Sketchbook > “Firefly_DUEM_Firmata_1003.pde”
c. Select your Board: Tools > Board > Arduino Duemilanove (w/ ATmega 328)
d. Select your Serial Port: Tools > Serial Port > COM# (choose one that is available; remember the Port #)
Upload Button
e. Upload the Program: Simply click the “Upload” button. Wait a few seconds - you should see the RX and TX
leds on the board flashing. If the upload is successful, the message “Done uploading.” will appear in the status
bar. You will keep the USB connected to the Arduino - this is how Firefly will communicate with the sensors,
motors and LEDS connected to the board.
Congratulations - your Arduino board is now ready to communicate with Grasshopper / Firefly!!!

2.0 FIREFLY TOOLBAR + COMPONENTS
Firefly Toolbar
BOARDS
Duemilanove Read - read values on all digital and analog Arduino DUEM pins
Duemilanove Write- write values on all digital and analog Arduino DUEM pins
Mega Read - read values on all digital and analog Arduino MEGA pins
Mega Write - write values on all digital and analog Arduino MEGA pins
SerialRead - Retrieve a value coming over the serial sort
SerialWrite - Write a string value to the Serial Port
Open Port - open the serial port, set the port number and the baud rate
OTHER INPUTS
Pachube Read - Read a file from a Pachube Internet feed (www.pachube.com)
Wii Nunchuck - read all sensor values from a Wii Nunchuck
UTILITY
Binary Blink - oscillates 0’s and 1’s based on an incoming pattern of integers
Buffer - Store the last number of values based on the buffer domain
Constrain Values - constrains a number to specific numeric range
Data Log- create a log for incoming data
Fader One-Way - fade between one value to another based on a time interval
Fader Two-Way - fade between a min and max value based on fade in /out
Playback - the playback component will retrieve values from a text file (.txt, .csv, and .dat)
Smoothing - Smooth (or average) an incoming value Firefly Primer - Firefly Version 1.003 - Page 8
2.1 Open Port
A
Step 01. Set the Step 02. Toggle
Port number Open to “True”
Firefly > Boards > Open Port
The Open Port component allows you to establish the connection between the Arduino and Grasshopper. First,
confirm the communication Baud Rate (Since 9600 works for just about everything - beginners can skip this
step!). Second, Set the Port Number [A] and then Open or Close the Serial Port Connection using a True/False
Toggle [B] [False = Port Closed; True = Port Open]. The Firefly Duemilanove Read/Write and Mega Read/Write
components will only send/receive data if the port is open.
Note: Always close the serial port before closing your Grasshopper sketch. If you do not close your port then the
next time you open the file you will encounter a pop-up screen with a whole series of nasty errors messages!
* You can use multiple Open Port components to connect multiple Arduino boards to Firefly.
Description of Component Input/Output Parameters
Input parameters:
Open (Boolean) Boolean (True/False) value to Open or Close the Serial Port
Port (Integer) The Port Number has to be the same Serial Port assigned in the Arduino Sketch. You can find
which COM port [C] you are using by clicking on the Tools>Serial Port button on the Arduino IDE (see below).
Baud (Integer) The BaudRate value should match the speed set in the Arduino sketch. Standard values: 4800,
9600, 14400, 19200, 28800, 38400, 57600.
Output parameters:
Msg (String) Current status of Serial Port
Locating your Serial Port COM# within the Arduino PDE
Arduino: Tools > Serial Port > COM #

2.2 Duemilanove Read
Firefly > Boards > Duemilanove Read
The FireFly Duemilanove Read component will read values for all corresponding digital and analog pins on the
Arduino Duemilanove, Diecimilla, or Lillypad board. Note: This component is meant to be used in tandem with
the FireFly Duemilanove Arduino program (a .pde file) which can be downloaded from the Firefly website at:
[A] Port: This should match the Port number that you first established in the Open Port component
Input Parameters:
Start (Boolean) Input an Boolean value (True/False) to start receiving values from the Arduino
Port (Integer) The Port Number has to be the same Serial Port assigned in the Arduino Sketch.
Timer (Boolean) Set a Boolean Toggle to turn the timer on (True) or off (False)
Rate (Integer) Time interval (ms) to wait after the solution has been expired. The default is for the timer to up-
date at its fastest possible rate. It you only want to read your sensors every 2 seconds you would enter “2000”
here, or every half second would be “500”, etc.
Output Parameters:
APin0 (Integer) Incoming sensor value from Analog In Pin 0
DPin2 (Integer) Incoming sensor value from Digital In Pin 2

2.3 Duemilanove Write
Firefly > Boards > Duemilanove Write
The FireFly Duemilanove Write component will write values for all corresponding digital pins on an Arduino
Duemilanove, Diecimilla, or Lillypad board. Note: This component is meant to be used in tandem with the Fire-
Fly Duemilanove Arduino Sketch (a .pde file) which can be downloaded from the Firefly website at:
Note: The current Firefly Firmata build assigns Digital (PWM) Pins 9, 10, and 11 for use with Servo engines,
and Digital Pins 3, 5, 6 are dedicated to Digital (PWM) for LEDS etc. All other Digital Pins can be used for Digital
Write (HIGH/LOW).
[A] Port: This should match the Port number that you first established in the Open Port component
Input parameters:
Start (Boolean) Input an Boolean value (True/False) to start writing values to the Arduino
DPin13 (Integer) Integer to write to Digital Pin13. The integer (0) will send a LOW value and a (1) will send a
HIGH value.
HIGH value.
DPin11* (Integer) Integer to write to Digital Pin 11. If the PWM button is not checked, then the integer (0) will
send a LOW value and a (1) will send a HIGH value. If the PWM button is checked, then any PWM value be-
tween 0-255 can be sent to the specified pin.
HIGH value.
Output parameters:
Out (String) Returns the string that will be sent to the Arduino board. The Arduino sketch that accompanies
this component will split this string up and send the values to the appropriate pins.
Arduino Diecimila / Duemilanove Overview
The Arduino Duemilanove (“2009”) is a microcontroller board based on the ATmega168 or ATmega328. It has
14 digital input/output pins (of which 6 can be used as PWM outputs), 6 analog inputs, a 16 MHz crystal oscil-
lator, a USB connection, a power jack, an ICSP header, and a reset button. It contains everything needed to sup-
port the microcontroller; simply connect it to a computer with a USB cable or power it with a AC-to-DC adapter
or battery to get started.
“Duemilanove” means 2009 in Italian and is named after the year of its release. The Duemilanove is the latest
in a series of USB Arduino boards; for a comparison with previous versions, see the index of Arduino boards.
For more info: http://arduino.cc/en/Main/ArduinoBoardDuemilanove

2.4 / 2.5 Mega Read / Write
Firefly > Boards > Mega Read / Write
The FireFly Mega Read and Write component will read and write values to all corresponding digital and analog
pins on an Arduino Mega board. Note: This component is meant to be used in tandem with the FireFly Mega
Arduino Sketch which can be downloaded from the Firefly website at: www.fireflyexperiments.com
This component is recommended for advanced users only. The Arduino Mega has 54 digital input/output pins
(of which 14 can be used as PWM outputs), 16 analog inputs and more. Detailed specs can be found here:
http://arduino.cc/en/Main/ArduinoBoardMega
Digital Pins 2,3,4,5,6,7 can fade LEDS (PWM option must be selected)
Digital PWM Pins 8,9,10,11,12,13 are capable of controlling Servos (PWM option must be selected)
Digital Pins 22,23,24,25,26,27,28,29,30,31,32,33 can control digital LEDS (on/off)
Arduino Mega microcontroller Firefly Primer - Firefly Version 1.003 - Page 13

2.6 Generic Serial Read
Firefly > Boards > Generic Serial Read
Retrieve a value coming over the Serial Port from the Arduino board.
Input parameters:
Start (Boolean) Input an Boolean value (True/False) to start receiving values from the Arduino. Note: You must
first open the serial connection by using the Open Port component (Firefly/Boards/Open Port) before setting
the Start input value to True.
which COM port you are using by clicking on the Tools>Serial Port button on the Arduino IDE.
Timer (Boolean) Set a Boolean Toggle to turn the timer on (True) or off (False)
Output parameters:
Out (String) The incoming value from the serial connection.
Note for Advanced Users:

To see how the Generic Serial Component works upload the following code to your Arduino and you will then
be able to read the text coming over the Serial Port (exactly like the example illustrated above.)
void setup() {
// initialize serial communications at 9600 bps:
Serial.begin(9600);
}
void loop() {
Serial.println(“This message is being sent from the Arduino!”);
delay(100);
}

2.7 Generic Serial Write
Firefly > Boards > Generic Serial Write
Write a string value to the Serial Port.
Input parameters:
Start (Boolean) Input an Boolean value (True/False) to start writing values to the Arduino. Note: You must first
open the serial connection by using the Open Port component (Firefly/Boards/Open Port) before setting the
Start input value to True.
Data (String) String to write to the Serial Port
Output parameters:
Out (String) Returns the string that will be sent to the Arduino board.

2.8 Pachube Read
Firefly > Other Inputs > Pachube Read
Read a file from a Pachube feed. Pachube (http://www.pachube.com ) allows you to store, share and discover
real-time sensor, energy and environment data from objects, devices and buildings around the world. Pachube
is a convenient, secure and scalable platform that helps you connect to and build the internet of things.
(Quoted from Pachube.com). *See the Pachube Read Tutorial in section 3.2 of this Primer
Input parameters
Feed (String): Pachube web address of feed.
API Key (String): Users API Key
Output parameters
csv (String) Returns the CSV output from a given csv pachube feed.
Msg (String) Returns the title and timestamp for the retreival of the pachube feed
ID (String) Returns the XML ID of each element in a pachube feed
Tag (String) Returns the XML Tag of each element in a pachube feed
Min (String) Returns the minimum value of each element in an XML pachube feed
Max (String) Returns the maximum value of each element in an XML pachube feed
Val (String) Returns the current value of each element in an XML pachube feed
Unit (String) Returns the units of each element in an XML pachube feed
2.9 Wii Nunchuck
Firefly > Other Inputs > Wii Nunchuck
This component will allow you to read all of the sensor values from the Wii Nunchuck. Note: This component is
meant to be used in tandem with the Wii Nunchuck Arduino Sketch which can be downloaded from the Firefly
website at: www.fireflyexperiments.com
Input parameters:
Start (Boolean) Input an Boolean value (True/False) to start receiving values from the Arduino. Note: You must
first open the serial connection by using the Open Port component (Firefly/Boards/Open Port) before setting
the Start input value to True.
Output parameters:
AccX (Integer): Returns the accelerometer X value
AccY (Integer): Returns the accelerometer Y value
AccZ (Integer): Returns the accelerometer Z value
JoyX (Integer): Returns the joystick value of the X-axis
JoyY (Integer): Returns the joystick value of the Y-axis
Zbut (Integer): Returns the status of the Z button
Cbut (Integer): Returns the status of the C button
Msg (String): Current status of Serial Port
WiiChuck Arduino Adapter Kit:

http://www.sparkfun.com/commerce/product_info.php?products_id=9281
http://todbot.com/blog/2008/02/18/wiichuck-wii-nunchuck-adapter-available/
2.10 Binary Blink
Firefly > Utility > Binary Blink
Oscillates 0’s and 1’s based on an incoming pattern of integers
Input parameters:
P (Integer): The blink pattern is a list of integers that will determine the time interval (ms) between the
oscillating output of zero’s or one’s. For instance, a blink pattern of ‘100,200,300,400’ will first output a zero for
100ms, then a one for 200ms, then back to a zero for 300ms, and finally another one for 400ms. If the repeat
toggle has been set to true, this blinking pattern will continue. The smallest time interval that is currently
accepted in the blink patter is 25ms.
S (Boolean): Start/Stop Boolean toggle
R (Boolean): Repeat Pattern
Output parameters:
B (Integer): Binary Output of 0’s and 1’s
Binary Blink is one of the simplest ways to confirm that Firefly

and the Arduino board are communicating correctly. In the
image (right) the long leg (+) of an LED is inserted into Pin13
and the short leg (-) is inserted into GND.

2.11 Buffer
Firefly > Utility > Buffer
Store the last number of values based on the buffer domain
Input parameters:
V (Number) Incoming value
D (Domain) Target Domain to store data in the buffer.
Output parameters:
V (Number) The list of buffered values
Mn (Number) The minimum value in the buffer
Mx (Number) The maximum value in the buffer

2.12 Constrain
Firefly > Utility > Constrain
Constrains a number to a specific numeric range.
Input parameters:
Val (Number) Incoming value
Min (Domain) Domain to constrain values
Output parameters:
Val (Number): Constrained Value

2.13 Data Log
Firefly > Utility > Data Log
Create a log of incoming data.
Input parameters:
V (String) The incoming data to track
R (Boolean) Reset the log of values
T (Boolean) Start recording values into the data log
W (Boolean) Wrap index to list bounds. If the Wrap value is set to true and the incoming log value exceeds the
length limit, then it will begin re-recording over the previous values from index number zero.
L (Integer) Set the number of values you wish to store in the data log. If an length of zero is set, then the data
log will record values indefinitely (or until you stop the recording).
P (String) Optional file path in your directory to stream the data log
Output parameters:
O (String) The output log of data

2.14 / 2.15 Fade One / Two Way
Firefly > Utility > Fade One Way
Fade between one value to another based on a time interval (ms). These are great components to fade LEDS or
pulsing motors using timed intervals.
Firefly: Utility > Fade Two Way
Fade between a minimum and maximum value based on the fade in and fade out time interval (ms).
Input parameters:
V1 (Integer) The minimum value for the fade
V2 (Integer) The maximum value for the fade
T or T1 (Integer) The time interval (ms) to fade from the minimum value to the maximum value. The smallest
time interval that will be accepted is 100ms.
T2 (Integer) The time interval (ms) to fade from the maximum value to the minimum value. The smallest time
interval that will be accepted is 100ms.
D or D1 (Integer) A time delay (ms) to wait before after the value has reached the maximum value but before it
starts the fade back to the minimum value.
D2 (Integer) A time delay (ms) to wait before after the value has reached the minimum value but before it
starts the fade back to the maximum value.
S (Boolean) Start/Stop Boolean toggle
Output parameters:
O (Integer) Fading Output

2.16 Playback
Firefly > Utilities > Playback
The Playback component will retrieve values from a text file (acceptable file types: .txt, .csv, and .dat) and will
begin returning individual values at a given frame rate(s). You can input multiple framerates to simultaneously
keep track of multiple outputs at different intervals
Input parameters:
P (String) File path(s) to monitor. The playback will remove any timestamp values from the original file.
Acceptable file types include .txt, .csv, and .dat
S (Boolean) Start/Stop Boolean toggle
F (Integer) Frame rate (ms) to the return each value from the file. Currently the smallest frame rate allowed is
25ms.
R (Boolean) Repeat Playback pattern
Output parameters:
O (String) The playback output values

2.17 Smoothing
Utility > Smoothing
Smooth (or average) an incoming value based on a sampling level. In the illustration above, the raw APin0
sensor value is 673. APin0 is connected to the V parameter. A text Panel holding the number 10 (generally
anything between 10-20 works well) is connected to the N parameter. On the right side of the Smooth
component you can see a text Panel holding the smoothed value of 673.0.
A comparison of the two Value Tracker graphs (above right) best illustrates how effective the smooth
component can be when reading analog sensors like Photoresistors, IR proximity sensors, Accelerometers, etc.
The graph above (B) is jagged and jittery, while the lower graph (A) is relatively smooth and flowing.
Input parameters
Val (Number): Incoming value
N (Integer): The number of samples to average
Output parameters
A (Number): A smoothed average of values.

2.18 Additional Components
Additional Components [Timer, Value Tracker, Remap Numbers and more]
These additional components are not Firefly specific components but you will use them quite often. They
come pre-packaged as a part of the standard Grasshopper build. You will utilize many of these components
when you use Firefly so it is critical that you know where to find them and how to incorporate them into your
projects. This is a just a sampling of what we consider to be the most important for beginning users - as you get
more advanced you will certainly begin to incorporate many more into your projects. If there are components
or custom clusters that you invent and you think they should be included in the next Firefly Primer - please
leave us a comment on the Firefly website: www.fireflyexperiments.com
Params > Special > Boolean Switch
Boolean Switch - Toggle a switch between TRUE / FALSE. (True outputs a 0; False outputs a 1)
Boolean Switch Description

A switch is a special interface object that allows for quick setting of individual Boolean values. You can toggle a
Switch through the Menu, or by double-clicking it. Note that switches only have output grips.
Params > Special > Number Slider
Number Slider - output a specific range of numbers by sliding a dial lef and right
Number Slider Description

A slider is a special interface object that allows for quick setting of individual numeric values. You can change
the values and properties through the menu, or by double-clicking a slider object. Sliders can be made longer
or shorter by dragging the right-most edge left or right. Note that sliders only have output grips.

Params > Special > Value Tracker
Value Tracker - Track a collection of numeric values over time
Analog values will be variable and

continuous ranging from 0 to 1023
Digital values will spike from 0 to 1
Value Tracker Description

The Value Tracker allows you to visualize incoming sensor data coming from your APins and DPins. If you right-
click on the Value Tracker component you can set the Period (width of the graph - from 1 second to 1 hour),
and you can set the Update time (this works best if you keep the default setting of “Smooth 25ms”). This is a
very handy tool to use when you are trying understand how your sensors are performing side-by-side.
Math > Domain > Remap Numbers
Remap Numbers - Remap numbers into a new numeric domain
Remap Numbers Description

This component allows to you remap incoming analog sensor data (usually 0-1023) to any numeric domain (for
LEDs this is usually 0 To 255, or for servos this is usually 0 To 180).
Input parameters:
V (Number) Values to remap
S (Domain) Optional source domain.
T (Domain) Target domain
Output parameters:
R (Number) Remapped numbers.
Params > Special > Panel
Panel - output parameters of components, or input parameters into a component (text or numbers).
Panel Description
Panels can receive their information from elsewhere. If you plug an output parameter into a Panel, you can see
the contents of that parameter in real-time. All data in Grasshopper can be viewed in this way.

3.0 FIREFLY TUTORIALS
In order to complete these tutorials you must have successfully followed all the steps outlined
in the first section of this Primer: “1.0 Getting Started > Installation”.
Download the tutorial support files at: http://www.fireflyexperiments.com
3.1 - Tutorial: Basic Reading and Writing

Introduction
For this first Firefly tutorial you will utilize the three most basic Firefly components: Open Port, Duemilanove
Read and Duemilanove Write. To begin with - your Arduino board’s USB cable should be connected to your
computer and the green “power” light should on. The “Firefly DUEM Firmata” should also be uploaded to you
board. Next you will place these three Firefly components into your Grasshopper workspace, then you will
prepare them to both read and write data over the USB serial port.
Steps 1 will cover building the actual circuit using an Arduino Board, breadboard, Servo, LEDs
Steps 2-4 will cover the process of setting GH/Firefly Open Port, Read and Write
Steps 5 will cover linking your GH/Firefly sketch to specific geometry
b. STANDARD
SERVO
a. LED
SIG
GND +
c. LED (PWM)
GND 5V
USB
+ GND
1K
10 K
d. PHOTORESISTOR
5V GND SIG
Step 1: Preparing the Arduino Breadboard Circuit
a. LED - Connect the long leg of an LED to Digital Pin 13, and connect the short leg to the second-to-last pin
maked GND. Note that Pin 13 has a built-in resistor. If you attach to any other pin you must use a resistor.
b. STANDARD SERVO - Connect a Stardard Servo to Digital Pin 9. Note that this pin is marked PWM (Pulse
Width Modulation). The standard Firefly build allows you to control servos on Digital Pins 9,10,11 only.
c. LED (PWM) - Connect the long leg off the LED to a resistor and Digital Pin 3, and the other to GND.
d. PHOTORESISTOR - Use a Photoresistor and a 10K resistor to construct the circuit pitured above. Connect the
SIG (signal) to any of your Analog In pins. The circuit above uses Analog Pin 1.
READ C WRITE
PORT
A
Step 1: Preparing Open Port
a. Drag the Open Port component to the Grasshopper workspace

b. Add a Boolean Toggle [A] to the “Open” input. When you double-click the Boolean Toggle you will activate
(True) or deactivate (False) Firefly’s ability to communicate with your Arduino.
c. Set the Serial Port Number (this should match the port COM# you used when you uploaded the Firmata). We
recommend using a Text Panel [B] (Params > Special > Text Panel) to input your port COM#.
d. Close/Toggle your Boolean to (False) for now. You will open it after you get everything else set up.
Step 2: Preparing Duemilanove Read
a. Drag the Duemilanove Read component to the Grasshopper workspace

b. Add a Boolean Toggle to the “Start” and “Timer” inputs. When you double-click the Boolean Toggle you will
activate (True) or deactivate (False) this components ability to communicate with your Serial Port / Arduino.
c. Create and connect Text Panels (Params > Special > Panel) to each of the “Read” [D] parameters (APin0
through DPin 7) and the Msg panel on the right side of the component. This will allow you to read the values
coming from sensors conected to the Arduino. In later steps we will connect these directly to specific param-
eters within a Grasshopper model to dynamically control geometries, spatial relationships, etc.
E
H J
F
G
Above - The Duemilanove Write Component (see description on the next page)

Step 3: Preparing Duemilanove Write
a. Drag the Duemilanove Write component to the Grasshopper workspace

b. Add a Boolean Toggle to the “Start” input. When you double-click the Boolean Toggle you will activate (True)
or deactivate (False) communication with your Serial Port / Arduino.
c. Create and connect Text Panels (Params > Special > Panel) to the Out and Msg [J] parameters. The Out
parameter is essentially a diagnostic tool that allows you to see what data is actually being sent through the
Serial Port to the Arduino board. This string of comma-seperated numbers is then seperated in the Arduino
Firmata (.pde) sketch and is used to control specific Arduino pins.
d. Add three unique Number Sliders to all the components on the left side of the component. Refer to the
diagram above to locate these three slider types:
[E] 0-1 Slider (Slider Type: Integer; Lower Value: 0 and Upper Value: 1)
[F] Servo Slider (Slider Type: Integer; Lower Value: 0 and Upper Value: 179)
[G] LED Slider (Slider Type: Integer; Lower Value: 0 and Upper Value: 255)
Note on DPins marked with a star* [H]: The DPin11*, DPin10*, DPin9*, DPin6*, DPin5*, Dpin3* parameters
have a “PWM” option (Pulse Width Modulation). If you right click over the DPin parameter text you will see
an option to select PWM [I]. If PWM is selected, Pins 5,6,7 can be used to fade LEDS, and Pins 9,10,11 can
control Servo Motors. These PWM pins correspond the the PWM pins indicated on the Arduino Duemilanove
board. If the PWM button is not checked, then the integer (0) will send a LOW value and a (1) will send a HIGH
value. If the PWM button is checked, then any PWM value between 0-255 can be sent to the specified pin.
Step 4: Connect Firefly to points in the Rhino File
The example (below) creates a real-time 3D map of your Analog Inputs and draws a line accross them. We
first connect the 6 outputs from the Duemilanove Read component to the Z input of a Point component
[A]. We then use a Series Component to input (0,5,10,15,20,25) into the Y input [B]. A Pline [C] is used to
connect these points and create a dynamically updating line in space. We then add another corresponding
Point component. These points will be fixed to ground plane. Again, we use the Series Component to input
(0,5,10,15,20,25) into the Y input [D]. The final step is to connect both sets of points with vertical lines [E].
C C
B
A
D
E
E
Figure 1. The Rhino modeling window (left) and Grasshopper Interface (right)
3.2 - Tutorial: Pachube Read
My Settings
Preparing the Pachube Read Component
Step 1. Setup a pachube account and find your API Key
In order to begin monitoring various sensor feeds from pachube.com, you will first need to create an account.
Begin by going to the URL: http://www.pachube.com and click on the Sign Up link at the top of the page. After
providing a unique user name, e-mail address, and password you will be directed back to the pachube home
page.
When logged in, you will notice a grey menu bar at the top of the page with various links to manage your ac-
count. On the far right hand side of this menu, you will find a link to manage “My Settings”. After clicking on
this link, you will be directed to your account settings page where you will find your API Key.
Some Pachube API methods don’t require authentication (primarily those involving syndication and those that
contain no real-time data, for example 24-hour history CSV and graphs). This enables them to be used in third-
party websites or mashups that require public access.
However, most real time data methods do require a Pachube API key. Your API Key is your personal identifica-
tion code that will be required to access many real-time feeds on pachube.
Note: Since your API Key is your personal identifier on pachube, it is crucial that you keep this code private. Do
not share this information with others and make sure you do not share Grasshopper files which may contain
your key inside the document.
Now that we have setup an account, drag and drop a Text Panel onto the canvas. Copy and paste your API Key
(from your account settings) into the Text Panel. Connect the output of this Text Panel to the API Key input
node of the Pachube Read component.

Step 2. Find a Pachube feed
There are several different methods for accessing the thousands of live realtime sensor feeds that are updated
to the pachube servers every minute. Map View allows users to find a feed based on geolocation. Tags are
color coded based on categories: agriculture, buildings, devices, energy, environment, transport, and other.
List View gives users a text based version of all online feeds. Finally, Cloud View provides a list of all feed tags
and scales the text of each tag based on the number of occurrences of each tag (larger fonts indicate the
greater number of occurrences of a given tag). We can also Search Feeds or Tags by using the search box at
the top of the page.
For this tutorial, we will use a feed created by the National Wind Technology Center in Denver, CO. Type the
following web address into your browser: http://www.pachube.com/feeds/1197 . The readings that are dis-
played are derived from instruments mounted on or near an 82 meter (270 foot) meteorological tower located
at 39° 54’ 38.34” N and 105° 14’ 5.28” W (datum WGS84) with its base at an elevation of 1855 meters (6085
feet) above mean sea level.
Each feed’s page (e.g. http://www.pachube.com/feeds/1197) lists three URLs for accessing realtime data in
various formats: CSV, JSON & EEML (an XML format). The XML file format contains the most descriptive infor-
mation about a sensor feed (including metadata), while the CSV format contains the least. Note: The Grass-
hopper Pachube Read component can only access XML or CSV file formats.
By retrieving data from one of these URLs you will access the remote environment’s most recent datastream
values and metadata (up to a resolution of 5 seconds) and can use this data to control, trigger, modulate or
otherwise affect your device, building, environment, actuator, etc.
Each feed page has a data stream link labeled ‘embed, history, triggers’ which reveal a drawer with a number
of URLs and code snippets:

URL: retrieves the realtime value of that datastream alone. We can add the extension .xml or .csv to this URL
address to isolate the current value of a single sensor data stream.
History: quick view of the last 24 hours of data in 15-minute increments, CSV format, no timestamps (total of
96 datapoints). This URL address can only be accessed by adding the .csv file extension.
Archive: complete datastream history in 15-minute increments, CSV format, includes timestamps. This URL
address can only be accessed by adding the .csv file extension.
PNG graph: HTML code snippet for embedding a configurable PNG graph of the datastream. Currently the
PNG graphs cannot be imported into Grasshopper.
Zoom graph: HTML code snippet for embedding a zoomable graph of the last 30 days of data. Currently the
Zoom graph cannot be imported into Grasshopper.
Step 3. Setting up a Pachube Read Component in Grasshopper

5.00 ADDITIONAL RESOURCES
5.1 Hardware Suppliers and Related Software

LITTLE BITS OF EVERYTHING
Adafruit [Based in NYC - Arduinos, Sensors, Wireless, DIY Central, great range of things ...]
Jameco [outside SF in Belmont, CA - Huge selection of Electronics]
RobotShop [Huge selection of robot-based electronics, SMAs, Motors, Sensors]
Al Lashers Electronics [Located in Berkeley, CA -1734 University Ave (510)843-5915]
Electronics Plus [San Rafael, CA - (415) 457-0466]
Fry’s [1077 East Arques Ave. Sunnyvale, CA, 408.617.1300 - also in Palo Alto, San Jose and more]
Marlin P. Jones [Huge Supplier including Power Supplies, LED, Connectors, etc]
ARDUINO + GENERAL ELECTRONICS SUPPLIERS

Arduino [mothership: great links to everything Arduino]
Sparkfun [sensors, hardware, kits ...]
MakerShed [sensors, hardware, kits ...]
LiquidWare [lots of everything]
POWER SUPPLIES
PowerSupplyOne [Huge Selection of Power Supplies]
SENSORS
Acroname [Sharp IR Sensor Source - we use the GP2Y0A02YK]
Making Things [Great range of Sensors - highly recommend]
Sparkfun Sensors [many flavours] Sensor Kit by Sparkfun
LadyAda [Bits and Pieces; Sensors and Arduinos and much more]
SERVOS
Servocity [Great Selection of Servos and Supplies]
LEDS
SuperBrightLEDS.com [Single LEDs or multiple strings, all types, good quality]
GOOD ARDUINO BASED STARTER KITS

+ Minimum > Arduino Budget Pack or equal [includes Arduino Duemilanove Atmega328, and a small selection
of starter components]
+ Mid-Range > Arduino Starter Pack or equal [includes Arduino Duemilanove Atmega328, Protoboard, and a
good selection of starter components]
+ High-End Recommended > Arduino Experimentation Kit v1.0 or equal [includes Arduino Duemilanove At-
mega328, Prototyping bundles, and a great selection of starter components]
Other misc. tools that you might consider purchasing: a soldering iron and solder, wire strippers, helping
hands, digital multimeter, etc. Here is a great link for info on the best tools to purchase.
[Note: These are working lists. Please e-mail us a related links and we’ll consider adding them to our lists]

5.2 Related Tech Links
LEDS
LED Circuitry Tutorial: http://www.theledlight.com/ledcircuits.html
LED Calculator: http://www.led-calculator.com/
Instructables http://www.instructables.com/
Lady Ada Tutorials http://www.adafruit.com/index.php?main_page=tutorials
SERVOS
Hacking Servos for continuous rotation: http://www.seattlerobotics.org/guide/servohack.html
5.3 Related Software Projects

Grasshopper and GH Plug-in Related
Grasshopper Home [plug-in for Rhino; Created by David Rutten and augmented by many others]
Kangaroo [Physics Engine for simulating materials]
Geometry Gym [Geometry toolkit]
ModeLab Tools [Many helpful GH tools ]
Geco [connect GH with Ecotect]
Weaverbird [smoothing, modifying and preparing meshes]
For a complete list visit: http://www.grasshopper3d.com/page/addons-for-grasshopper
Arduino Related
Arduino [obviously, but this is a key software especially to hack the Firefly Firmata!]
Processing [Arduino is based on Processing by Casey Reas and Ben Fry]
Modkit [Drag and Drop programming for Arduino]
General Related Projects

Ubimash [Uses UDP to publish and subscribe to server data; used with GC and others]
NetLabToolkit [Tools for tangible interaction using Arduino / Flash Widgets]
Fritzing [Draw, Visualize and Output Circuits Diagrams; Arduino to Breadboard - highly recommended]
[Note: These are working lists. Please e-mail us a related links and we’ll consider adding them to our lists]

5.4 Related Books and Reading
Fox, Michael and Kemp, Miles. Interactive Architecture. Princeton Architectural Press, 2009. (Amazon)
Nobel, Joshua. Programming Interactivity: A Designer’s Guide to Processing, Arduino, and Openframeworks.
O’Reilly Media, 2009. (Amazon)
Platt, Charles. Make: Electronics (Learning Through Discovery Series). Make Publishers, 2009. (Amazon)
Banzi, Massimo. Getting Started with Arduino. Make Publishers, 2008. (Amazon)
Reas and Fry. Processing - Programming Handbook for Designers. MIT Press. (Amazon)
Igoe and O’Sullivan. Physical Computing: Sensing and Controlling the Physical World with Computers. Course
Tech CPR. (Amazon)
Igoe, Tom. Making Things Talk. O’Reilly Press. (Amazon)
Image courtesy of modelab.nu/
6.00 FIREFLY COMMUNITY - Share, Comment, Help
Firefly is currently hosted at: http://www.fireflyexperiments.com We encourage you to create

discussions related to Firefly on this site.
There is also a thriving community of Arduino related enthusiasts here:

http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl
We encourage you to e-mail us comments, corrections and suggestions:

info@fireflyexperiments.com

Cover graphic courtesy of Future Cities Lab - The Aurora Project
(JK. Johnson/N. Gattegno with special thanks to C. Norman/T. Kelley)

Firefly Primer 1.003

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Firefly Primer 1.003

Uploaded by

Copyright:

Available Formats

FIREFLY Firefly Version 1.

For use with Grasshopper (build 0.7 or higher)

Check for updates to this Primer at:

Firefly Primer - Firefly Version 1.003 - Page 2

Thanks and we look forward to hearing from you!

Jason Kelly Johnson

Image courtesy of: http://www.firefly.org/images/

Firefly Primer - Firefly Version 1.003 - Page 3

“First we build the tools, and then they build us.”

Section Contents Page

1.0 GETTING STARTED > INSTALLATION 06

2.0 FIREFLY TOOLBAR + COMPONENTS 08

3.0 FIREFLY TUTORIALS 28

5.0 ADDITIONAL RESOURCES 34

6.0 FIREFLY COMMUNITY - Share, Comment, Help 37

Firefly Primer - Firefly Version 1.003 - Page 5

First Steps > Dowload and Install Software

Step 01. Rhino Version 4 - Service Release 8

Step 02. Grasshopper (Build 0.7 or higher)

Step 03. Firefly (Build 1.002)

Firefly Primer - Firefly Version 1.003 - Page 6

Follow these instructions closely and complete steps #1-6: http://arduino.cc/en/Guide/Windows

Note: If you are having Arduino installation problems visit: http://arduino.cc/en/Guide/Troubleshooting

Step 05a. Firefly Firmata (Build 1.003)

Step 05b. Upload Firefly Firmata to your Arduino Board

Firefly Primer - Firefly Version 1.003 - Page 7

SerialRead - Retrieve a value coming over the serial sort

SerialWrite - Write a string value to the Serial Port

Pachube Read - Read a file from a Pachube Internet feed (www.pachube.com)

Wii Nunchuck - read all sensor values from a Wii Nunchuck

Constrain Values - constrains a number to specific numeric range

Data Log- create a log for incoming data

Firefly > Boards > Open Port

Description of Component Input/Output Parameters

Locating your Serial Port COM# within the Arduino PDE

Arduino: Tools > Serial Port > COM #

Firefly > Boards > Duemilanove Read

Description of Component Input/Output Parameters

Firefly Primer - Firefly Version 1.003 - Page 10

Firefly > Boards > Duemilanove Write

Description of Component Input/Output Parameters

Arduino Diecimila / Duemilanove Overview

For more info: http://arduino.cc/en/Main/ArduinoBoardDuemilanove

Firefly > Boards > Mega Read / Write

Arduino Mega microcontroller Firefly Primer - Firefly Version 1.003 - Page 13

Firefly > Boards > Generic Serial Read

Description of Component Input/Output Parameters

Note for Advanced Users:

Firefly Primer - Firefly Version 1.003 - Page 14

Firefly > Boards > Generic Serial Write

Write a string value to the Serial Port.

Description of Component Input/Output Parameters

Firefly Primer - Firefly Version 1.003 - Page 15

Firefly > Other Inputs > Pachube Read

Description of Component Input/Output Parameters

Firefly > Other Inputs > Wii Nunchuck

Description of Component Input/Output Parameters

WiiChuck Arduino Adapter Kit:

Firefly > Utility > Binary Blink

Oscillates 0’s and 1’s based on an incoming pattern of integers

Description of Component Input/Output Parameters

Binary Blink is one of the simplest ways to confirm that Firefly

Firefly Primer - Firefly Version 1.003 - Page 18