API and Mobile SDK

Including Documentation, Sample Code and Cutomisable UIKit. Download the SDK from https://github.com/orbotix

iosdeveloperheader.jpg

iOS Developer Quick Start Guide

Resources

Class Documentation


The class documentation is located in api/ as DocSets for use with Xcode. It can be installed by following the Sphero SDK installation steps below. If that does not work or you would like to install the DocSets manually you can simply copy them into the DocSets directory used by Xcode. It is located at

    ~/Library/Developer/Shared/Documentation/DocSets/

Once the DocSets have been copied, restart Xcode and they will then appear in the Documentation section of the Organizer.


Community and Help

Keep up to date by watching our Sphero iOS GitHub Repository

Share your project, get help, and chat with Sphero developers at Sphero Developer Forum

Overview

This Guide walks you through the basics of creating mobile apps for iOS that leverage the Orbotix Sphero SDK. The examples in this guide were built using Objective-C and have been tested with the current released OS and current version of Xcode. 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 Xcode

Notice: The Sphero iOS SDK works with iOS 5.0+

Before you begin to develop applications that interface with Sphero on iOS, you will need to install the iOS developer tools. There is a general assumption that you are using the latest version of Mac OSX, our software is designed to take advantage of all the most current technologies that are offered but it is possible that it will work on older frameworks and technologies.

  • Download and Install the current version of Xcode

Installing the Sphero iOS SDK

There are two ways to integrate the Sphero SDK into your project. You can start a new project that is preconfigured to communicate with Sphero or you can add the RobotKit and RobotUIKit to an existing project. Starting a new project is the fastest way to begin developing applications that utilize and control Sphero.

 

Starting a new Project

Please see the 1.6 release notes for setting up a new project or follow the following Integrating with existing project section)

 

Integrating into an existing project

There are always those cases where you already developed an awesome game or app and want to integrate Sphero functionality or controllability into the project. For those cases we have made it possible to integrate our libraries into your existing project, including some nifty pre-built user interface tools.

  • Download the current Sphero iOS SDK.

  • Simply Drag RobotKit.framework, RobotUIKit.framework and RobotUIKit.Bundle into your project's framework folder.

  • Change your Deployment Target to 6.0

sendingIn.png

!NOTICE: It is important to note that you must also include: ExternalAccessory.framework, CoreMotion.framework

!NOTICE: There are some linker changes that also must be made: Change Build Settings -> Linking -> Other Linker Flags

    -lstdc++
    -all_load
    -ObjC
    -lsqlite3

The HelloSphero example has all the necessary code needed to create and maintain a connection to Sphero, and can be used as a guide in best practices. In general you will need to:

  • You should define two methods in your .h, One to Setup the connection to Sphero and one to maintain the connection.

     BOOL robotOnline;
     -(void)setupRobotConnection;
     -(void)handleRobotOnline;
    
  • Make sure to import RobotKit.h

     #import <RobotKit/RobotKit.h>
    
  • Create a method to handle setting up the Connection to Sphero

     -(void)connectToRobot 
     {   
         [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRobotOnline:) name:RKDeviceConnectionOnlineNotification object:nil];
     if ([[RKRobotProvider sharedRobotProvider] isRobotUnderControl]) 
     {
         [[RKRobotProvider sharedRobotProvider] openRobotConnection];
     }else
     {
         [[RKRobotProvider sharedRobotProvider] controlConnectedRobot];
     }
    
  • Create a method to handle maintaining the Connection to Sphero

      - (void)handleRobotOnline {
          /*The robot is now online, we can begin sending commands*/
          if(!robotOnline) {
              /* Send commands to Sphero Here: */
    
          }
          robotOnline = YES;
      }
    
  • Overload the appDidBecomeActive:(NSNotification*)notification method and initialize the connection to Sphero

     -(void)appDidBecomeActive:(NSNotification*)notification {
         /*When the application becomes active after entering the background we try to connect to the robot*/
         [self connectToRobot];
     }
    
  • In the OnLoad() method you should register for application lifecycle notifications

     - (void)viewDidLoad
     {
         [super viewDidLoad];
         // Do any additional setup after loading the view, typically from a nib.
    
         /*Register for application lifecycle notifications so we known when to connect and disconnect from the robot*/
        [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(appDidBecomeActive:) name:UIApplicationDidBecomeActiveNotification object:nil];
        [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(appWillResignActive:) name:UIApplicationWillResignActiveNotification object:nil];
    
         robotOnline = NO;
     }
    
  • Do not forget to Disconnect from the Robot when the app closes, otherwise next time you start a connection it will already be in use.

     -(void)appWillResignActive:(NSNotification*)notification {
         /*When the application is entering the background we need to close the connection to the robot*/
         [[NSNotificationCenter defaultCenter] removeObserver:self name:RKDeviceConnectionOnlineNotification object:nil];
         [RKRGBLEDOutputCommand sendCommandWithRed:0.0 green:0.0 blue:0.0];
         [[RKRobotProvider sharedRobotProvider] closeRobotConnection];
     }
    

