Snap! is a drag and drop programming environment developed by Jens Mönig and Brian Harvey. Snap! is a descendant of Scratch and adds a number of key features like creating custom blocks, recursion, and running in a browser.

We have developed two utilities, the BirdBrain Robot Server and the Finch connection app, that allow Finch to be controlled from within Snap!. The rest of this guide describes installing the utilities, opening Snap!, and programming for Finch in Snap! 

User Guide



Download the Windows installer and double click on it. Follow the instructions in the installer. Once installation is complete, a shortcut to BirdBrain Robot Server will appear on your desktop.


Download the Mac installer and double click on it to mount the disk image and open the installation folder. Drag the "BirdBrainRobotServer" lightbulb icon into the "Applications" directory. To run it, go to Applications and double click on BirdBrainRobotServer.



Download the debian installer and install it. You will need administrator privileges to install. 

Other 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 BirdBrainRobotServer 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. Once you have configured the package, you can run Snap by double-clicking on "LaunchSnap" and selecting "Run". The configuration script is based on the configuration rules for Ubuntu; it may not work with all Linux variants.


Visit the Chrome webstore to install the Finch Connection App.  

Important note 1: Projects created with the Birdbrain Robot Server on Windows, Mac, or Linux will not run on a Chromebook. Similarly, projects saved on a Chromebook will not run with the Birdbrain Robot Server. If this is an issue, you can use this utility to convert .xml files exported from the Finch Connection App to a form that can be used with the Birdbrain Robot Server. It can also convert .xml files created with the Birdbrain Robot Server so that they can be used with the Finch Connection App. Please note that all of the Snap! sample programs that can be downloaded here and on the Teaching tab were created for the Birdbrain Robot Server; this sample code must be converted if you want to run it on a Chromebook.

Important note 2: If using the Chrome app on a Macbook running Mac OS 10.9 or later, keep some part of the Finch Connection App visible on the desktop to prevent app nap.

Launching Snap! - Windows, Mac, and Linux

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

BirdBrain Robot Server Launcher

This window will check if you have a Finch and/or Hummingbird attached and provides a convenient way to launch the Snap! website. 

Once you have Finch plugged in, click "Open Snap!". This will open a second window, allowing you to select the level you wish to use:

The levels are discussed at length in the Programming for Finch in Snap! section. 

Once you have selected a level, this will launch the Snap! website in Chrome (if installed), or in your computer's default browser. For the best experience using Snap!, install Chrome.

The checkbox for "Open Snap! locally" allows you to run Snap! if there is no internet connection. The application checks upon startup for a connection to the Snap! website and will automatically check this box if no connection is found.

Launching Snap! - Chrome OS

  1. Plug in the Finch
  2. Launch the Finch Connection App:
  3. Click the Open Snap! button on the app to automatically load a Snap! page with the Finch blocks loaded, and accept any prompts when the page loads.

Note: If the appropriate Snap! page does not load when you press Open Snap!, you can access them directly here: Level 1, Level 2, Level 3, Level 4.

Programming for Finch in Snap!

Programming Levels

In addition to the regular Snap! programming environment (level 4), we have created three simpler levels of the programming interface. Each level provides increasing options and complexity, with the intent that young students (ages 4 to 10) or other beginners will progress through these introductory levels before transitioning to the regular Snap! interface.

Levels 1-3 simplify the use of the Finch's wheels, lights, and buzzer. Finch sensors are still available in the "sensing" category and control structures are in "control", but they have not been simplified. 

Level One, Simple Blocks

Level one introduces the three Finch outputs: movement, light, and sound.

The arrow keys move the Finch forward, backward, left, and right. Forward and backward run 70% speed for one second, whereas left and right turn the Finch roughly 90 degrees on hard flooring.

The colored circles set the Finch LED to the color of the circle; the options are: red, green, blue, cyan, yellow, magenta, and off. Each LED block has a 1/2 second delay built-in, so that you can chain a number of color blocks directly after one another. The LED does not change color until another LED block is activated.

The "Lightning" symbol plays a short 1/2 second beep on the Finch's buzzer.

You can try each block by simply clicking on the block, or you can create a program by dragging these blocks and hanging them off the "When space key pressed" block in the project workspace. We've started this for you with a program that turns the LED green, moves the Finch forward, and beeps. Start this program by pressing the space key.

Level Two, Blocks with Parameters

Level two adds parameters to the mix, allowing you to set the speed of the motors, the color of the LED, and the note played by the beeper.

The four arrow blocks each have a single argument, which is set to 5 by default and can range from 0 to 10; higher values result in faster speeds. Each block completes its motion in half a second and then stops.

The LED block sets the color of the LED. The red, green, and blue intensities are set individually from 0 to 10. There is half second delay built into this block so that you can chain different colors after one another.

The buzzer (lightning) block will play a note from A to G, or a numeric frequency in Hertz. There is a half second delay built into this block as well.

A program is included that uses all three types of blocks.

Level Three, Parameters and Time

Level three removes the built-in delays of each block and adds a separate wait block. For motion, this means that motion blocks will set a speed and the Finch will stick to that speed until a new motion block or the STOP! block is used.

