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
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
- Download the latest version of the Sphero Android SDK
- You can always keep up to date by watching our GitHub Repository
The first step to making Sphero apps is getting the HelloWorld sample to run correctly. The sample establishes a Bluetooth connection to your Sphero and makes it blink a color. If you can get this sample to work, you are clear to try out more advanced samples (using the same steps), and even integrate Sphero into an existing application.
Start by creating a new Eclipse workspace. Name it something like SpheroDev or MyBallsWorkshop. Make sure you have these workspace settings.
- Andriod API level 8 (Android 2.2) or greater.
- Java language compliance level 6.0(1.6) .
In the samples directory, you will find the RobotUILibrary directory. Because almost all Sphero applications rely on the RobotUILibrary project to connect to a Sphero, we need to import this first. Right click in the package explorer, or click "File" from the menu, and choose import. Under the "General" directory, choose "Existing Projects into Workspace".
From this screen, browse to the RobotUILibrary directory in the samples directory. Once the screen looks like the one below, click finish. You do not need to check the "Copy Project into Workspace" box.
Within the same Eclipse workspace, follow the same steps for importing RobotUILibrary, but this time for the HelloWorld sample.
Notice: After this step, some samples will show an error of:
"The project cannot be built until build path errors are resolved".
To resolve this, simply do Project -> Clean…
Also, if you see the error below, you imported the wrong RobotUILibrary. Make sure you imported the RobotUILibrary under the samples directory.
Run the HelloWorld sample as an Android Application, and you should see the UI to connect to a Sphero pop up. If you click connect, and you see Sphero blink, you have completely your first Sphero app!
At this point, feel free to try out some of the more advanced samples, like StreamingExample, by importing them into your current workspace. If you want to take the awesome game you've already made and integrate Sphero, read on!
When creating a new project, or using an existing 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) .
Place the libs folder from the SDK into your Android project's folder.
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. 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.
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.
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;
private Robot mRobot;
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
}
}
- This line gets an identifier for the robot that was connected returned from the activity.
- 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.)
- This line calls a method that will be used to blink Sphero's 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);
}
}
- This line will send a command to turn off the LED.
mRobotis 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. - 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.
- 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.
When your application is closing, it will call the onStop() method. This is where we should properly disconnect Sphero and revert any changes we made to the device. For example, if we turned on the tail light, we should be sure to turn it off here. Or, if our application drives Sphero, we should be sure to send a RollCommand.sendStop(mRobot) to avoid a runaway ball.
@Override
protected void onStop() {
super.onStop();
mRobot = null;
//Disconnect Robot
RobotProvider.getDefaultProvider().removeAllControls();
}
-
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.
-
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.
- Heading in degrees from 0° to 360°
- 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);
}
}
-
This line sends the heading of 0° and the maximum speed of 1.0 to Sphero.
-
This line creates the handle that is used to send the delayed stop command.
-
This line uses the RollCommand to send the stop.
Next add a call to
drive()in theonActivityResult()below the call toblink().
Run the application on an Android Device, if all went well Sphero should have moved forward just a little.
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.