Sphero API Tutorial - Revision history

Mark at 07:34, 27 November 2015

2015-11-27T07:34:52Z

← Older revision		Revision as of 07:34, 27 November 2015
Line 6:		Line 6:
	Source: [https://github.com/orbotix/DeveloperResources/tree/master/docs https://github.com/orbotix/DeveloperResources/tree/master/docs]</ref>.		Source: [https://github.com/orbotix/DeveloperResources/tree/master/docs https://github.com/orbotix/DeveloperResources/tree/master/docs]</ref>.

	Making sense of the Sphero API is greatly motivated for those who wish to implement an interface to the device from a new platform that isn't officially supported by others. For example, the [http://www.mathworks.com/matlabcentral/fileexchange/48359-sphero-matlab-interface\|Sphero MATLAB Interface], ~~co-~~authored by Yi Jui Lee ~~and myself~~ forms the major basis for my interest.		Making sense of the Sphero API is greatly motivated for those who wish to implement an interface to the device from a new platform that isn't officially supported by others. For example, the [http://www.mathworks.com/matlabcentral/fileexchange/48359-sphero-matlab-interface\|Sphero MATLAB Interface], authored by Yi Jui Lee, forms the major basis for my interest.

	Subsequent work that sprung out of the efforts set forth by Yi Jui with Sphero MATLAB Interface include my re-write and extension of this project, [[Sphero API Matlab SDK]]. Code for this project can be found on [http://community.gosphero.com/discussion/2966/sphero-api-matlab-sdk-just-released-on-matlab-file-exchange\| Matlab File Exchange (Sphero API Matlab SDK)] and announced at [http://community.gosphero.com/discussion/2966/sphero-api-matlab-sdk-just-released-on-matlab-file-exchange\| Sphero Developer Community Forums].		Subsequent work that sprung out of the efforts set forth by Yi Jui with Sphero MATLAB Interface include my re-write and extension of this project, [[Sphero API Matlab SDK]]. Code for this project can be found on [http://community.gosphero.com/discussion/2966/sphero-api-matlab-sdk-just-released-on-matlab-file-exchange\| Matlab File Exchange (Sphero API Matlab SDK)] and announced at [http://community.gosphero.com/discussion/2966/sphero-api-matlab-sdk-just-released-on-matlab-file-exchange\| Sphero Developer Community Forums].

Mark: draft done; edited source links for references

2015-11-26T07:59:59Z

draft done; edited source links for references

← Older revision		Revision as of 07:59, 26 November 2015
Line 1:		Line 1:

	~~{{Work In Progress\|Page}}~~

	~~'''Only the section [[#State Management\|State Management]] is incomplete!'''~~

	This page offers my personal description of the Sphero API used to encode commands and general communication between Sphero and a host computer over a physical Bluetooth connection. This low-level (binary) API is documented by Sphero's developers at their online quick reference<ref name="sphero-api-web">		This page offers my personal description of the Sphero API used to encode commands and general communication between Sphero and a host computer over a physical Bluetooth connection. This low-level (binary) API is documented by Sphero's developers at their online quick reference<ref name="sphero-api-web">
	Sphero Docs API Quick Reference;		Sphero Docs API Quick Reference;
	Source: [http://sdk.sphero.com/api-reference/api-quick-reference/]</ref> as well as in a PDF document hosted on GitHub in Sphero API Developer Resources documentation <ref name="sphero-api-github">		Source: [http://sdk.sphero.com/api-reference/api-quick-reference/ http://sdk.sphero.com/api-reference/api-quick-reference/]</ref> as well as in a PDF document hosted on GitHub in Sphero API Developer Resources documentation <ref name="sphero-api-github">
	Sphero Developer Resources (Orbotix) on GitHub;		Sphero Developer Resources (Orbotix) on GitHub;
	Source: [https://github.com/orbotix/DeveloperResources/tree/master/docs]</ref>.		Source: [https://github.com/orbotix/DeveloperResources/tree/master/docs https://github.com/orbotix/DeveloperResources/tree/master/docs]</ref>.

	Making sense of the Sphero API is greatly motivated for those who wish to implement an interface to the device from a new platform that isn't officially supported by others. For example, the [http://www.mathworks.com/matlabcentral/fileexchange/48359-sphero-matlab-interface\|Sphero MATLAB Interface], co-authored by Yi Jui Lee and myself forms the major basis for my interest.		Making sense of the Sphero API is greatly motivated for those who wish to implement an interface to the device from a new platform that isn't officially supported by others. For example, the [http://www.mathworks.com/matlabcentral/fileexchange/48359-sphero-matlab-interface\|Sphero MATLAB Interface], co-authored by Yi Jui Lee and myself forms the major basis for my interest.

Mark: /* State Management */

2015-11-26T07:58:14Z

State Management

@@ Line 513: / Line 513: @@
 == State Management ==
-{{Work In Progress|Section}}
+Now that we understand the language that Sphero speaks, the last step to implementing Sphero API is learning how to successfully hold a conversation. In other words, just sending commands and receiving responses one at a time is not enough to manage all communications with the device. Managing Sphero's communication state within a client application is imperative in order to maintain consistent representations of device parameters and be prepared to interpret all types of data that may be received from the device at a given instant in time. A sensible perspective through which to approach these considerations is in terms of the attributes of [[#Synchronous Command and Control|Synchronous Command and Control]] and [[#Asynchronous Messages|Asynchronous Messages]] before finally looking at [[#The Big Picture|The Big Picture]].
 == References ==

Mark: /* Packet Structure */

2015-11-25T07:20:16Z

Packet Structure

Show changes

Mark at 07:15, 25 November 2015

2015-11-25T07:15:17Z

← Older revision		Revision as of 07:15, 25 November 2015
Line 20:		Line 20:
	As Sphero is described in its documentation,		As Sphero is described in its documentation,

	:he's electronically a collection of raw inputs and outputs.		: ... he's electronically a collection of raw inputs and outputs.

	Understanding the functionality of the raw inputs and outputs and the ways in which they're connected is not a requirement for success in communicating with Sphero, but does offer insight regarding the purpose and capabilities of Sphero's communication protocol.		Understanding the functionality of the raw inputs and outputs and the ways in which they're connected is not a requirement for success in communicating with Sphero, but does offer insight regarding the purpose and capabilities of Sphero's communication protocol.

Mark: /* Sphero Basics */

2015-11-25T07:14:24Z

Sphero Basics

← Older revision		Revision as of 07:14, 25 November 2015
Line 20:		Line 20:
	As Sphero is described in its documentation,		As Sphero is described in its documentation,

	~~<blockquote>~~		:he's electronically a collection of raw inputs and outputs.
	~~... \|~~ he's electronically a collection of raw inputs and outputs.
	~~</blockquote>~~

	Understanding the functionality of the raw inputs and outputs and the ways in which they're connected is not a requirement for success in communicating with Sphero, but does offer insight regarding the purpose and capabilities of Sphero's communication protocol.		Understanding the functionality of the raw inputs and outputs and the ways in which they're connected is not a requirement for success in communicating with Sphero, but does offer insight regarding the purpose and capabilities of Sphero's communication protocol.

Mark at 07:12, 25 November 2015

2015-11-25T07:12:32Z

← Older revision		Revision as of 07:12, 25 November 2015
Line 2:		Line 2:
	{{Work In Progress\|Page}}		{{Work In Progress\|Page}}

	'''Only the ~~sections [[#MSG Packet Decoding\|MSG Packet Decoding]] and~~ [[#State Management\|State Management]] ~~are~~ incomplete!'''		'''Only the section [[#State Management\|State Management]] is incomplete!'''

	This page offers my personal description of the Sphero API used to encode commands and general communication between Sphero and a host computer over a physical Bluetooth connection. This low-level (binary) API is documented by Sphero's developers at their online quick reference<ref name="sphero-api-web">		This page offers my personal description of the Sphero API used to encode commands and general communication between Sphero and a host computer over a physical Bluetooth connection. This low-level (binary) API is documented by Sphero's developers at their online quick reference<ref name="sphero-api-web">

Mark: /* MSG Packet Decoding */

2015-11-24T03:55:15Z

MSG Packet Decoding

← Older revision		Revision as of 03:55, 24 November 2015
Line 498:		Line 498:

	;DataStreamingMessage		;DataStreamingMessage
	:In this example, we'll specify the ~~all~~ raw and filtered accelerometer data sources should stream with one frame per packet		:In this example, we'll specify that all of the raw and filtered accelerometer data sources should stream with one frame per packet
	:<pre>MASK = 11100000000000001110000000000000b</pre>		:<pre>MASK = 11100000000000001110000000000000b</pre>
	:<pre>ID_CODE = 03h, DLEN = 0Dh = 12 = (6 data sources)(two bytes per data source)(1 frame per packet)</pre>		:<pre>ID_CODE = 03h, DLEN = 0Dh = 12 = (6 data sources)(two bytes per data source)(1 frame per packet)</pre>
	:<pre>packet = [ FFh \| FEh \| 03h \| 00h \| 0Dh \| 00h \| 00h \| 00h \| 0Ah \| 00h \| FBh \| FFh \| DFh \| 00h \| 76h \| 10h \| 24h \| 62h ]</pre>		:<pre>packet = [ FFh \| FEh \| 03h \| 00h \| 0Dh \| 00h \| 00h \| 00h \| 0Ah \| 00h \| FBh \| FFh \| DFh \| 00h \| 76h \| 10h \| 24h \| 62h ]</pre>
	:<pre>		:Data results are decoded in hardware units (i.e. before conversion to physical units) below

			<pre>
	ACCEL_X_RAW = 0000h = 0		ACCEL_X_RAW = 0000h = 0
	ACCEL_Y_RAW = 000Ah = 10		ACCEL_Y_RAW = 000Ah = 10

Mark: /* MSG Packet Decoding */

2015-11-24T03:53:08Z

MSG Packet Decoding

← Older revision		Revision as of 03:53, 24 November 2015
Line 501:		Line 501:
	:<pre>MASK = 11100000000000001110000000000000b</pre>		:<pre>MASK = 11100000000000001110000000000000b</pre>
	:<pre>ID_CODE = 03h, DLEN = 0Dh = 12 = (6 data sources)(two bytes per data source)(1 frame per packet)</pre>		:<pre>ID_CODE = 03h, DLEN = 0Dh = 12 = (6 data sources)(two bytes per data source)(1 frame per packet)</pre>
	~~SpheroCore DEBUG >> sending packet: FF FF 02 11 05 0E 01 90 00 01 E0 00 E0 00 01 00 00 00 00 86~~
	~~SpheroCore DEBUG >> received packet: FF FF 00 05 01 F9~~
	~~MSG:~~
	~~:<pre></pre>~~
	:<pre>packet = [ FFh \| FEh \| 03h \| 00h \| 0Dh \| 00h \| 00h \| 00h \| 0Ah \| 00h \| FBh \| FFh \| DFh \| 00h \| 76h \| 10h \| 24h \| 62h ]</pre>		:<pre>packet = [ FFh \| FEh \| 03h \| 00h \| 0Dh \| 00h \| 00h \| 00h \| 0Ah \| 00h \| FBh \| FFh \| DFh \| 00h \| 76h \| 10h \| 24h \| 62h ]</pre>
	:<pre>		:<pre>
	~~MASK_ACCEL_X_RAW ......... \| 80 00 00 00h~~ = ~~10000000 00000000 00000000 00000000b~~		ACCEL_X_RAW = 0000h = 0
	~~MASK_ACCEL_Y_RAW ......... \| 40 00 00 00h~~ = ~~01000000 00000000 00000000 00000000b~~		ACCEL_Y_RAW = 000Ah = 10
	~~MASK_ACCEL_Z_RAW ......... \| 20 00 00 00h~~ = ~~00100000 00000000 00000000 00000000b~~		ACCEL_Z_RAW = 00FBh = 251
			ACCEL_X_FILT = FFDFh = -33
			ACCEL_Y_FILT = 0076h = 118
			ACCEL_Z_FILT = 1024h = 4132
	</pre>		</pre>
	~~{{Work In Progress\|Section}}~~

	== State Management ==		== State Management ==

Mark: /* MSG Packet Decoding */

2015-11-24T03:47:07Z

MSG Packet Decoding

← Older revision		Revision as of 03:47, 24 November 2015
Line 497:		Line 497:
	Since all data sources are encoded with sixteen bits, the length of the <code>DATA</code> array should exactly double the number of bits set in <code>MASK</code> unless there are multiple data frames transmitted in a single packet. If this is the case, repeat this procedure for successive data frames until all elements are shifted out of <code>DATA</code>.		Since all data sources are encoded with sixteen bits, the length of the <code>DATA</code> array should exactly double the number of bits set in <code>MASK</code> unless there are multiple data frames transmitted in a single packet. If this is the case, repeat this procedure for successive data frames until all elements are shifted out of <code>DATA</code>.

			;DataStreamingMessage
			:In this example, we'll specify the all raw and filtered accelerometer data sources should stream with one frame per packet
			:<pre>MASK = 11100000000000001110000000000000b</pre>
			:<pre>ID_CODE = 03h, DLEN = 0Dh = 12 = (6 data sources)(two bytes per data source)(1 frame per packet)</pre>
			SpheroCore DEBUG >> sending packet: FF FF 02 11 05 0E 01 90 00 01 E0 00 E0 00 01 00 00 00 00 86
			SpheroCore DEBUG >> received packet: FF FF 00 05 01 F9
			MSG:
			:<pre></pre>
			:<pre>packet = [ FFh \| FEh \| 03h \| 00h \| 0Dh \| 00h \| 00h \| 00h \| 0Ah \| 00h \| FBh \| FFh \| DFh \| 00h \| 76h \| 10h \| 24h \| 62h ]</pre>
			:<pre>
			MASK_ACCEL_X_RAW ......... \| 80 00 00 00h = 10000000 00000000 00000000 00000000b
			MASK_ACCEL_Y_RAW ......... \| 40 00 00 00h = 01000000 00000000 00000000 00000000b
			MASK_ACCEL_Z_RAW ......... \| 20 00 00 00h = 00100000 00000000 00000000 00000000b
			</pre>
	{{Work In Progress\|Section}}		{{Work In Progress\|Section}}