Firefly Primer 1006

FIREFLY PRIMER BY

JASON KELLY JOHNSON AND ANDREW PAYNE

CONNECTING ARDUINO + GRASSHOPPER + MORE

Firefly Version 1.006

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

Firefly Primer - Version 1.006 By Jason Kelly Johnson and Andrew Payne Copyright 2011 All Rights Reserved For use with Grasshopper (build 0.80050 or higher) Last Modified: August 15, 2011 10:08 PM Downloads, Primer Updates and Firefly Forum: www.fireflyexperiments.com

Firefly Primer - Version 1.006 - Page 2

Introduction to Firefly 1.006 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 initially released in conjunction with the Architectural Association (London) Biodynamic Structures Summer Workshop hosted by the CCA in San Francisco in July 2010 (it also being held again in 2011 and 2012). Over the course of the workshop Firefly was beta-tested by over 40 participants. In just over one year since its release Firefly and the Firefly Primer were download over 5000 times by adventurous architects, designers, artists and engineers from all over the world. Although we have worked for months to design, build, test and refine 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: [email protected] 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 Andrew Payne LIFT Architects / Harvard GSD, Cambridge MA. www.liftarchitects.com

AA BioDynamic Structures Workshop at CCA San Francisco

Firefly Primer - Version 1.006 - Page 3

Project Credits and Collaborators Firefly was founded by Andy Payne and Jason Kelly Johnson in 2010. Andy has been primarily responsible for writing the code underlying Firefly’s various components. He has also been involved (along with Jason) with the development of the Firefly Firmata, a critical piece of open source software which enables a direct connection between the Arduino hardware and the Grasshopper environment. As of 2011, Andy is the lead researcher and developer of Firefly’s new X control tools. He is currently pursuing this research independently as a part of his PhD dissertation at Harvard GSD in Boston, MA. Jason continues to develop and support the core Firefly tools and educational primer. Jason has been active in helping to establish the connection between Firefly and the Arduino software and hardware environment. Along with the development of the Firefly Firmata, Jason has also been primarily responsible for all of the documentation and educational tutorials to date. He is currently an Assistant Professor of Architecture and Interaction at CCA in San Francisco, California. Firefly is built upon the Grasshopper plug-in for Rhino, both developed by Robert McNeel and Associates. Robert Lee has made critical contributions to early versions of Firefly. We would like to thank Prof. Panagiotis Michalatos for his generous support and guidance in the development of the Firefly_X toolset. Ronnie Parsons and Gil Akos of StudioMode (www.modelabs.nu) in New York City have also contributed to the development of some amazing example files that were released with Version 1.005. A full list of acknowledgements is listed on the Firefly blog. Andy and Jason would also like to acknowledge the input of various colleagues, students and workshop participants in the development and continued evolution of Firefly. The Arduino language syntax is based on Wiring by Hernando Barragan. The Arduino environment is based on Processing by Ben Fry and Casey Reas, and is now supported by an amazing team of software and hardware developers that continue to refine and expand its capabilities. Pachube was created by Usman Haque and his amazing team at pachube.com. The Reactivision framework is being developed by the Music Technology Group at the Universitat Pompeu Fabra in Barcelona, Spain.

Firefly Workshop at the AA BioDynamic Structures Workshop at CCA in July 2010

Firefly Primer - Version 1.006 - Page 4

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

Firefly Primer - Version 1.006 - Page 5

FIREFLY COMMUNITY - Share, Discuss, Help Firefly is currently hosted at: http://www.fireflyexperiments.com We encourage you to create discussions related to Firefly on this site and sign-up for our mailing list. There is also a thriving community of Arduino related enthusiasts here: http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl Please e-mail comments, corrections and suggestions to: [email protected]

Discussion Forum at fireflyexperiments.com

Tutorial and Project Videos at fireflyexperiments.com

Firefly Primer - Version 1.006 - Page 6

Table of Contents Section

Contents



INTRODUCTION

03

1.0

GETTING STARTED > INSTALLATION

08

2.0

FIREFLY TOOLBAR + COMPONENTS

11

2.10 2.11 2.12 2.13 2.14 2.15

OSC Listener and Sender UDP Listener and Sender Pachube Read Reactivision Listener Wii Nunchuck XML Search

22 23 24 25 26 27

2.16 2.17 2.18 2.19 2.20 2.21 2.22 2.23 2.24 2.25 2.26

Binary Blink Buffer Constrain Values Data Log Fader One-Way Fader Two-Way Playback Smoothing Wave State Detection Stop Watch