There are now six motion blocks: forward, backward, left, right, STOP!, and a block that allows you to set the left and right wheel speeds of the Finch individually to make arcs and circles.

The buzzer and LED blocks are similar to those of level two, but they do not have a built-in wait. The buzzer block's beep is still a 1/2 second long, but there is no built-in wait, so if you run two buzzer blocks right after one another, you will hear both buzzes at the same time.

The WAIT block pauses program execution for an amount of time set by the number in the block. WAIT measures time in one tenth of a second, so the default WAIT 5 is a half second pause.

We've started a program that moves the Finch, sets its beak to magenta, beeps, waits one second, stops the Finch, sets the beak to green, and beeps again. We also included a second program that uses control structures and sensors (discussed in level 4). This program causes the Finch to move backwards if either of its obstacle sensors detect an obstacle.

Level Four, Regular Snap!

For those unfamiliar with the Snap/Scratch interface, take a look at the reference manual for Snap! and check out the tutorials here (Scratch) and here (Snap). You can also right click on many of the regular Snap! blocks and select "Help.." to get an idea of how they work (most blocks display help, some do not). 

We will focus on explaining how to use the Finch blocks we've added to Snap! If you want to use Finch and Hummingbird together and need instruction on the Hummingbird, visit the Hummingbird's Snap! page.

Finch Blocks

The Finch blocks are distributed among Snap!'s Motion, Looks, Sound, and Sensing categories. 

Motion Commands

  • Move Finch Left: Right:  Sets the power  to the left and right wheels. The range is -100 to 100; for example Move Finch Left: 100 Right: 100 is full forward, Left: -100 Right: -100 is full backwards.
  • stop Finch: Stops the Finch

Looks Commands

  • Finch LED 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 color.

Sound Commands

  • Finch Buzzer Hz ms: Plays the Finch's buzzer with a sound of the frequency specified for the time specified. Range is 20 to 20,000 for frequency.
  • Finch Buzz+Wait Hz ms: Does the exact same thing as Finch Buzzer, but also causes Snap! to halt program execution for the amount of time specified.

Sensing Commands

  • Finch Left and Right Light Sensor: Returns the intensity of light hitting the left or right light sensor. The values are in a range from 0 to 100 where 0 is total darkness and 100 is saturation of the sensor.
  • Finch Light Sensors: Returns both left and right light sensor values as a list.
  • Finch X/Y/Z Acceleration: 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.
  • Finch Accelerations: Returns the X, Y, and Z accelerations as a list
  • 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 Left and Right Obstacle Sensor: These are boolean or predicate blocks, returning true if an object is 1-4" from the sensor and false otherwise.
  • Finch Obstacles: Returns a list of containing the left and right obstacle sensor values.
  • Finch Temperature Celsius: Returns the current temperature in Celsius.
  • Finch Temperature Fahrenheit: Returns the current temperature in Fahrenheit.

Say This Block

We've added one more block to both Finch and Hummingbird block libraries. It's called "Say This" and it will cause the computer to speak whatever text is placed in the box. It is in Snap!'s Sound category.

Step by Step Examples

We have created six step by step examples that demonstrate how to create Snap! and Finch projects. Check them out below. Please note that our example programs are for the Birdbrain Robot Server, but you can use this converter to create a version that is compatible with the Finch Connection App for Chromebooks.

Name Description Difficulty
Simple Remote Use the keyboard to control the Finch's movement and beak color Beginner
Obstacle Avoider Automatically detect and drive around obstacles Beginner
Finch Dance Make the Finch dance by using movement, LED, and wait blocks Beginner
Light Follower Program the Finch to follow a flashlight Intermediate
Simon Says Create an interactive game using the Finch as a controller Advanced
Finch Pong Use the Finch to control the paddle in a game of Pong Advanced

Assignments and Activities

Check out assignments and activities designed for Snap! appropriate for elementary, middle , and high school. Please note that all of the Snap! sample programs for these activities were created for the Birdbrain Robot Server; this sample code must be converted with this utility if you want to run it on a Chromebook.

Saving and Loading Projects

Snap! provides for three different ways to save a project; which you use is up to you. They are:

  • Save Project in the Cloud. This option allows you to easily save and load projects on different computers, but requires an internet connection as well as an account (which can be made by clicking the "cloud" button in the top left). Currently projects from one user are not shareable with others, though this may change.
  • Save Project in Brower. This option saves the project in the browser cache, so it is only accessible if the same user opens the same browser on the same computer. If the cache is cleared, these projects disappear.
  • Export Project. This option opens a new browser window containing an xml file containing the project's data. You must then use the browser's "Save Page" option to save the file with a .xml extension. This is a good way to distribute example files to many people at once until cloud storage allows sharing. If you need to convert a project made with the Birdbrain Robot Server to one that is compatible with the Chrome app (or vice versa), you will need to export the project as a .xml file in order to use the converter utility

