Using the BirdBlox App

Approx. Time: 
30

The BirdBlox app allows you to program your Hummingbird over Bluetooth using an iPad! To use this app, you will need a Hummingbird Controller, a Hummingbird BLE Adapter, an iPad (iPad 3 or newer, any version of iPad Mini, Air, or Pro) running iOS 8 or later, a computer (to burn the firmware), a USB Cable, and an LED. You can buy the Hummingbird BLE Adapter here.

User Guide


Video Tutorials


Burn Firmware

1. If you have not done so already, Follow the instructions to download and install the Hummingbird Firmware Burner.

2. On windows only: You will need to install drivers for the Hummingbird's bootloader. Download the Hummingbird driver installation program and run it once with administrative privileges.

3. Connect your Hummingbird to your computer using the USB cable.

4. Open the Hummingbird Firmware Burner and select "Switch to Hummingbird Bluetooth Ready Firmware."

5. On the bottom of the Hummingbird, locate the reset button. Press and hold the button for one second, then release it.

6. You should see a message stating that the firmware uploaded successfully. In addition, the status light by the USB port should be slowly fading in and out.

7. Unplug the USB cable so that the Hummingbird is now off.


Attach Hummingbird BLE Adapter

1. On the bottom of your hummingbird, locate the 2x3 pin connectors indicated below. The Hummingbird BLE Adapter will connect to these pins and the bottom four pins on each side of the board.

2. Place the module on the pins and gently slide it into place.


Connect Hummingbird to iPad App

The BirdBlox app works with an iPad 3 or newer, all versions of iPad Mini, Air, and Pro. Your iPad must be running iOS 8 or later, but iOS 9 or later is preferred.

1. On your iPad, open the App Store and search for the "BirdBlox" app or follow the link below.

https://itunes.apple.com/us/app/birdblox/id1120319218?mt=8

2. Plug your Hummingbird into your computer or wall socket.

3. Attach an LED to LED port 1.

4. Open the BirdBlox app. You may see a message telling you to turn on bluetooth. If this happens, tap "Settings" and slide the switch to enable bluetooth.  

5. Return to the BirdBlox app. To connect to your Hummingbird, tap the Hummingbird Connection icon at the top of the screen. Then tap "Connect." Select your Hummingbird from the list of devices. If there is more than one Hummingbird, just pick one.

6. Drag the Hummingbird LED block from the Hummingbird menu to the Scripts area. Click on the 0 and change it to 50.

7. Tap the Hummingbird LED block to turn on the LED. If the LED does not come on, you may have connected to the wrong Hummingbird. Try connecting to a different Hummingbird until you can turn on the LED.

8. Rename your Hummingbird by tapping on the Hummingbird Connection icon at the top of the screen. Then select "Rename." Choose a name for your Hummingbird and tap "Okay." This will make the device easier to identify when connecting to it.

9. You are now ready to program the Hummingbird with your iPad!


Programming with BirdBlox

Birdblox is based on Snap!/Scratch. The blocks in the ControlSensingOperators, and Variables menus are similar to the blocks in the corresponding menus in Snap!. For those unfamiliar with the Snap/Scratch interface, you can learn more about the blocks in these menus at the Scratch Wiki

Using Touch Controls

Using BirdBlox on an iPad is a little different from the normal mouse-and-keyboard interface. You can use the following gestures:

  • Touch and drag blocks to move them.
  • Place your finger on an item and hold it there to perform actions that would usually require clicking, such as accessing menus or duplicating blocks.
  • To edit a number, tap on it and a number pad will appear. Press the check mark to close the number pad when you are done.
  • To edit text, tap on the text and a keyboard will appear. Press "Okay" when you are done.
  • Swipe your finger over an empty (dark gray) part of your screen to scroll. Swiping over blocks will move them rather than scrolling.

Hummingbird Blocks

The blocks on the Hummingbird menu allow you to control the device's motors, servos, and LEDs as well as read sensor values.  

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

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

