Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge branch 'master' of github.com:OrbotixInc/MOBILE-ANDROID-SDK

  • Loading branch information...
commit 8bbf40ab7a4e403080f166cc88a7be3ea0491778 2 parents 5445c0b + d898562
@SkylarC SkylarC authored
View
BIN  library/libs/RobotLibrary.jar
Binary file not shown
View
43 release notes/version1.2.md
@@ -0,0 +1,43 @@
+
+## New in this version:
+
+#### New API additions.
+* Locator - The locator API allows you to stream position, and speed as Sphero moves. (Added in firmware 1.20.)
+* Self leveling - Commands Sphero to level it's internal drive mechinism. (Added in firmware 1.20.)
+* Set user hack mode - User hack mode enables ASCII shell commands.
+* Quaternion streaming - API to support data streaming of quaternion orientation data. (Added in firmware 1.20.)
+* Motion time out - Allows client code to set a time out to stop Sphero after the last roll command sent.
+* User default color - Allows client code to set a user preferred color. This is the color used when Sphero first connects to a device and no color command is sent to it.
+* Get power state - Client code can get the current power state and other information about the battery.
+* Option flags - Client code can set options flags that effect some of Sphero's default behaviours.
+
+#### New sample code
+
+* Locator - Demonstrates the use of the new Locator API.
+* RobotMacroSample - Demonstrates creating macros in code, and sending them to Sphero.
+* MacroSample - Demonstrates loading macros made in MacroLab from your code.
+* OptionsFlags - Demonstrates the use of the new options flag command.
+* SelfLevel - Demonstrates how to use the self level command which levels the drive mechanism inside Sphero.
+
+
+
+## Fixes and such:
+
+#### In the API
+
+- Fix issue in data streaming when requesting rax x accelerometer data which caused the data to be streamed incorrectly.
+- The API will now set Sphero into a default state when closing a connect. This will turn off the back LED, data streaming, and collision detection. Also, Sphero is set to the users default color, and stabilization turned on.
+- User can query event counts for acheivement events.
+- Client code can get array of achievements data to present in native views.
+- Multiplayer has new pause state and methods to pause and resume a game.
+- Multiplayer improvements in handling players disconnecting.
+- Fixed issue with closing connection if app enters the background in Multiplayer.
+- Multiplayer API can transition from started state back to lobby state.
+
+#### In the samples
+
+- StreamingExample - Updated to stream quaternion data. Plus, emulates infinite streaming by request a finite number of samples, and resends the data streaming command to continue the streaming. This fixes an issue caused when the application quits without turning off data streaming.
+- All samples - Fixed dependencies errors when importing sample project into an Eclipse workspace.
+
+
+
View
54 samples/Collisions/README.md
@@ -0,0 +1,54 @@
+![logo](http://update.orbotix.com/developer/sphero-small.png)
+
+# Collision Detection
+
+Sphero collision detection is a firmware feature that generates a collision async message when an impact is detected. The detection criteria is based on threshold parameters set via the phone.
+
+## Detection Features
+The collision detection feature detects impacts on the X and Y axis of Sphero.
+The Y axis runs through the forward/backward line of Sphero. The X axis runs from side to side. The Z axis run up and down, but is not a factor in the current implementation.
+
+It detects collisions by measuring the accelerometer values and calculating the power (energy) of the signal in real time. When the power exceeds a threshold value, a collision is reported.
+
+## Detection Thresholds
+The X and Y axis impact thresholds are controlled independently. Each axis has two threshold values, the power of an impact, and a bias based on the speed of the ball. Xt is the threshold for the X axis at a speed of zero. The Xspd bias is added to Xt and becomes the threshold at the maximum speed.
+
+Typical values are in the 40-100 range for Xt and Yt. Typical values for the speed thresholds Xspd and Yspd are 50-100.
+
+These values are dependent on the types of collisions you want to detect. For example, if you only want to detect serious impacts when the ball hits a wall you should set these paramers:
+
+ Wall Hits: Xt=200, Xsp=0, Yt=125, Ysp=0, deadTime=100 (1 second)
+
+These values suggest only pay attention to a power threshold over 125 in the y-direction. And a x threshold over 200 is too high to occur while driving. The deadTime means that after the ball detects a collision, it will delay any more collisions for 1 second after. This is to avoid multiple collision async packets from one collision.
+
+Ball to ball collisions is a little bit tougher to determine, since Sphero may trigger collisions just driving aorund. However, these parameters will get you fairly accurate collisions at any point on the ball.
+
+ Ball to Ball Hits: Xt=40, Xsp=60, Yt=40, Ysp=60, deadTime=40 (400 ms)
+
+These values suggest a low collision threshold when you are not moving, and a higher one when Sphero is driving at full power. That way, we will minimize the false collisions when just driving around. This also will trigger collisions on both axis. We don't want the deadTime to be as high here, because if we get a false collision before an actual collision, we don't want to ignore the real one.
+
+## Enabling Collision Detection
+Collision Detection is enabled via the Configure Collision Detection command. The Method field should be set to RKCollisionDetectionMethod1, and the X and Y axis impact thresholds should be set, along with the deadTime. The code to configure collision detection is:
+
+ ConfigureCollisionDetectionCommand.sendCommand(mRobot, ConfigureCollisionDetectionCommand.DEFAULT_DETECTION_METHOD, Xt, Yt, Xspd, Yspd, deatTime);
+
+## Registering for Collision Async Data
+
+As with data streaming, you have to register for async data notifications with this line of code after you configure the collision detection:
+
+ DeviceMessenger.getInstance().addAsyncDataListener(mRobot, mCollisionListener);
+
+After this, you must add a method called handleAsyncData that will check for async data of type *RKCollisionDetectedAsyncData*:
+
+ private final AsyncDataListener mCollisionListener = new AsyncDataListener() {
+
+ public void onDataReceived(DeviceAsyncData asyncData) {
+ if (asyncData instanceof CollisionDetectedAsyncData) {
+ final CollisionDetectedAsyncData collisionData = (CollisionDetectedAsyncData) asyncData;
+ // Analyze the Data
+ }
+
+ }
+
+
+## Understanding Collision Data
View
33 samples/Locator/README.md
@@ -0,0 +1,33 @@
+![logo](http://update.orbotix.com/developer/sphero-small.png)
+
+# Locator
+
+Sphero Locator is a firmware feature that provides real-time position and velocity information about the robot. After setting up locator data streaming, you will receive async data packets containting Sphero's X,Y position, and X,Y velocity in cm and cm/s respectively.
+
+In this document we show on iOS how to receive the locator data, and use the Configure Locator command.
+
+
+ Note: This command only works on Sphero's with Firmware 1.20 or greater
+
+## Setting Data Streaming
+
+In the Set Data Streaming command, we recommend a value of 20 <= divisor <= 50 and packetFrames=1 for most purposes. Since the maximum sensor sampling rate is ~420 Hz, if we take divisor=20 and packetFrames=1 we get approx. 420/20 = ~21 packets/second each containing one set of position and velocity data. For iOS devices divisor=20 works well. For many Android devices divisor = 10 or less is possible (42+ samples/second).
+
+
+ final long mask = SetDataStreamingCommand.DATA_STREAMING_MASK_LOCATOR_ALL;
+
+ SetDataStreamingCommand.sendCommand(mRobot, divisor, packet_frames, mask, response_count);
+
+For real time applications setting packetFrames > 1 is usually pointless since you are only interested in the most recent data. However it is possible to obtain all the samples by setting, for instance, divisor=1 and packetFrames=21 (~20 packets/second each containing 21 sets of position/velocity data).
+
+## Interpreting Locator Data
+The locator treats the ground as a 2D plane and provides Sphero’s position in X,Y coordinates. By default, roll heading 0, points down the positive Y-axis with positive X-axis to the right. So, if you shake Sphero awake and send a roll command with heading 0, you will see the Sphero’s Y coordinate counting up. If you then send a roll command with heading 90, Sphero’s X coordinate will count up.
+
+There are two API commands that affect the locator coordinate system. Most obviously, the Configure Locator command allows you to set the position of Sphero and rotate the locator coordinate system with respect to roll headings. For instance, if you would prefer that heading 0 corresponds to the positive X-axis (instead of Y) you could achieve this with the Configure Locator command by setting the yaw tare to 90. This is acheived by calling this command in code:
+
+ ConfigureLocatorCommand.sendCommand(mRobot, flag, newX, newY, newYaw);
+
+The parameters are as follows:
+
+1. **flag**: Determines whether calibrate commands automatically correct the yaw tare value. When 0, the positive Y axis coincides with heading 0 (assuming you do not change the yaw tare manually using this API command). When 1, a roll heading 0 will always increment Y, no matter if you calibrate or not.
+2. **newX**: Set the current X coordinates of Sphero on the ground plane in centimeters.
View
6 samples/Locator/res/layout/main.xml
@@ -300,9 +300,11 @@
</LinearLayout>
<!-- Calibration View must be in a FrameLayout to work, since it draws over top the other objects -->
+
<orbotix.robot.widgets.calibration.CalibrationView
- android:id="@+id/calibration_widget" android:layout_width="match_parent"
- android:layout_height="match_parent" />
+ android:id="@+id/calibration_widget"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent" />
</FrameLayout>
View
BIN  samples/MultiplayerLobby/libs/jmdns.jar
Binary file not shown
View
110 samples/OptionFlags/README.md
@@ -0,0 +1,110 @@
+![logo](http://update.orbotix.com/developer/sphero-small.png)
+
+# Option Flags
+
+ Note: These commands only work on Sphero's with Firmware 1.20 or greater
+
+Option flags are settings that stay with Sphero even after it goes through power cycles. There are currently 5 different settings you can change. These are:
+
+1. Prevent Sleep In Charger
+2. Enable Vector Drive
+3. Disable Self Level In Charger
+4. Tail Light Always On
+5. Enable Motion Timeout
+
+By default, your Sphero only has vector drive enabled.
+
+ Warning: If you are going to change any of these settings, please make sure to set them back to the default upon your app closing
+
+## Get Current Option Flags
+
+To get the current state of the option flags, you must register a response callback when *StartupActivity* returns. Then, you call the command to request the option flags. This is done with the following code:
+
+ @Override
+ protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+ super.onActivityResult(requestCode, resultCode, data);
+
+ if(resultCode == RESULT_OK){
+
+ if(requestCode == sStartupActivity){
+
+ //Get the Robot from the StartupActivity
+ String id = data.getStringExtra(StartupActivity.EXTRA_ROBOT_ID);
+ mRobot = RobotProvider.getDefaultProvider().findRobot(id);
+
+ // Set the response listener that will process get option flags responses
+ DeviceMessenger.getInstance().addResponseListener(mRobot, mResponseListener);
+
+ // Get the current option flags
+ GetOptionFlagsCommand.sendCommand(mRobot);
+ }
+ }
+ }
+
+Now you will be notified by the handleResponse method when you receive a response from Sphero. Retreive the option flags from the following callback:
+
+ private DeviceMessenger.DeviceResponseListener mResponseListener = new DeviceMessenger.DeviceResponseListener() {
+ @Override
+ public void onResponse(DeviceResponse response) {
+
+ if(response instanceof GetOptionFlagsResponse){
+
+ // Cast the get option flags response object
+ GetOptionFlagsResponse getOptionFlagsResponse = (GetOptionFlagsResponse)response;
+
+ // Grab the information of whether the option flags are set or not
+ boolean preventSleepInChargerSet = getOptionFlagsResponse.isOptionFlagSet(
+ GetOptionFlagsResponse.OPTION_FLAGS_PREVENT_SLEEP_IN_CHARGER);
+ boolean enableVectorDriveSet = getOptionFlagsResponse.isOptionFlagSet(
+ GetOptionFlagsResponse.OPTION_FLAGS_ENABLE_VECTORE_DRIVE);
+ boolean diasbleSelfLevelInChargerSet = getOptionFlagsResponse.isOptionFlagSet(
+ GetOptionFlagsResponse.OPTION_FLAGS_DISABLE_SELF_LEVEL_IN_CHARGER);
+ boolean tailLightAlwaysOn = getOptionFlagsResponse.isOptionFlagSet(
+ GetOptionFlagsResponse.OPTION_FLAGS_TAIL_LIGHT_ALWAYS_ON);
+ boolean enableMotionTimeout = getOptionFlagsResponse.isOptionFlagSet(
+ GetOptionFlagsResponse.OPTION_FLAGS_ENABLE_MOTION_TIMOUT);
+
+ }
+ }
+
+Here we are getting the state of each option flag in a boolean variable which will be either false (off) or true (on).
+
+## Set Option Flags
+
+You can change the value of the option flags by sending a bitwise mask to Sphero with the *SetOptionFlagsCommand.sendCommand(mRobot, optionFlags);*. This is done in code by:
+
+ long optionFlags = 0;
+
+ // Logical OR the bit for prevent Sphero from sleep when placed in charger
+ // You would use this to maximize battery life for displaying notifications, visualizations, etc.
+ if( ((CheckBox)findViewById(R.id.checkbox_bit0)).isChecked() )
+ optionFlags |= GetOptionFlagsResponse.OPTION_FLAGS_PREVENT_SLEEP_IN_CHARGER;
+
+ // Logical OR the bit for enabling vector drive
+ if( ((CheckBox)findViewById(R.id.checkbox_bit1)).isChecked() )
+ optionFlags |= GetOptionFlagsResponse.OPTION_FLAGS_ENABLE_VECTORE_DRIVE;
+
+ // Logical OR the bit for disabling self levels when you place Sphero in the charger
+ if( ((CheckBox)findViewById(R.id.checkbox_bit2)).isChecked() )
+ optionFlags |= GetOptionFlagsResponse.OPTION_FLAGS_DISABLE_SELF_LEVEL_IN_CHARGER;
+
+ // Logical OR the bit for keeping the tail light of Sphero always on
+ // This is helpful when demonstrating new users how to use Sphero. They will always know which way it faces.
+ if( ((CheckBox)findViewById(R.id.checkbox_bit3)).isChecked() )
+ optionFlags |= GetOptionFlagsResponse.OPTION_FLAGS_TAIL_LIGHT_ALWAYS_ON;
+
+ // Logical OR the bit for enabling motion timeout
+ // This is useful so if your app crashes or you go out of bluetooth range, then the ball will stop
+ // rolling after the roll timeout
+ if( ((CheckBox)findViewById(R.id.checkbox_bit4)).isChecked() )
+ optionFlags |= GetOptionFlagsResponse.OPTION_FLAGS_ENABLE_MOTION_TIMOUT;
+
+ // Send command to set option flags
+ SetOptionFlagsCommand.sendCommand(mRobot, optionFlags);
+
+Here we set the value of each flag to the value of a UI CheckBox. We then send the command to ball to set the option flags.
+
+## Questions
+
+For questions, please visit our developer's forum at [http://forum.gosphero.com/](http://forum.gosphero.com/)
+
View
BIN  samples/RobotUILibrary/libs/RobotLibrary.jar
Binary file not shown
View
112 samples/SelfLevel/README.md
@@ -0,0 +1,112 @@
+![logo](http://update.orbotix.com/developer/sphero-small.png)
+
+
+
+# Self Level
+
+This sample code demonstrates how to connect to a Sphero and perform the self level command. The self level routine attempts to achieve a horizontal orientation with Sphero. This is what you see Sphero doing when you place it in a charge with Firmware 1.20 or greater. It is also useful for controller apps when you want to level the Sphero in a user's hand.
+
+ Note: This command will only work with Sphero Firmware 1.20 or greater
+
+## Default Self Level Command
+
+A basic self level command can be performed by the developer by calling
+
+ SelfLevelCommand.sendCommand(mRobot);
+
+This will make you Sphero attempt to level itself. You can also provide the RKSelfLevelCommand with settings to customize the self level command to perform perfect for your application. The settings are as follows:
+
+1. **Angle Limit**: The amount of degrees the roll and pitch angles must be within to be considered level.
+2. **Accuracy Time**: The length of time in centiseconds the roll and pitch angles must be within the Angle Limit before it is considered level.
+3. **Timeout**: The length of time in seconds you will allow Sphero to try and self level itself to within the angle limit and accuracy time.
+
+When you do *SelfLevelCommand.sendCommand(mRobot)* the values for these settings it uses are, **Angle Limit** = 2 **Accuracy Time** = 30 (300 milliseconds), **Timeout** = 15.
+
+Additional settings include the options flag. This flag is a bitwise mask the size of a byte. The settings include:
+
+1. **Start Bit**: 0 aborts the routine if in progress. 1 starts the routine.
+2. **Final Angle**: 0 just stops when it satisfies roll and pitch angles. 1 rotates to heading equal to the heading prior to the self level.
+3. **Sleep Bit**: 0 stays awake after leveling. 1 goes to sleep after leveling.
+4. **Control System Bit**: 0 turns control system off after leveling. 1 turns control system on after leveling.
+
+When you do *SelfLevelCommand.sendCommand(mRobot)* the values for these settings it uses are, the **Stop Bit** = 1, **Final Angle Bit** = 1, **Sleep Bit** = 0, and **Control System Bit** = 0.
+
+## Customized Self Level Command
+
+To take advantage of the settings described above, you can implement the custom command with the following code:
+
+ SelfLevelCommand.sendCommand(mRobot, options, angleLimit, timeout, accuracy);
+
+The options flag is created with the following code:
+
+ RKSelfLevelCommandOptions options = RKSelfLevelCommandOptionStart;
+
+To add options to the flag you simply logical or the other options to the options variable. For example, this code below will set all the bits to 1:
+
+ options = SelfLevelCommand.OPTION_START | SelfLevelCommand.OPTION_KEEP_HEADING | SelfLevelCommand.OPTION_SLEEP_AFTER | SelfLevelCommand.OPTION_CONTROL_SYSTEM_ON;
+
+## Self Level Async Response Message
+
+When the self level command completes, either successfully or unsuccessfully, it will send an async message on the it status upon completion. To register to receive async messages, put this code in the handleRobotOnline callback:
+
+ DeviceMessenger.getInstance().addAsyncDataListener(mRobot, mDataListener);
+
+Withing the handleAsyncData callback we print out the async message status code in readable text to a label with the following code:
+
+ private DeviceMessenger.AsyncDataListener mDataListener = new DeviceMessenger.AsyncDataListener() {
+ @Override
+ public void onDataReceived(DeviceAsyncData data) {
+
+ if(data instanceof SelfLevelCompleteAsyncData){
+
+ // Cast the self level complete object
+ SelfLevelCompleteAsyncData resultCode = (SelfLevelCompleteAsyncData)data;
+
+ // Print result to text view at the top of the screen
+ TextView resultTextView = (TextView)SelfLevelActivity.this.findViewById(R.id.txt_self_level);
+
+ // Print result code in human readable format
+ switch( resultCode.getResultCode() ) {
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_UKNOWN:
+ resultTextView.setText("Unknown Error");
+ break;
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_TIMEOUT:
+ resultTextView.setText("Timeout");
+ break;
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_SENSORS_ERROR:
+ resultTextView.setText("Sensors Error");
+ break;
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_SELF_LEVEL_DISABLED:
+ resultTextView.setText("Self Level Disabled");
+ break;
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_ABORTED:
+ resultTextView.setText("Aborted");
+ break;
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_CHARGER_NOT_FOUND:
+ resultTextView.setText("Charger Not Found");
+ break;
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_SUCCESS:
+ resultTextView.setText("Success");
+ break;
+
+ }
+ }
+ }
+ };
+
+## Questions
+
+For questions, please visit our developer's forum at [http://forum.gosphero.com/](http://forum.gosphero.com/)
+
+
+
+
+
+
View
10 samples/SelfLevel/src/com/orbotix/SelfLevelActivity.java
@@ -123,7 +123,7 @@ public void selfLevelPressed(View v) {
public void abortPressed(View v) {
// Easy command to abort self level
SelfLevelCommand.sendCommandAbortSelfLevel(mRobot);
-
+
// Let the user know the ball is aborting self level
((TextView)findViewById(R.id.txt_self_level)).setText("Aborting...");
}
@@ -145,7 +145,7 @@ public void onDataReceived(DeviceAsyncData data) {
// Print result to text view at the top of the screen
TextView resultTextView = (TextView)SelfLevelActivity.this.findViewById(R.id.txt_self_level);
- // Print result
+ // Print result code in human readable format
switch( resultCode.getResultCode() ) {
case SelfLevelCompleteAsyncData.RESULT_CODE_UKNOWN:
@@ -167,7 +167,11 @@ public void onDataReceived(DeviceAsyncData data) {
case SelfLevelCompleteAsyncData.RESULT_CODE_ABORTED:
resultTextView.setText("Aborted");
break;
-
+
+ case SelfLevelCompleteAsyncData.RESULT_CODE_CHARGER_NOT_FOUND:
+ resultTextView.setText("Charger Not Found");
+ break;
+
case SelfLevelCompleteAsyncData.RESULT_CODE_SUCCESS:
resultTextView.setText("Success");
break;
View
1  samples/StreamingExample/src/com/orbotix/streamingexample/StreamingActivity.java
@@ -36,7 +36,6 @@
/**
* AsyncDataListener that will be assigned to the DeviceMessager, listen for streaming data, and then do the
- *
*/
private DeviceMessenger.AsyncDataListener mDataListener = new DeviceMessenger.AsyncDataListener() {
@Override
Please sign in to comment.
Something went wrong with that request. Please try again.