BirdBrain Snap v0.2 (alpha)

This page is for documentation purposes only. A new version of Snap! is now available. For the newest version, visit:

We have created a drag and drop environment for programming Finch/Hummingbird based heavily on Snap 4.0. Snap 4.0 is being developed by Jens Mönig and Brian Harvey and is based on the popular Scratch programming environment. Snap adds a number of key features like creating custom blocks and recursion. Snap is normally hosted online  through a browser interface, but in order to interface it with the Finch /Hummingbird we needed to create a downloadable release. 

The hybrid BirdBrain Snap environment takes the interface and source code from Snap, and tweaks it to add blocks that control/get sensory data from the Finch robot or Hummingbird controller. The modified Snap interface communicates with these robots via a server that talks with the javascript-based Snap using JSON2 RPC messages. 

Purpose of Release

We're looking for feature suggestions and bug reports! We believe that the version posted is ready for use with students, but are continuing to improve the UI and squashing whatever bugs remain. 

User Guide


Windows: Download the Windows installer and double click on it. A dialog will pop up for 10-30 seconds and exit on its own; you will not be prompted for anything. Once installed, a lightbulb icon labeled "BirdBrainSnap" will appear on your desktop. Run the program by double clicking on this.

Mac: Download the Mac installer and double click on it. In the resulting disk image window, drag the BirdBrainSnap program (lightbulb icon) into the Applications folder. To run, open Applications and double click on BirdBrainSnap.

In Mac OS X 10.8 (Mountain Lion) the first time you run the application, right-click or control-click on it and select "Open". In the resulting dialog, select "Open". More details here.

Linux: Download the Linux package and unzip it. Place the resulting folder in a convenient directory. Auto-configure by running the "Configure" script as root. You can do this by navigating to the BirdBrainSnap directory and typing "sudo ./Configure". The configuration script will install a USB HID library in your /usr/lib/ directory and will write udev rules to allow you to use Finch and Hummingbird as a normal user. If this configuration fails, please email us for manual instructions (we need feedback from you if it breaks, as we are unable to test on all Linux variants).

Once you have configured the package, you can run Snap by double-clicking on "LaunchSnap" and selecting "Run".

Launching Snap!

Plug in a Finch, Hummingbird, or both, then run the BirdBrainSnap application. The following window will appear:

