jigsawrenaissance / sphero-android-sdk

Sphero™ is the amazing robotic ball ( gosphero.com ), this is the repository for the Android SDK for Sphero™. Visit Forum for more information:

Android Developer Quick Start Guide

Overview

This Guide walks you through the basics of creating mobile apps for Android that leverage the Orbotix Sphero SDK. The examples in this guide were built using Java and although we strive to support ALL the various Android devices available there are a few that are known to cause problems. Visit our developer forum for more information. The goal of this developer guide along with sample code is to give the developer a taste of the wide variety of things Sphero can do, respond to, and keep track of.

In general this guide will walk you through:

• Installing the SDK
• Changing Sphero's Color
• Using the Roll Command to move Sphero

Before we begin - Installing Eclipse

Notice: The Sphero Android SDK works with Android 2.2+

Before you begin to develop applications that interface with Sphero on Android, you will need to install the Android developer tools. We often use Eclipse but there are many other well written Android IDEs out there and these same basic steps are most often still applicable.

• Install the Android SDK and the Eclipse Plugin

Installing the Sphero Android SDK

• Download the latest version of the Sphero Android SDK
  • You can always keep up to date by watching our GitHub Repository

Create a new Android project in Eclipse.

When creating a new project it is important to take special notice to the Android API Level and the Java compliance level. The Sphero SDK currently supports:

• Andriod API level 8 (Android 2.2) or greater.
• Java language compliance level 6.0(1.6) .

Integrating the Sphero Libraries

Place the libs folder from the SDK into your Android project's folder.

Setting the dependency to RobotLibrary.jar.

Set the dependency in the project's properties in the Properties->Java Build Path-> Libraries dialog. This will allow your project access to all the public method names in RobotLibrary.jar.

Adding the RobotUILibrary source library into the workspace.

Import the library into workspace using Import->General->Existing projects
into Workspace. You can have the importer copy the source into your workspace folder or you can place it into the workspace folder before importing. Once it is imported, you need to set the project dependent on RobotLibrary.jar, which is added using the Properties->Java Build ->Libraries dialog. You will need to add RobotUILibrary as library project to your application project from the projects Properties dialog.

RobotUILibrary is distributed as source, so you can customize the look of the resources to fit in with your applications.

Using the Sphero Android SDK

Add code to connect to a sphero.

The RobotUILibrary includes an Activity called StartupActivity which will handle connectioning to a Sphero. When the activity exits, your are ready to send commands.

• To run the StartupActivity, add the following code to the main activity's onStart() method,

      Intent i = new Intent(this, StartupActivity.class);  
      startActivityForResult(i, STARTUP_ACTIVITY);  
  

This will launch the StartupActivity using the intent, and sets an activity results identifier. The STARTUP_ACTIVITY constant is returned in the onActivityResult() method after the StartupActivity finishes as shown in the code below.

       private final static int STARTUP_ACTIVITY = 0;

       protected void onActivityResult(int requestCode, int resultCode, Intent data){
           super.onActivityResult(requestCode, resultCode, data);
           if(requestCode == STARTUP_ACTIVITY && resultCode == RESULT_OK){
               //Get the connected Robot
               final String robot_id = data.getStringExtra(StartupActivity.EXTRA_ROBOT_ID);  // 1
               if(robot_id != null && !robot_id.equals("")){
                   mRobot = RobotProvider.getDefaultProvider().findRobot(robot_id);          // 2
               }
               //Start blinking
               blink(false);                                                                 // 3
          }
        }

1. This line gets an identifier for the robot that was connected returned from the activity.
2. This line gets a Robot object for the robot identifier which is used to identifier the connected Sphero in other API calls. (The API supports connection to multiple Spheros.)
3. This line calls a method that will be used to blink Sphero's LED.

Add code to blink the RGB LED.