28 29 30 31 32 32 33 34 35 36 37

2.27

Additional Helpful Components (Boolean, Slider, Tracker, Remap, Panel, Timer)

38

3.0

FIREFLY TUTORIALS

40

4.0

ADDITIONAL RESOURCES Hardware Suppliers and Related Software Recommended Web Resources Recommended Books and Readings

48 48 49



2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9

3.1 3.2 4.1 4.2 4.3

Table of Contents Rhino, Grasshopper, Firefly (.gha) Install Arduino, Blink, Firefly Firmata (.pde) Upload Ports Available + Open Port Uno Read Uno Write Mega Read Mega Write Generic Serial Read Generic Serial Write Code Generator Upload to I/O Board

Tutorial 01: Basic Reading and Writing Tutorial 02: Pachube

Page 07 08 09

13 14 15 17 17 18 19 20 21

40 44

47

Firefly Primer - Version 1.006 - Page 7

1.0

GETTING STARTED

Prerequisites

In order to begin working with Firefly, you’ll want to make sure you have the following software installed on your computer: • Rhinoceros 4.0 (or 5.0 WIP beta) http://www.rhino3d.com/download.htm • Service Release 8 (for Rhino) http://download.rhino3d.com/en/Rhino/4.0/sr/download/ • Grasshopper (version 0.8 or higher) http://download.rhino3d.com/Grasshopper/1.0/wip/download/ • Arduino IDE (Integrated Development Environment) http://arduino.cc/en/Main/Software

Step 1 (Install the Firefly Toolbar - only needed once)

Download and unzip the “Firefly Build 1.006.zip“ folder: http://www.fireflyexperiments.com/download/ The first thing we’ll want to do is to copy and paste the Firefly.gha and Firefly_X.gha files (found inside the Firefly zip file) and the libTUIO.dll file into the proper Grasshopper Directory. • First, launch Rhino and type the word ‘Grasshopper’ in the command line. This will launch the GH editor. • Click on File>Special Folders> Components Folder. Delete any older versions of Firefly (either older .gha files or the libTUIO.dll) if they are already installed on your computer. • Next, open the Firefly Installation folder (in the .zip file you just downloaded) and copy all three files (Firefly. gha, Firefly_X.gha, and libTUIO.dll) into the Components Folder that was opened from within Rhino. Note: All three of these files have to be copy/pasted into that directory for Firefly to run properly. This process only has to be done once! Make sure to remove any prior Firefly installation files (if you are upgrading from an earlier release and had the build files stored in this folder). If you had installed an earlier version of Firefly and you had placed the build files in the C:\Program Files (x86)\ Rhinoceros 4.0\Plug-ins\Grasshopper\Components directory... please remove them! • Now, Restart Rhino and Grasshopper - This time when you launch Grasshopper, you should see a new Firefly tab at the top of the Grasshopper Editor. Congratulations! You’ve now installed the Firefly toolbar.

Firefly Tab

Note: If you are having problems getting Firefly to load properly in Rhino 5.0 beta, try the following steps: Open the Special Components folder (where we just copied the 3 files) and right-click on each file and select “Properties”. Under the General tab, check the box to “Unblock” the file. Do this for each of the three files. Now, Restart Rhino and Grasshopper

Firefly Primer - Version 1.006 - Page 8

Step 02. Arduino 0022 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 0022 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!

USB

Blink Me !!!

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

Step 02b. Firefly Firmata

Download the latest Firefly Firmata: http://www.fireflyexperiments.com/download/ Copy/Paste the folder named “Firefly_UNO_Firmata” 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 02c. Upload Firefly Firmata to your Arduino Board

a. Launch the Arduino 0022 Application b. Open the Firefly Firmata sketch: File > Sketchbook > “Firefly_UNO_Firmata.pde” c. Select your Board: Tools > Board > Arduino Uno (w/ ATmega 328) (or whatever board you are using) 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!!! Firefly Primer - Version 1.006 - Page 9

Step 3 (Install WinAVR - Needed to Upload Sketches from Grasshopper)

WinAVR is now required to be installed in order to use the new Upload to I/O Board component in Firefly. WinAVR is an suite of open source software development tools that includes avr-gcc (compiler) and avrdude (programmer) among other things. To install the latest version of WinAVR: Go to: http://sourceforge.net/projects/winavr/files/WinAVR/ Click on the folder called “20100110” and download the file WinAVR-20100110-install.exe Run the executable and follow the instructions.