You are now ready to start controlling and receiving information from your Sphero, simply add the following to change the LED Color of Sphero to red:

 [RKRGBLEDOutputCommand sendCommandWithRed:1.0 green:0.0 blue:0.0];

 

Using the Sphero iOS SDK

If you started poking around in the template project you may have noticed that inside ViewController.m there are some commands to set the RGB LED on Sphero. This is best way to change Sphero’s color and give visual feedback using the ball. This command is described in section 3 in more detail but it is a good exercise at this point to change these values and try it out, play around a little bit.

For example, try changing the following command in ViewController.m from

[RKRGBLEDOutputCommand sendCommandWithRed:0.0 green :0.0 blue :1.0];

to

[RKRGBLEDOutputCommand sendCommandWithRed:0.0 green :1.0 blue :0.0];

Notice the change from green of 0.0 to a green of 1.0. Run it and you should have a Green Sphero!

 

Sending Roll Commands

  • Using Roll Commands to Move Sphero.

  • Using Roll Commands to Stop Sphero.

So, you got the LED to blink… thats 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 for 2 seconds. Next we will create 2 new methods, one to Move Sphero, and Delay. And another to Stop Sphero.

        - (void)stop {
            [RKRollCommand sendStop];
        }

        - (void)driveforward {
            [RKRollCommand sendCommandWithHeading:0.0 velocity:0.5];            
            [self performSelector:@selector(stop) withDelay:2.0];
        }

Next add the following code in place of the RGB command that was sent before.

        [self driveforward];

Run the application on an iOS 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.

   

Samples


  • HelloWorld - Connect to Sphero and blink the LED. This is the most compact and easy to follow sample for dealing with Sphero. It is also the default project for the template installer.

  • ButtonDrive - Drive Sphero with simple buttons on screen, just a notch above helloworld.

  • RobotUISample - RobotUISample is a great place to start, it already has elements for two finger calibration, shows you how to use sleep and colorpicker and also has a drive wheel!

  • SensorStreaming - If you want to use the sensor data from Sphero, you should check this sample out. Just simply register as an observer to the data, Pay attention to starting and stoping streaming during the application life cycle.

  • SphereMotion Teapot - This is a sensor streaming application that shows you how to use 3D objects in the screen, the simple teapot, driving by Sphero's motion.

  • RKAchievement Sample - Sphero has a backend web service that can help you maintain Achievements and also keeps track of all the Sphero activity, engage with your users!

android.jpg

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, but 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:

Before we begin - Installing Eclipse

Notice: The Sphero Android SDK works with Android 2.2+ and Java Compiler Level 6.0(1.6)+

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.

Installing the Sphero Android SDK

Available Samples

The Sphero Android SDK has over 15 different sample projects. Starting with these is the best way to get started programming Sphero!

  1. HelloWorld - How to connect to a Sphero and blink it's RGB LED blue.
  2. ButtonDrive - Drive a Sphero by sending roll commands at 0°, 90°, 180°, and 270°.
  3. Collisions - Set up collision detection, a firmware feature that sends an asyncronous message when an impact is detected.
  4. AcheivementSample - Add acheivements to the SpheroWorld back end, and track them from an application.
  5. Locator - How to use the Sphero Locator, a firmware feature that provides real-time position and velocity information about Sphero.
  6. MacroSample - How to connect to multiple balls, programmatically create macros, and run them on multiple Spheros.
  7. MacroLoader - Load macros created in MacroLab and run them on the ball.
  8. MultiplayerLobby - Connect two phones over a wifi network for the use of multiplayer games. This is soon to be deprecated in favor of better services like http://playphone.com/.
  9. OptionFlags - Control option flags, which are settings that persist through Sphero's power cycles.
  10. OrbBasicSample - This sample demonstrates how to load and execute OrbBasic programs on Sphero.
  11. SelfLevel - Connect to Sphero and perform the self level command.
  12. StreamingExample - How to use Sphero's ability to asynchronously stream data from certain control systems and sensors. This allows you to use Sphero as a controller to games.
  13. StreamingAnimation - Move and rotate a 2D object on the screen using Sphero's data streaming.
  14. SpheroMotionTeapot - Move and rotate a 3D object on the screen using Sphero's data streaming.
  15. UISample - This is a great resource for application development. It contains a pre-made drive joystick, a calibration widget, a color changing widget, and a sleep widget.

Importing a Sphero Sample Project

To import a sample into Eclipse, right-click in the project explorer, or click the File menu and select "Import…"

QSG-libs.png

Select the 'Existing Project into Workspace' option under the 'General' tab. Then browse to the folder that holds the HelloWorld Sample. It will be in the directory where you downloaded the Sphero SDK.

QSG-libs.png

At this point there should be no "red X's" or "red !'s" next to the smaple project you just imported. If there aren't any, you are now ready to run it on an Android device. Keep in mind that Sphero projects cannot run inside of the emulator and will fail compilation. If you have problems try these fixes.

  1. Right click the project, and go to Properties. Under the Android tab on the left, the check box next to Android 2.2 (or above) should be checked. If you don't see any Android options, you need to download the Eclipse ADT plugin.QSG-libs.png

  2. Right click the project, and go to Properties. Under the Java Compiler tab on the left, the compiler level should be 1.6 or above.

  3. If the problem still persists, try a "Project -> Clean" in the file menu. 60% of the time, this works all the time.