iPad Blocks

The iPad menu in BirdBlox contains blocks that take advantage of the iPad's built-in sensors.

  • Device Shaken: Returns true if the iPad has been shaken recently. After returning true, the block will return false on subsequent checks until the device is shaken again.
  • Device Latitude/Longitude: Returns a list with the longitude and latitude of the iPad.
  • Device SSID: Returns the SSID (the name) of the Wi-Fi network the iPad is connected to.
  • Device Pressure: Returns an air pressure reading from the device's barometer in kilopascals. This block will only work if you are using an iPad Air 2, iPad Mini 4, iPad Pro, or a newer iPad with a built-in barometer.
  • Device Relative Altitude: Returns the change in the iPad's altitude (in meters) since the Snap for Hummingbird app was opened. This is determined using the device's barometer, which is necessary for the block to work (see the Device Pressure block).
  • Device Acceleration: Returns a list with the g-force in the x, y, and z directions. 1g is the acceleration due to gravity (9.8 meters per second per second).
  • Device Orientation: Returns text which describes the orientation of the iPad. Possible outputs include:
    "Faceup"
    "Landscape: home button on left"
    "Landscape: home button on right"
    "Portrait: home button on bottom"
    "Portrait: home button on top"
    "Facedown"
    "In between"
    If your project is using this block, you may want to lock the screen orientation by swiping up twice from the bottom of the screen and tapping the Orientation Lock icon so it turns white.

Zooming In and Out

To make zoom in or out in BirdBlox, tap the Zoom icon and then select the option that you want. If you are working on a device with a small screen, you may need to zoom in so that you can select blocks more easily.


Saving and Loading Projects

In BirdBlox, you can save a program to the memory of the iPad. It will only be accessible on the current device and will be deleted if the app is uninstalled. To transfer a project to another device or back it up more securely, you can export the program.

To save a project, tap on the File icon and select "Save As." Give your program a name and then tap "Okay."

 

To load a project, tap the File menu icon and then select "Open." Tap on the name of the file that you wish to open.

To move a program from one iPad to another, you can export it. Tap on the File menu and select "Export." Next, tap the "Mail" icon. Then mail the file to yourself!

  

To import a program from your email, click on it and then select "Copy to BirdBlox." You may need to scroll to the right to see this option. The program should then load in the BirdBlox app.


Examples

These step by step example projects show how to use the iPad's touch screen and sensors to control the Hummingbird.

Name Description Difficulty
Motor Mover Create a program that remotely controls a motor or servo using the BirdBlox app Beginner
LED Accelerometer Use a tri-color LED to display the iPad's current acceleration Intermediate
Maze Game Use iPad accelerometer to control a ball in maze game actuated by Hummingbird servos Advanced

The following six projects were originally designed for the browser version of Snap! and will require some slight modifications to work with the BirdBlox app. They are still good examples of what more complicated programs can do.

Name Description Difficulty
Traffic Light Build a working traffic light out of LEDs Beginner
Burglar Alarm Flash LEDs and vibrate when someone gets too close Beginner
Rainbow LED Make a tri-color LED fade through the colors of the rainbow Intermediate
Dimmer LED & Servo Control a servo and LED with a rotation sensor Intermediate
Sprite Sizer Make the cat sprite bigger or smaller with the distance sensor Intermediate
Combination Lock Utilize variables and procedures to make the Hummingbird turn a servo when someone enters the correct combination Advanced

Known Issues and Troubleshooting

  • Currently, when projects are loaded or imported, the name of the project is lost.
  • If you try to connect to your Hummingbird and do not see it in the list of devices, make sure that the board is plugged into AC power or a battery pack. Also, make sure that bluetooth is enabled on your iPad.
  • If you have renamed your Hummingbird, you may notice that the iPad occasionally forgets this name. If this happens, you will need to repeat the process to rename the board.
  • The dot to the left of the Hummingbird Connection icon may remain red even though you are connected to the Hummingbird.