To access the file menu for saving and loading, click on the file button in the top left corner. If you select Save or Save as you will open a window from which you can choose to either save the file locally or in the cloud. To create an xml file instead, click Export Project....

To load a project from the browser cache or from the cloud, click on Open. To open a project from an xml file, click on Import.. and browse to the location of your xml file.

Known Issues and Troubleshooting

  • Launching Snap! from the application may result in a gray or white blank browser window. If this happens, try reloading the page two times in a row. If that still fails, you can visit and import the Finch or Hummingbird blocks directly. Download the Finch xml file and Hummingbird xml file, and then in the Snap! interface go to the File icon->Import... and select the FinchSnapBlocks.xml or HummingbirdSnapBlocks.xml. Or, you can simply drag the .xml file from explorer or finder onto a browser page that has Snap! loaded.
  • If you are running an older version of the Birdbrain Robot Server (downloaded prior to May 2017), the sensor values may update very slowly. This is caused by App Nap putting the BirdBrain Robot Server to sleep. We recommend that you uninstall the Birdbrain Robot Server and install the most recent version. To manually disable App Nap on the BirdBrain Robot Server, CTRL-click on the BirdBrain Robot Server application and select Get Info in the resulting menu. In the Info window, check the box for Prevent App Nap:

  • In Mac/Linux, if both Finch and Hummingbird are plugged in, you may see a 5-10 second delay after you try closing the server, and you may get an error message on close.
  • In Mac/Linux, occasionally the application will not quit when you try to close the window - end the process with force quit in mac, or kill in linux.
  • In Mac/Linux, you must plug in the Finch prior to launching the BirdBrain Robot Server
  • Levels 1-3 were added on February 18, 2015. Upgrade the BirdBrain Robot Server if you do not see these levels.
  • If the robot seems to stop responding for any reason, there is no need to close the Snap! browser window. Close the BirdBrain Robot Server application instead and re-open it.
  • The Finch Connection App for Chrome must stay visible on the desktop if using it with a Macbook running OS 10.9 or later. If the app is minimized, sensor values will stop updating and output commands will be sent very slowly.

Technical Details


This section describes how the BirdBrain Robot Server works to connect Snap! and Finch and Hummingbird; it isn't necessary to read if you're just looking to use Snap!

Snap! and the BirdBrain Robot Server application communicate using Snap!'s native http:// block. This block allows Snap! to receive data from the BirdBrain Robot server and issue commands using URL's. In order to do so, our server needs to have a "cross-domain filter" to allow http:// get requests from outside the server's domain. 

Finch and Hummingbird both have extensive Java API's, and so we decided to use Jetty, a java-based library for creating servers. Jetty is light-weight, can be embedded into regular Java code, and allows cross-domain filters.

Data Flow

At a high-level, here's a description of how data flows between Snap!, the server, and the Finch/Hummingbird API exposed by the server:

  1. User clicks on a custom block that parses any inputs (using join block from the Snap! interface) and sends an encoded url string to the http:// block
  2. The server gets the URL and a servlet for Finch or Hummingbird parses it.
  3. The servlet will use the data in the URL to set an output or read from an input.
  4. The servlet may return data based on the URL and whether it's a sensor command.
  5. If the custom block is of the reporter or predicate type, it reports this data.

As an example, here's how the generic server provided on this page makes text to speech capability available in Snap!

  1. User clicks on the Say This block, pictured above left, which is part of a custom block library that gets automatically loaded by clicking "Open Snap!". Say This has as an input a string that defaults to "Hello" (we think computers should start friendly). Above right shows how the URL is composed using Snap!'s native join and http:// blocks to send to the server. In this case we have a servlet on http://serverurl/speak/ that will speak any string that comes after speak/. The server is on localhost and on the arbitrarily chosen port 22179 (if you use our code, please change the default port to avoid collisions with our server). You can check out how all of our blocks are made simply by right clicking on a Finch or Hummingbird block and selecting edit. 
  2. Parsing in this case is very simple, as any string after speak/ gets spoken. 
  3. We use the third party freeTTS library to set up a text to speech "voice" and convert it to a wav file. We're using a few wrapper classes from the Carnegie Mellon CREATE lab's commons library to play that wav file.
  4. In this case, the servlet does not return data. Returning data is as simple as calling response.getWriter().print("Data to return").
  5. Even if we had returned data, Say This is a command style block and so the report portion is ignored.

Additional Considerations

Our server has a few other features to try to make it easier for kids to launch Snap! with our libraries loaded. They are:

  1. Graphical window that has a large "Open Snap!" button which opens Snap! in the default browser.
  2. Open Snap! actually opens a URL that automatically loads the custom block library containing Say This, Finch, and/or Hummingbird blocks. The following URL will open Snap!'s website with the block library for Finch loaded:
  3. The server also checks if is accessible. If it is not, it will open a local copy of Snap! (source downloaded on 3/20/2013). If it is accessible, opening a local copy is still an option.

Source Code

We provide the code and libraries for the entire utility on github. The key files to look at and understand are all souce java files and web.xml. 

Creative Commons License
The source code of this work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License. Third-party libraries used by the source may be licensed differently.