Now it is time to add code that sends a command to Sphero. In this case we will blink the RGB LED blue. Commands are encapsulated by subclasses of DeviceCommand and message to Sphero using DeviceMesssenger singleton. For convenience, DeviceCommand subclasses have class sendCommand() methods that will post messages to the DeviceMessenger singleton. Here is the code for the blink() method sends the SetRGBLEDCommand to blink LED.

   private void blink(final boolean lit){
       
       if(mRobot != null){
           
           //If not lit, send command to show blue light, or else, send command to show no light
           if(lit){
               RGBLEDOutputCommand.sendCommand(mRobot, 0, 0, 0);        // 1
           }else{
               RGBLEDOutputCommand.sendCommand(mRobot, 0, 0, 255);      // 2
           }
           
           //Send delayed message on a handler to run blink again
           final Handler handler = new Handler();                       // 3
           handler.postDelayed(new Runnable() {
               public void run() {
                   blink(!lit);
               }
           }, 1000);
       }
   }

1. This line will send a command to turn off the LED. mRobot is the Robot object that will receive the command, and last three parameters turn of the red, green, and blue components of the LED. A 0 value for the color component will set the LED components brightness off.
2. This line will send a command to turn on the blue LED at full brightness. 255 is full brightness, and is only set for the blue component of the LED.
3. This line creates a Handler that is used to post a delayed call to the blink() method after 1 second with the lit parameter inverted, so the next call toggles the LED on or off.

Modify the AndroidManifest.xml file.

Before running the application, you need to add an activity entry for the StartupActivity to the AndroidManifest.xml file. For convenience, you can copy this from the RobotUILibrary project's AndroidManifest.xml file. Add the following,

	<activity android:name="orbotix.robot.app.StartupActivity"
		android:theme="@android:style/Theme.Translucent"
		android:launchMode="singleTop"/>

• You will also need to add permissions to use bluetooth,

        <uses-permission android:name="android.permission.BLUETOOTH" />
        <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
  

• Add android:launchMode="singleTask" to the main activity.

Run on a device.

• Run the Application on a supported Android Device. Turn Bluetooth ON.

• At this point in time you will want to Pair your Android Device to Sphero from within the settings.

Sendings Roll commands

• Using Roll Commands to Move Sphero.

• Using Roll Commands to Stop Sphero.

  So, you got the LED to blink… that's Awesome! But let's also take advantage of the amazing technology inside Sphero and drive the ball around a little bit. In order to move Sphero you will need to send a RollCommand. The RollCommand takes two parameters.

  1. Heading in degrees from 0° to 360°
  2. Speed from 0.0 to 1.0.

For example, a heading of 90° at a speed of 0.5 will tell Sphero to turn clockwise 90° at half speed (1.0 is full speed). Once this command is issued Sphero will continue at this heading and speed until it hits something or runs out of range, so you will need to stop the ball using the RollCommand and sendStop().

Now, it's time to modify the code. Let's send Sphero forward at full speed for 2 seconds. So, add the following method to the main activity.

    private void drive() {
    	if(mRobot != null) {
    		// Send a roll command to Sphero so it goes forward at full speed.
    		RollCommand.sendCommand(mRobot, 0.0f, 1.0f);                         // 1
    		
    		// Send a delayed message on a handler
    		final Handler handler = new Handler();                               // 2
    		handler.postDelayed(new Runnable() {
				
				@Override
				public void run() {
					// Send a stop to Sphero
					RollCommand.sendStop(mRobot);                               // 3
				}
			}, 2000);
    		
    	}
    }

1. This line sends the heading of 0° and the maximum speed of 1.0 to Sphero.

2. This line creates the handle that is used to send the delayed stop command.

3. This line uses the RollCommand to send the stop.

   Next add a call to drive() in the onActivityResult() below the call to blink().

Run the application on an Android Device, if all went well Sphero should have moved forward just a little.

Where is Sphero going?

If you have successfully completed the quick start guide then Sphero should have moved after running the modified code. What is interesting to note here is that Sphero just went in a random direction. The direction was not random at all, Sphero believe it or not has a front and a back. It is necessary for the application to determine what direction forward is for the user from the point of view of the ball. We call this step Calibration and it is required to properly drive Sphero in a predictable direction. To learn more about calibration and using the BackLED to set Sphero's orientation please check out the UISampler Sample project.