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

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

samples/Collisions/README.md

@@ -0,0 +1,54 @@
+![logo](http://update.orbotix.com/developer/sphero-small.png)
+
+# Collision DetectionSphero 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 FeaturesThe 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 ThresholdsThe 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 DataAn impact is reported via an asynchronous messages to the phone.  The details of the impact are reported using two different methodologies.First, the actual power impact value is given in xMagnitude and yMagnitude. These values are the power that was detected in the impact and were compared to the threshold to determine a reportable collision. The Axis field indicates which (or both) axis crossed the threshold and is being reported.  In the sample of code, these values are:
+
+	final CollisionDetectedAsyncData collisionData = (CollisionDetectedAsyncData) asyncData;
+
+	collisionData.hasImpactXAxis()
+	collisionData.hasImpactYAxis();
+		
+	CollisionPower power = collisionData.getImpactPower();
+	power.x;
+	power.y;
+The second methodology is the impact values read from the accelerometer at the highest peak of impact. X and Y are the "flattened" values given by the accelerometer, and are calculated by removing the Z axis influence. In other words, they represent impact values only on the plane of the surface that Sphero is running on. X and Y have both positive and negative values. Positive values are based on the front (Y) and right (X) side of the ball. The Z reported value is always zero.  Also, the speed of the ball at the time of the reported impact is given by the Speed output. The values can be received in code by:
+
+	Acceleration acceleration = collisionData.getImpactAcceleration();	acceleration.x;      
+	acceleration.y;           
+	collisionData.getImpactSpeed();The timestamp can be used to synchronize collisions in a multi-ball scenario.	collisionData.getImpactTimeStamp();## Questions
+
+For questions, please visit our developer's forum at [http://forum.gosphero.com/](http://forum.gosphero.com/)

samples/Locator/README.md

@@ -0,0 +1,33 @@
+![logo](http://update.orbotix.com/developer/sphero-small.png)
+
+# LocatorSphero 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 DataThe 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.
+3. **newY**: Set the current Y coordinates of Sphero on the ground plane in centimeters.
+4. **newYaw**: Controls how the X,Y-plane is aligned with Sphero’s heading coordinate system. When this parameter is set to zero, it means that having yaw = 0 corresponds to facing down the Y- axis in the positive direction. The value will be interpreted in the range 0-359 inclusive.The Set Heading (Calibrate) command also affects locator coordinates in a different way.  Assume no Configure Locator commands are sent.  Then heading 0 corresponds to the positive Y-axis.  The Set Heading command changes the meaning of “heading 0”.  There are two options:1. The locator Y-axis continues to correspond to heading 0 but points in a different real-world direction. (yaw tare is unchanged, see the discussion of yaw tare in Appendix A)2. The locator Y-axis continues to point in the same real-world direction but corresponds to a different heading angle. (yaw tare is modified).
+Depending on your particular needs, one of these behaviors may be more useful/intuitive.  We think of the first option as “no correction” and the second as “auto-correction”.  You can turn this feature on and off with the configure Locator command.  If the first flag bit is set to true auto-correction is turned on.  This is the default configuration.
+## Making the Most of the Locator
+Depending on your needs there are a few ways to set up and use the Locator.1. Do you need to know position (go to 2) or just distance traveled (go to 3)?2. Do you want to use roll commands to move Sphero to specific locator positions (go to 4) or does it suffice to simply know where Sphero is (go to 5)?3. Do you want to know an arc length/odometer distance (go to 6) or do you want to the distance “as the crow flies” (go to 5)?4. See The Full Setup.5. See The Default Setup.6. See Distance Traveled.## The Default SetupSign up for locator position streaming.  Leave the locator in its default configuration with flag 0 set to true.  The application may use the standard joystick and calibration UI elements freely.## Distance TraveledSign up for locator velocity streaming.  Leave the locator in its default configuration with flag 0 set to true.  The application may use the standard joystick and calibration UI elements freely.  If you want to keep track of distance in the odometer sense, when a data streaming callback comes in accumulate a total using the following formula:
+	Distance Traveled += √(Vx^2 + Vy^2 ) * dt
+Where *Vx* and *Vy* are the x and y velocity components and dt is the time between data samples.  Rather than actually measuring dt (and fighting with Bluetooth latency to get a good timestamp) it is better to synthesize it using the formula:
+	dt = N/420Where N is the divisor used in the Set Locator Streaming command.## The Full Setup
+The easiest way to use locator coordinates and roll command headings together in your app is to turn auto-correction off (set the first flag bit to false) and avoid the Set Heading command altogether.  You may freely use the Configure Locator command to set the location of Sphero as long as you always set yaw tare to zero.  Again, do not use the Set Heading command!
+Your app may freely use the standard joystick UI element.  Unfortunately, the calibration UI element uses the Set Heading command and so should be avoided.  To achieve the same effect one can use Roll commands with a speed of zero to rotate the ball.  Of course, this does not change the meaning of yaw angles the same way Set Heading does.  In order to simulate this effect, you must maintain a private yaw offset, which you set when reorienting the ball.  Your joystick (or other control mechanism) must be modified to add this yaw offset to every outgoing roll command.In this way, the user gets all the functionality of the set heading command without altering the locator coordinate system or the IMU headings.  If you want to drive from one location toward another the following formula gives the heading you should use:
+	∅(heading) = (π/2) - atan2( Ygoto – Ysphero,Xgoto - Xphero )
+This angle is in radians.  In order to use it in a roll command you must convert it to integer degrees in the range [0,359].
+## Questions
+
+For questions, please visit our developer's forum at [http://forum.gosphero.com/](http://forum.gosphero.com/)
+
+	  

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>