Snap! with Hummingbird

Redirecting, click if you can see this.

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 a utility, the BirdBrain Robot Server, that allows Finch and Hummingbird to be controlled from within Snap!. The rest of this guide describes installing the utility, opening Snap!, and programming for Finch/Hummingbird in Snap! 

User Guide

Video Tutorials

Installing and Launching Snap!

The following tutorial introduces Snap!, covers installing the BirdBrain Robot Server in Windows, and shows how to launch Snap! from the BirdBrain Robot Server. Fullscreen the tutorial for the best viewing experience.

If the videos are blocked, use these links to download them:

Using Hummingbird in Snap! 

This tutorial covers the Hummingbird blocks and how they are used, provides an overview of the Snap! interface including the regular Snap! blocks and saving and loading projects, and also shows live coding of the Hummingbird in Snap! to trigger a simple robot with a distance sensor and to make a simple ball and paddle game with the paddle controlled by the Hummingbird's knob.



Download the Windows installer and double click on it. Follow the instructions in the installer. Once installation is complete, a short cut 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.

If you are running Mac OS 10.9 (Mavericks) or later, disable "App Nap" on the BirdBrain Robot Server the first time you run it. To do so, 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:



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. 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 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 and/or Hummingbird plugged in, click "Open Snap!". This will launch the Snap! website in your computer's default browser. For the best experience using Snap!, set your default browser to 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.

Programming for Hummingbird in 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 Hummingbird blocks we've added to Snap! If you want to use Finch and Hummingbird together and need instruction on how to use Finch, visit the Finch's Snap! page.

Hummingbird Blocks

Hummingbird Blocks

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

Motion Commands

  • Hummingbird Servo: Sets servos 1 through 4 to a value from 0 to 180 degrees.
  • Hummingbird Motor: Sets motor port 1 or 2 to a value from -100 to 100.
  • Hummingbird Vibration. Sets vibration motor 1 or 2 to an intensity value from 0 to 100.

Looks Commands

  • Hummingbird LED: Sets the intensity of light on a single color LED on ports 1 through 4. Intensity ranges from 0 to 100.
  • Hummingbird TRI-LED 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 color.

Sensing Commands

All sensing commands allow the user to specify a number corresponding to the port the sensor is on. For example, a distance sensor on port three would be read by HB Distance CM 3 or HB Distance Inch 3.

  • Hummingbird Light: Returns the value of a light sensor, range is 0 to 100.
  • HB Temperature C: Returns the value in Celcius of a temperature probe.
  • HB Temperature F: Returns the value in Fahrenheit of a temperature probe.
  • HB Distance CM: Returns the distance to an object from a distance sensor in centimeters. The range is 8 to 60 cm with the kit's range sensor (a value greater than 60 cm should be considered as not seeing an object).
  • HB Distance Inch: Returns the distance to an object from a distance sensor in inches. The range is 3 to 24 inches with the kit's range sensor (a value greater than 24 inches should be considered as not seeing an object).
  • Hummingbird Knob: Returns the value of the hummingbird's knob; range is 0 to 100.
  • Hummingbird Sound: Returns the value of a sound sensor, range is 0 to 100.
  • Hummingbird Raw Sensor: Returns the raw sensor value at the port; range is 0 to 100 and corresponds to the DC voltage at the port. A voltage of 5V is equivalent to a reading of 100, and a voltage of 0V is equivalent to a reading of 0.

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.

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. As importantly, 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.

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.

Example Programs

You can download a set of five example programs demonstrating how to use each of the Hummingbird's sensors to set Hummingbird outputs. If you are looking for more details about using Hummingbird sensors, make sure to read the pdf tutorial included in the zip 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.
  • In Mac OS 10.9 the sensor values may update very slowly. This is caused by App Nap putting the BirdBrain Robot Server to sleep, make sure you have the latest version of the software and follow the instructions in the Installation section for disabling 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.
  • If the Hummingbird 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.

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