Create a New Android Project in Eclipse With Sphero or Integrating Sphero Into an Existing Project

If you are 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:

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

Integrating the Sphero Libraries Into Your Project

You can start a new Sphero project using the libraries in the library folder or start a project using one of the sample projects from the samples folder. This quick start guide describes how to start a new project.

To start, create a new Android project in your Eclipse workspace. Then, place the libs folder from the SDK's library folder into your Android project's folder.

QSG-libs.png

Setting the dependency to RobotLibrary.jar

Eclipse should automatically add RobotLibrary.jar to the Android Dependencies folder. But, if it does not, 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.

QSG-jar-depend.png

Using the Sphero Android SDK

Add code to connect to a sphero

The RobotLibrary includes a view called SpheroConnectionView which will handle connecting to a Sphero. When the view sends an onRobotConnected event you are ready to send commands.

  • To use the SpheroConnectionView add the following code to your Activity's xml layout file

    <LinearLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="fill_parent"
        android:layout_height="fill_parent"
        android:background="#ff888888" >
    
        <orbotix.view.connection.SpheroConnectionView
            android:id="@+id/sphero_connection_view"
            android:layout_width="fill_parent"
            android:layout_height="fill_parent"
            android:background="#FFF" />
    
    </LinearLayout>
    
  • This will show the SpheroConnectionView when the Activity starts. It is important to put the view last in a frame layout, so when you hide the rest of your layout will be visible. Also, you must create the listener for the SpheroConnectionView. This will fire events to let you know the user's interaction with the SpheroConnectionView and then you can do what you please. This code snippet shows how to create the listener and how to hide the connection view when a Sphero is connected.

     // Find Sphero Connection View from layout file
    mSpheroConnectionView = (SpheroConnectionView) findViewById(R.id.sphero_connection_view);
    
    // This event listener will notify you when these events occur, it is up to you what you want to do during them
    ConnectionListener mConnectionListener = new ConnectionListener() {
        @Override
        // The method to run when a Sphero is connected
        public void onConnected(Robot sphero) {
            // Hides the Sphero Connection View
            mSpheroConnectionView.setVisibility(View.INVISIBLE);
            // Cache the Sphero so we can send commands to it later
            mSphero = (Sphero) sphero;
            // You can add commands to set up the ball here, these are some examples
    
            // Set the back LED brightness to full
            mSphero.setBackLEDBrightness(1.0f);
            // Set the main LED color to blue at full brightness
            mSphero.setColor(0, 0, 255);
    
            // End examples
        }
    
        // The method to run when a connection fails
        @Override
        public void onConnectionFailed(Robot sphero) {
            // let the SpheroConnectionView handle or hide it and do something here...
        }
    
        // Ran when a Sphero connection drops, such as when the battery runs out or Sphero sleeps
        @Override
        public void onDisconnected(Robot sphero) {
            // Starts looking for robots
            mSpheroConnectionView.startDiscovery();
        }
    };
    // Add the listener to the Sphero Connection View
    mSpheroConnectionView.addConnectionListener(mConnectionListener);
    
  • These events are useful feedback from the user. For example, you could use the onConnectionFailed(Robot sphero) method to prompt the user to check that the Sphero is eligible for connection then retrying the connection.

  • You must also prepare the bluetooth adapter on each start of the app, so that the app is aware of Sphero's nearby so that it can display them and connect to them. It is best practice to do this inside of the onResume() method.

    @Override
    protected void onResume() {
        // Required by android, this line must come first
        super.onResume();
        // This line starts the discovery process which finds Sphero's which can be connected to
        mSpheroConnectionView.startDiscovery();
    }
    
  • You must ensure that the robot is cleaned up properly by ensuring discovery is cancelled, and disconnecting the robot. This is best done in the onPause() method in your activity. Do not forget to stop discovery as this consumes a lot of resources on the device!

    @Override
    protected void onPause() {
        super.onPause();
        BluetoothAdapter.getDefaultAdapter().cancelDiscovery();
        if (mSphero != null) {
            mSphero.disconnect(); // Disconnect Robot properly
        }
    } 
    

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. As opposed to previous versions of the SDK, commands are now sent via the Sphero object that you cached in the previous step. Commands are now sent using the dot method notation, as all objects in Java. Here is the code for the blink() method sends the SetRGBLEDCommand to blink LED.

    private void blink(final boolean lit){

        if(mSphero != null){

            //If not lit, send command to show blue light, or else, send command to show no light
            if(lit){
                mSphero.setColor(0, 0, 0);                               // 1
            }else{
                mSphero.setColor(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. mSphero 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 will need to add permissions to use bluetooth,

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

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.
            mSphero.drive(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
                    mSphero.stop()                                               // 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 tells the ball to 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.

Questions

For questions, please visit our developer's forum at http://forum.gosphero.com/