Step 4 (Have Fun! - needed everytime)

Your now set to start playing around with Firefly. Launch Rhino, and type the word “Grasshopper” into the command prompt to launch the Grasshopper Editor. Open one of the example files located in the ‘Grasshopper Examples’ folder (inside the zip file) and begin exploring the connection between the physical and virtual worlds!

1.1

FIREFLY GRASSHOPPER EXAMPLE FILES

An amazing set of example files has been put together by Andy Payne in collaboration with Gil Akos and Ronnie Parsons. The files are located in the “Firefly Build 1.006.zip“ folder: http://www.fireflyexperiments.com/download/ These example files are a great way to jump start the learning process.

Partial screenshot from the “20110625_Firefly_02_Actuation.gh” example file

Firefly Primer - Version 1.006 - Page 10

2.0

FIREFLY TOOLBAR + COMPONENTS

I/O Boards

PORTS COM Ports Available - Check to see which COM Ports are currently available Open Port - open the serial port, set the port number and the baud rate

I/O (Input/Output) Boards Mega Read - read values on all digital and analog Arduino MEGA pins Mega Write - write values on all digital and analog Arduino MEGA pins Uno Read - read values on all digital and analog Arduino UNO pins Uno Write- write values on all digital and analog Arduino UNO pins SerialRead - Retrieve a value coming over the serial port SerialWrite - Write a string value to the Serial Port

CODE GENERATOR AND UPLOAD TO BOARD CodeGen - convert a Grasshopper definition into Arduino code. [New to 1.006!] Upload I/O - Upload an Arduino sketch to an Arduino board (requires WinAVR) [New to 1.006!]

Firefly Primer - Version 1.006 - Page 11

Other Inputs + Utility

OSC + UDP OSC Listener - receives data from a specified UDP port [New to 1.006!] OSC Sender - sends messages over a UDP port to a specified IP address [New to 1.006!] UDP Listener - opens a UDP port and listens for any incoming messages. [New to 1.006!] UDP Sender - sends any string to a specified IP address on the network [New to 1.006!]

OTHER INPUTS Pachube Read - Read a file from a Pachube Internet feed (www.pachube.com) ReacTIVision - connects to an open source, cross-platform computer vision framework Wii Nunchuck - read all sensor values from a Wii Nunchuck XML Search - Search an XML file (web or a local directory) for a specific element tag [New to 1.006!]

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 Wave - creates a sinusoidal waveform output State Detection - detect a switch from LOW to HIGH (0 or 1) or vice versa [New to 1.006!] Stop Watch - time in milliseconds since the data was updated. [New to 1.006!]

Firefly Primer - Version 1.006 - Page 12

2.1

Ports Available + Open Port B A