This window will check if you have a Finch and/or Hummingbird attached. In Windows you can plug in a device after the window has been launched and have it be detected, in Mac/Linux you must plug in your devices before launching this window; simply exit and re-run the program if necessary.Once all of the robots you have attached have been found, click on the "Open Snap!" button. 
5-20 seconds after clicking "Open Snap!", the Snap programming environment will launch in your default browser. We strongly recommend setting Chrome to default for the best user experience. If you do not wish to set Chrome to default, you can also copy the URL ( into a Chrome window after you click "Open Snap".
The "Stop Server" button can be used to disconnect the Finch or Hummingbird from the Snap! interface, thus allowing you to use them with other environments or languages while keeping the Snap Launcher window open. It can also be used to reset the Finch/Hummingbird in the event that it is unplugged during use. Do not press the "Stop Server" button if a Snap script using Finch/Hummingbird blocks is running, as it may cause the script or page to crash.

Programming for Finch/Hummingbird in Snap

For those unfamiliar with the Snap/Scratch interface, check out the tutorials here (Scratch) and here (Snap). We will focus on the Finch/Hummingbird blocks unique to BirdBrain Snap.

Finch Blocks  

Motion Commands

  • move Finch forward/move Finch backward: Sets both wheels to the same power, range is 0 to 100% power.
  • turn Finch clockwise/right and turn Finch counterclockwise/left: Turns Finch in  place, range is 0 to 100% power.
  • set Finch wheels: Lets you set each wheel individually, range is -100 to 100.
  • stop Finch: stops the Finch
LED Commands
  • set beak to R G B: Sets the color of the Finch's beak, the R, G, and B arguments control the intensity of the red, green, and blue elements in the Finch's beak. Range is 0 to 100 for each argument. 
  • set beak to color: Sets the color to the one picked by a color picker. Works best for colors in the middle of the picker.
Sound Commands
  • play Finch beep at Hz for seconds: Plays the Finch's beep with a sound of the frequency specified for the time specified. Range is 20 to 20,000 for frequency.
  • Have computer say text: Uses the text to speech synthesizer to have the computer say whatever is in the text field.
Sensing Commands
  • Finch left and right light sensor: Returns the intensity of light hitting the light sensors. The values are in a range from 0 to 100 where 0 is total darkness and 100 is saturation of the sensor.
  • Finch left and right obstacle sensors: These are boolean, returning true if an object is 1-4" from the sensor and false otherwise.
  • Finch temperature: Returns the current temperature in Celcius.
  • Finch Orientation: Returns the current orientation of the Finch, possible responses are: level, upside down, beak up, beak down, left wing down, right wing down, and in between.
  • Finch X/Y/Z accelerometer: Returns the current g-forces measured along the Finch's X (beak to tail), Y (wheel to wheel), and Z (top to bottom) axes. Range is -1.5 to 1.5 gees.
  • Is Beak Up/Is Beak Down/Is Finch Level/Is Left Wing Down/Is Right Wing Down/Is Finch Upside Down: Returns true if Finch is in the position described by the block name, false otherwise.
All sensors have a monitor checkbox - if checked, values will be continuously refreshed and displayed in the drawing area.

Hummingbird Blocks  

Motion Commands

  • set HB motor: Sets motor port 1 or 2 to a value from -100 to 100. 
  • set HB servo: Sets servos 1 through 4 to a value from 0 to 160 degrees.
  • set HB vibration motor. Sets vibration motor 1 or 2 to an intensity value from 0 to 100.
LED Commands
  • set HB Full-color LED to R G B: Sets the full color LED at port 1 or 2. The R, G, and B arguments control the intensity of the red, green, and blue elements in the tri-color LED. Range is 0 to 100 for each argument. 
  • set HB Full-color LED to color: Sets the full color LED at port 1 or 2 to the color chosen by the color picker.
  • set HB LED: Sets the intensity of light on a single color LED on ports 1 through 4. Intensity ranges from 0 to 100.
Sensing Commands
  • HB Sensor Port 1 to 4: Displays and allows access to the value seen by Hummingbird at a given sensor port. Sensor values range between 0 to 100. Note that these are raw values and have not been converted to units appropriate to a given sensor in the kit.
All sensors have a monitor checkbox - if checked, values will be continuously refreshed and displayed in the drawing area.

Saving, Loading, and Configuring Projects 

The project control bar at the top of the browser window contains the buttons necessary for creating, saving, loading, and configuring projects.

 New project. This button closes the current project and creates a new project. By default a new project is created when you first open snap in the browser. If you wish to keep a project open while you work on a new project you can always click on the "Open Snap" button in the launcher program to open a new Snap window in your browser.


  Load Project. This button allows you to browse for a project file (xml file extension).


 Save project. This button saves the current project to the disk. The file name will be the name of the project followed by the .xml extension. In Windows in Chrome the default save directory is not the same as the load project directory - please change the directory a more typical directory (like Documents) before saving.


 Project Settings. Use this button to edit/view project notes, export custom blocks, rename the project, or change certain configuration options (like whether the blocks make a clicking noise when snapped together).


We have created a number of preliminary example programs for Finch in Snap. You can download them here. We will create more detailed examples when Snap! officially moves to beta.

Known Issues

  • Currently if the computer goes to sleep, you'll need to restart the server because it will lose connection with the Finch/Hummingbird (you can keep the browser page open through a server restart).
  • The "Name your Project" dialog's text field must be clicked on in Windows Chrome to type a name.
  • The save program button requires Flash to be enabled.
  • The save program location in Chrome in Windows is not the same as the load program location. We suggest saving files in the load program location (Documents).
  • If Finch/Hummingbird are unplugged while a program is running or while Finch/Hummingbird sensors are being monitored, the browser window could freeze. You can unfreeze the window by clicking on "Stop Server" in the Launching Program, plugging your Finch/Hummingbird back in, and then clicking on "Resume Server".

Last Update

We last updated our code on October 3rd, download it again if you got it before then.

FinchSnapExamples.zip42.3 KB