This page is for documentation purposes only. A new version of Snap! is now available. For the newest version, visit: http://www.finchrobot.com/software/snap

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

User Guide

• Installation
  • Windows
  • Mac
  • Linux
• Launching Snap
• Programming for Finch/Hummingbird in Snap
  • Finch Blocks
  • Hummingbird Blocks
• Saving, Loading, and Configuring Projects
• Examples
• Known Issues

Installation

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:

Programming for Finch/Hummingbird in 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

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

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

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

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.

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

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

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

Examples

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.