Firefly > Boards > Ports Available Use this component to check to see what COM ports are currently available. In order to establish a connection to the Arduino, we must designate which serial port we would like to use. Note: If only one Port Number is listed (similar to above) then you can also directly connect the Ports Available output [P] directly into the Open Port input [A]. If you have one or more Arduino boards connected to your computer, the Ports Available component will poll your device manager and return the number to each device you have connected. (Note: We have successfully connected as many as 4 Arduino boards to Firefly at once. Theoretically if your computer can assign your each of your boards a COM Port # then Firefly can communicate with it! You can also verify the COM port number is correct by clicking on the Tools>Serial Port button within the Arduino software IDE.)

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 Uno Read/Write and Mega Read/Write components will only send/receive data if the port is open. * You must 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 Firefly Primer - Version 1.006 - Page 13

2.2

Uno Read

A Firefly > Boards > Uno Read The FireFly Uno Read component will read values for all corresponding digital and analog pins on the Arduino Uno, Duemilanove, Diecimilla, or Lillypad board. Use the GH_Timer component (Parameters/Special/Timer) to update the sensor values in real-time. Note: This component is meant to be used in tandem with the FireFly Uno Arduino Firmata program (a .pde file) which can be downloaded from the Firefly website at: www.fireflyexperiments.com

Description of Component Input/Output Parameters Input Parameters: Start (Boolean) Input an Boolean value (True/False) to start receiving values from the Arduino Port (Integer) This should match the Port number that you first established in the Open Port component. The Port Number has to be the same Serial Port assigned in the Arduino Sketch. You can find which COM port you are using by clicking on the Tools>Serial Port button on the Arduino IDE. Note: In the image above the “Wire Display” is set to “Hidden Display” (right-click over “Port” to select this) [A] Timer (Parameters/Special/Timer) Connect a timer component - Timer intervals are specified in milliseconds. Right-click on the Timer component and then select “Interval”. If you type in “1” then this will set the timer to 1 millisecond (very fast). 500 ms equals 1/2 second, and 1000 ms equals 1 second etc. Output Parameters: APin0 (Integer) Incoming sensor value from Analog In Pin 0 APin1 (Integer) Incoming sensor value from Analog In Pin 1 APin2 (Integer) Incoming sensor value from Analog In Pin 2 APin3 (Integer) Incoming sensor value from Analog In Pin 3 APin4 (Integer) Incoming sensor value from Analog In Pin 4 APin5 (Integer) Incoming sensor value from Analog In Pin 5 DPin2 (Integer) Incoming sensor value from Digital In Pin 2 DPin4 (Integer) Incoming sensor value from Digital In Pin 4 DPin7 (Integer) Incoming sensor value from Digital In Pin 7 Msg (String) Current status of Serial Port Firefly Primer - Version 1.006 - Page 14

2.3

Uno Write

A Firefly > Boards > Uno Write The FireFly Uno Write component will write values for all corresponding digital pins on an Arduino Uno, Duemilanove, Diecimilla, or Lillypad board. Note: This component is meant to be used in tandem with the FireFly Uno Arduino Firmata Sketch (a .pde file). Note: If the Port has been opened, double-click on the Start toggle to set it to True and start writing values to the Arduino. The Firefly Firmata sketch has been completely re-written to make the Write process more fluid. For example, you can now control a servo on any of the digital pins. The pins that have the tilde (~) symbol represent the digital pins on the Arduino board that have Pulse Width Modulation (PWM: 0-255) capabilities. To set the type of pin control, simply right-click on any input and set the status to either Digital (HIGH/LOW or 0/1), PWM (0-255), or Servo (0-180). If you right-click on the Uno Write components DPins 11,6,5 and 3 you will see the PWM option (between Digital and Servo) in the drop down menu. In the current build Pins 10,9 are not PWM. Let me know if this works for you. [A] Port: This should match the Port number that you first established in the Open Port component

Description of Component Input/Output Parameters Input parameters:

Start (Boolean) Input an Boolean value (True/False) to start writing values to the Arduino DPin13 (Integer) Integer to write to Digital Pin 13. Right-click on the input to set the input status (Digital or Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin12 (Integer) Integer to write to Digital Pin 12. Right-click on the input to set the input status (Digital or Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin11~ (Integer) Integer to write to Digital Pin 11. Right-click on the input to set the input status (Digital, PWM, Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the PWM status is set then any value between 0-255 can be used to analogWrite to the specified pin. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin10~ (Integer) Integer to write to Digital Pin 10. Right-click on the input to set the input status (Digital or Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin9~ (Integer) Integer to write to Digital Pin 9. Right-click on the input to set the input status (Digital or Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin8 (Integer) Integer to write to Digital Pin 8. Right-click on the input to set the input status (Digital or Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin6~ (Integer) Integer to write to Digital Pin 6. Right-click on the input to set the input status (Digital, PWM, Servo). If the Digital Firefly Primer - Version 1.006 - Page 15

status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the PWM status is set then any value between 0-255 can be used to analogWrite to the specified pin. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin5~ (Integer) Integer to write to Digital Pin 5. Right-click on the input to set the input status (Digital, PWM, Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the PWM status is set then any value between 0-255 can be used to analogWrite to the specified pin. If the Servo status is set then any value between 0-180 can be used to for servo positioning. DPin3~ (Integer) Integer to write to Digital Pin 3. Right-click on the input to set the input status (Digital, PWM, Servo). If the Digital status is set then the integer (0) will send a LOW value and a (1) will send a HIGH value. If the PWM status is set then any value between 0-255 can be used to analogWrite to the specified pin. If the Servo status is set then any value between 0-180 can be used to for servo positioning. Port (Integer) The Port Number has to be the same Serial Port assigned in the Arduino Sketch. You can find which COM port you are using by clicking on the Tools>Serial Port button on the Arduino IDE.

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. Msg (String) Current status of Serial Port

RX+TX LEDS

Pin13 LED

Digital Pins 0-13

FTDI USB Chip Power LED

USB Jack

Reset Button ICSP Header 5V Volt Regulator

Microcontroller Chip ATmega 328

Power Jack Power Pins

Analog Input Pins

Arduino Uno Overview The Arduino Uno (released in 2010) is a microcontroller board based on the ATmega328 chip. It has 14 digital input/output pins (of which 6 can be used as PWM outputs), 6 analog inputs, a 16 MHz crystal oscillator, a USB connection, a power jack, an ICSP header, and a reset button. It contains everything needed to support 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. The Uno 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/ArduinoBoardUno Firefly Primer - Version 1.006 - Page 16

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 - Version 1.006 - Page 17

2.6

Generic Serial Read

Firefly > Boards > Generic Serial Read Retrieve a value coming over the Serial Port from the Arduino board.

Description of Component Input/Output Parameters 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. Port (Integer) The Port Number has to be the same Serial Port assigned in the Arduino Sketch. You can find 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. Msg (String) Current status of Serial Port 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); }

Firefly Primer - Version 1.006 - Page 18

2.7

Generic Serial Write

Firefly > Boards > Generic Serial Write Write a string value to the Serial Port.

Description of Component Input/Output Parameters 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 Port (Integer) The Port Number has to be the same Serial Port assigned in the Arduino Sketch. You can find which COM port you are using by clicking on the Tools>Serial Port button on the Arduino IDE. Output parameters: Out (String) Returns the string that will be sent to the Arduino board. Msg (String) Current status of Serial Port

Firefly Primer - Version 1.006 - Page 19

2.8

Code Generator

Firefly > Boards > Code Generator This component will attempt to convert a Grasshopper definition into Arduino compatible code. The code can be simultaneously saved as a .pde file to be opened in the Arduino IDE. This component will attempt to convert any Grasshopper definition into Arduino compatible code (C++) on the fly. Simply connect the Out string from either the Uno/Mega Write component to the input of the Code Generator and watch the code build as you create your Grasshopper definition. It works by detecting any component ‘upstream’ from the Uno/Mega Write component. When it detects a component, it checks whether or not it has a function for that component. If it does, it adds the function to the top of the code, and properly calls the function inside the main setup() or loop() functions. If the library of functions does not contain a definition for a particular Grasshopper component, it will provide a warning. This code can be simultaneously saved as a .pde file to be opened in the Arduino IDE. VIDEO: Andy has created a great video illustrating how it works: http://www.fireflyexperiments.com/videos/arduino-code-generator-upload-to-io-board.html

Description of Component Input/Output Parameters Input parameters: Input (Generic Data) Connect the ‘out’ message from one of the Uno/Mega Write components to generate the code. Path (String) File path to save the code. Note: This component will save the code with the arduino file extension .pde Output parameters: Code (String) Arduino Compatible Code

Firefly Primer - Version 1.006 - Page 20

2.9

Upload to I/O Board

Click to upload the Arduino Code Firefly > Boards > Upload I/O This component will attempt to upload any Arduino sketch to your I/O Board. VIDEO: Andy has created a great video illustrating how it works: http://www.fireflyexperiments.com/videos/arduino-code-generator-upload-to-io-board.html If the Arduino sketch file path is valid (can be from the Code Generator), you can click on the arrow icon to upload the sketch to the board. Alot of stuff happens behind the scenes, but it should create a dynamic MakeFile and convert the .pde file into a .cpp (C++) file and then into .hex code (machine readable code for the microcontroller). NOTE: WinAVR is required to be installed in order for the Upload to I/O Board component to work properly. WinAVR (pronounced “whenever”) is a free suite of executable, open source software development tools which includes avr-gcc (compiler), avrdude (programmer), among other things. You can download the latest version of WinAVR at: http://winavr.sourceforge.net/index.html

Description of Component Input/Output Parameters Input parameters: Path (String) File path to the Arduino code you would like to upload Port (Integer) Port Number Board (String) Right-click to select the Arduino board.

Firefly Primer - Version 1.006 - Page 21

2.10

OSC Listener and Sender

Firefly > Other Inputs > OSC Listener Open Sound Control (OSC) messages are essentially specially formatted User Datagram Protocols (UDP) transmissions. The OSC Listener component works by opening a UDP port and listening for any OSC message on the network. It receives a message it creates a data tree structure which contains the OSC name and the value (can be floats, integers, strings, etc.). If a new message is received with a different name, then a new branch is created for that message. However, if message is received and a branch already contains that name, then the value will updated. Use a List Item or Tree Item to retrieve the latest value for each message in the data tree. A reset toggle can be used to clear the data tree values. Note: This listener needs an external timer to update properly (use Grasshopper Timer). VIDEO: Andy has created a great video (see the screenshot below right) illustrating how it works: http://www.fireflyexperiments.com/videos/firefly-breath-osc.html

Description of Component Input/Output Parameters Input parameters: P (Integer) OSC Port to listen to R (Boolean) Reset (clear) the OSC messages Output parameters: D (String) The data just received from the port The Breath OSC Video by Andy Payne (with Daniel Piker)

Firefly > Other Inputs > OSC Sender The OSC Sender will automatically format incoming data into the appropriate OSC format and send the message over a UDP port to a specified IP address. As stated above, OSC messages are specially formatted messages which can be broadcast over a network. In order to send an OSC message, you must know the IP address of the device you’re trying to send the message to. You must also specify a unique UDP port. Once you have specified the IP address and the Port, you can connect any type of data (sliders, toggles, panels, etc.) and it will automatically format the data into an OSC message and broadcast that to the specified address.

Description of Component Input/Output Parameters Input parameters: Data (String) Data IP (String) IP Address Port (Integer) UDP Port Firefly Primer - Version 1.006 - Page 22

2.11

UDP Listener and Sender

Firefly > Other Inputs > UDP Listener User Datagram Protocol (UDP) is a transmission model for sending/receiving messages over a network. The UDP Listener component simply opens a UDP port and listens for any incoming message. An IP address is not required for listening for messages (only for sending messages). The return value is a string. Note: This listener needs an external timer to update properly (use Grasshopper Timer). Processing 1.5+: http://www.processing.org UDP Library by Stephane Cousot for Processing: http://ubaa.net/shared/processing/udp/udp.zip

Description of Component Input/Output Parameters Input parameters: P (Integer) UDP Port to listen to Output parameters: D (String) The data just received from the port

Firefly > Other Inputs > UDP Sender The UDP Sender component sends any string message to a specified IP address on the network through a given port. This can be useful in sending messages to other programs running on another computer (such as Processing) or other mobile devices.

Description of Component Input/Output Parameters Input parameters: Data (String) Data IP (String) IP Address Port (Integer) UDP Port

*** MORE DOCUMENTATION ON THESE COMPONENTS WILL BE COMING SOON ***

Firefly Primer - Version 1.006 - Page 23

2.12

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 at the end of this Primer

Description of Component Input/Output Parameters Input parameters F (String): Pachube web address of feed. A (String): Users API Key [*You will need to sign-up at pachube.com to get your own personal API key] Output parameters C (String) Returns the CSV output from a given csv pachube feed. M (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 T (String) Returns the XML Tag of each element in a pachube feed Mn (String) Returns the minimum value of each element in an XML pachube feed Mx (String) Returns the maximum value of each element in an XML pachube feed V (String) Returns the current value of each element in an XML pachube feed U (String) Returns the units of each element in an XML pachube feed

Firefly Primer - Version 1.006 - Page 24

2.13

Reactivision Listener

Firefly > Other Inputs > Reactivision Listener ReacTIVision is an open source, cross-platform computer vision framework for the fast and robust tracking of fiducial markers (symbols) attached onto physical objects, as well as for multi-touch finger tracking. The Firefly Reactivision Listener draws the position, rotation, and fiducial ID number of each Reactivision marker. This component creates an offset bounding box area defined by black tick marks that indicate the entire X&Y extents of the camera frame. Once a fidicial marker is introduced inside the inner grey bounding box area, the maker will remain on the plane/surface even if the camera loses track of the marker or the user hides the marker completely. If the user wants to remove a marker from the scene, they simply need to move the marker slowly outside the grey bounding box area. This component is meant to be used in tandem with the Reactivision software, available for free from: http://www.reactivision.com/downloads. Fiducial markers: http://reactivision.sourceforge.net/#files *Note: You must have the Reactivision software running in conjunction with a working camera to use this component.

Description of Component Input/Output Parameters Input parameters: Srf (Surface): Optional surface to map fidicual planes. If no surface is provided, the World XY plane will be used by default. S (Boolean): Start or Start the Listening Client Ps (Number): If no base surface is provide, the World XY plane will be used by default. This scale value will control the overall size of this plane. T (Boolean): Draw Fiducial ID Marker Tags B (Boolean): Draw Bounding Box Output parameters: P (Plane): Oriented planes corresponding to each fiducial markers ID (Integer): The list of current fiducial id’s recognized by the camera Msg (String): Current status message of the Reactivision Listener

Reactivision Fiducial Markers Firefly Primer - Version 1.006 - Page 25

2.14

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

Description of Component Input/Output Parameters 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. Port (Integer) The Port Number has to be the same Serial Port assigned in the Arduino Sketch. You can find which COM port you are using by clicking on the Tools>Serial Port button on the Arduino IDE. 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/

Firefly Primer - Version 1.006 - Page 26

2.15

XML Search

Firefly > Other Inputs > XML Search Search an XML file (either from the web or from a local directory) for a specific element tag

Description of Component Input/Output Parameters Input parameters: P (String) XML file path to search. This can either be a web address (URL) or a local directory. S (String) Keyword search value(s). Output parameters: E (String) XML Elements

XML File Source Example This is a good source for simple XML Weather Data: http://weather.boygenius.com/feeds In order to see how the XML is structured you will need to right-click in your browser window and select “View Source”. If you are using the “Chrome” browser you will see XML code similar to the screenshot below. Look for the tag element name that you would like to retrieve. In the Firefly example illustrated above we are using the tag on line 10 which in this case returns the text string “Most Sunny”.

Firefly Primer - Version 1.006 - Page 27

2.16

Binary Blink

Firefly > Utility > Binary Blink Oscillates 0’s and 1’s based on an incoming pattern of integers

Description of Component Input/Output Parameters 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. Firefly Primer - Version 1.006 - Page 28

2.17

Buffer

Firefly > Utility > Buffer Store the last number of values based on the buffer domain

Description of Component Input/Output Parameters 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

Firefly Primer - Version 1.006 - Page 29

2.18

Constrain

Firefly > Utility > Constrain Constrains a number to a specific numeric range.

Description of Component Input/Output Parameters Input parameters: Val (Number) Incoming value Min (Domain) Domain to constrain values Output parameters: Val (Number): Constrained Value

Firefly Primer - Version 1.006 - Page 30

2.19

Data Log

Firefly > Utility > Data Log Create a log of incoming data.

Description of Component Input/Output Parameters 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

Firefly Primer - Version 1.006 - Page 31

2.20 / 2.21

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).

Description of Component Input/Output Parameters 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

Firefly Primer - Version 1.006 - Page 32

2.22

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

Description of Component Input/Output Parameters 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

Firefly Primer - Version 1.006 - Page 33

2.23

Smoothing A

B

Firefly > 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.

Description of Component Input/Output Parameters Input parameters Val (Number): Incoming value N (Integer): The number of samples to average Output parameters A (Number): A smoothed average of values.

Firefly Primer - Version 1.006 - Page 34

2.24

Wave

Firefly > Utility > Wave Create a sinusoidal waveform output. This component outputs points that correspond to a cosine curve. You can start the timer and watch the phase shift move the points along. It also outputs the Y-coordinates which if scaled properly could correspond to PWM values to control LEDS, Servos, Steppers, etc.

Description of Component Input/Output Parameters Input parameters S (Boolean): Start the wave form N (Integer): The number of steps to evaluate along the wave form F (Integer): Frequency of the wave form W (Number): Wave Length of the wave form A (Number): Amplitude of the wave form B (Number): Base Line Value Output parameters P (Point): Points X (Number): X value Y (Number): Y value

Firefly Primer - Version 1.006 - Page 35

2.25

State Detection

Firefly > Utility > State Detection Used when you want to detect when something has switched from LOW to HIGH (0 or 1) or vice versa. For more information see: http://arduino.cc/en/Tutorial/ButtonStateChange

Description of Component Input/Output Parameters Input parameters: V (Integer) Incoming value to test. M (Integer) Modulo value to determine the number of state changes before a switch is made. Output parameters: S (Integer) Current State C (Integer) Counter TRY IT OUT: 1. Build the Button Circuit illustrated below. Make sure the button is connected to digital Pin 2 as pictured. 2. Construct the Firefly components as they are illustrated above. When you press the button the LED (hardwired to Pin 13) on your Arduino board should turn ON and OFF.

Firefly Primer - Version 1.006 - Page 36

2.26

Stop Watch

Firefly > Utility > Stop Watch Time in milliseconds since the data was updated.

Description of Component Input/Output Parameters Input parameters: D (Generic Data) Data to be updated. Output parameters: T (Number) Time in milliseconds since the data was updated. FPS (Integer) Approximate frames per second. Note: Takes the average of last five fps values.

Firefly Primer - Version 1.006 - Page 37

2.27

Additional Components

Additional Components [Boolean, Number Slider, Value Tracker, Remap, Panel, Timer] 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 left 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. Firefly Primer - Version 1.006 - Page 38

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 rightclick 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. Firefly Primer - Version 1.006 - Page 39

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.

Special > Domain > Timer Timer - Timers are objects which fire update events at specified intervals. In the image below it is used to fire (like a bang) the UNO Read component every 1 millisecond (it reads the sensor values every 1/1000 of a second.)

Timer

Timer Description Timers are object which fire update events at specified intervals. This process is reasonably dangerous since updates might occur when you do not expect them, so please be careful when using them, and only use a timer when you have no other option. Remarks: Timer intervals are specified in milliseconds. Right-click on the Timer component and then select “Interval”. If you type in “1” then this will set the timer to 1 millisecond (very fast). 500 ms equals 1/2 second, and 1000 ms equals 1 second etc.

Firefly Primer - Version 1.006 - Page 40

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, Uno Read and Uno 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

5V

GND

d. PHOTORESISTOR

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 Standard 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 pictured above. Connect the SIG (signal) to any of your Analog In pins. The circuit above uses Analog Pin 1. Firefly Primer - Version 1.006 - Page 41

READ A

C

WRITE

PORT

B

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 “Available Ports” # - see Section 2.1 for details). 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 Uno Read a. Drag the Uno 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 connected to the Arduino. In later steps we will connect these directly to specific parameters within a Grasshopper model to dynamically control geometries, spatial relationships, etc.

E G

F

J

H

I

Above - The Uno Write Component (see description on the next page) Firefly Primer - Version 1.006 - Page 42

Step 3: Preparing Uno Write a. Drag the Uno 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 separated 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 to the PWM pins indicated on the Arduino Uno 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 across them. We first connect the 6 outputs from the Uno 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

B A D E

Figure 1. The Rhino modeling window (left) and Grasshopper Interface (right)

C

E

Firefly Primer - Version 1.006 - Page 43

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 account. 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 thirdparty 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 identification 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.

Firefly Primer - Version 1.006 - Page 44

Step 2. Find a Pachube feed There are several different methods for accessing the thousands of live real-time 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 displayed 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 real-time data in various formats: CSV, JSON & EEML (an XML format). The XML file format contains the most descriptive information about a sensor feed (including metadata), while the CSV format contains the least. Note: The Grasshopper 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:

Firefly Primer - Version 1.006 - Page 45

URL: retrieves the real-time 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

This example and several others are covered in a very thorough example file “20110625_Firefly_07_Pachube. gh” available in the Download section here: www.fireflyexperiments.com. The example file covers several additional steps not shown here including how to connect the Pachube Read component to geometry in Grasshopper.

Firefly Primer - Version 1.006 - Page 46

4.00 4.1

ADDITIONAL RESOURCES

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; Great mail order too] 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] Digikey [Major Electronics Supplier with an huge catalog] SuperBrightLEDS.com [Single LEDs or multiple strings, all types, good quality] Servocity [Great Selection of Servos and Supplies] ARDUINO + GENERAL ELECTRONICS SUPPLIERS Arduino [mothership: great links to everything Arduino] Sparkfun [custom Arduino shields, sensors, hardware, kits ...] MakerShed [sensors, hardware, kits ...] LiquidWare [lots of everything] 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] SHAPE MEMORY ALLOY Dynalloy [maker of Flexinol - located in Tustin, CA] Images Scientific Instruments [large selection of nitinol and flexinol based products] Miga Motors [large selection of SMA driven servos and actuators] POWER SUPPLIES PowerSupplyOne [Huge Selection of Power Supplies] GOOD ARDUINO BASED STARTER KITS + Mid-Range > Arduino Starter Pack or equal [includes Arduino Uno, Protoboard, and a good selection of starter components] + High-End Recommended > Arduino Experimentation Kit v1.0 or equal [includes Arduino Uno, 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] Firefly Primer - Version 1.006 - Page 47

4.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

4.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] Finches / Local Code (GIS tools): http://www.grasshopper3d.com/group/localcodecomponents 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]

Machine Vision

ReACTivision: http://reactivision.sourceforge.net/ Kinect / Grasshopper Research Group: http://ghkinect.blogspot.com

Python

Python Interpreter for GH: http://www.grasshopper3d.com/forum/topics/python-interpreter-test-drive Python GH Research by Walter Kim: http://abstractnonsen.se/cca/ag_s11/ [Note: These are working lists. Please e-mail us a related links and we’ll consider adding them to our lists]

Firefly Primer - Version 1.006 - Page 48

4.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/

Firefly Primer - Version 1.006 - Page 49

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