header

Get Started

Sphero robots are fun, durable and programmable toys! This wiki is a guide to learn how to program Sphero robots with JavaScript, the most common web programming language in the world. You will need a Sphero robot, the Sphero Edu app on a compatible device, and a hunger to learn. If you're learning to program for the first time, the best place to start is our Structured Activities. If you are a developer interested in building an app for Sphero, use our SDK documentation.

Why JavaScript?

JavaScript is one of the most popular programming languages in the world. It is very useful for building modern websites, and it’s even possible to build website back-end services with extensions of the language. It was originally created in 1995 by Brendan Eich at Netscape, one of the first internet companies which built a popular web browser in the days of dial-up internet. It was originally named "Mocha" by the founder of Netscape, Marc Andreessen, one of Silicon Valley’s most famous entrepreneurs.

Netscape started working with Sun Microsystems, who developed Java, a popular language that powered apps on early computers, handhelds and cell phones. Both companies were motivated to build a plugin so existing Java apps could run natively inside the increasinly popular web browser so they wouldn't need to be rebuilt. So Netscape created a scripting language similar to the Java syntax so these apps could still be used, and just as important, all the Java programmers could quickly adapt without learning a new language from scratch. The langauge also was very powerful. Before JavaScript, most web pages were built of purely HTML and CSS; they were very static. JavaScript allowed pages to be more dynamic, use animations, take input from forms, and playback media.

After a period of competing languages on the web, JavaScript won out as the dominant language, and now you can write JavaScript that renders in all modern web browsers, like Chrome, Safari, Firefox and Internet Explorer on a variety of internet connected devices. If you are considering a career in software development, technology, or robotics, it is a valuable language to know as there are a lot of JavaScript jobs available around the world. Even if you aren't pursuing a career in these fields, you'll get to be creative and solve some intriguing problems through programming.

You might have already even programmed a little JavaScript; it powers the Draw and Blocks programming canvases in the Sphero Edu app, and you can view Javascript code behind those programs. Now you will graduate from drawing lines and dragging blocks to writing the text code yourself.

Hello World!

Using your device with the Sphero Edu app, create a new text program, click the ? button in the upper right to access this wiki, and use the Copy button to copy and paste these code samples into the text canvas. Don't forget to aim your robot, and then tap the Start button to see what happens!

async function startProgram() {
    await speak("Hello World", true);
    setMainLed({ r: 0, g: 0, b: 255});
    setSpeed(60.0);
    await delay (2.0);
    setSpeed(0.0);
}

Hello Square!

Now transform your first program into a Square with more logic:

async function startProgram() {
	setMainLed({ r: 0, g: 0, b: 255 });
	await speak("Hello Square", true);
	await delay(1.0);
	for (var count_702 = 0; count_702 < 4.0; count_702++) {
		setMainLed({ r: getRandomInt(0, 255), g: getRandomInt(0, 255), b: getRandomInt(0, 255) });
		await Sound.Game.Coin.play(true);
		await roll((getHeading() + 90.0), 60.0, 1.0);
		await delay(1.0);
	}
}

Streaming

streamingImage

Your code streams in real-time at 20 hertz (times per second) between your device and the robot, instead of running locally on the robot. This is pretty cool for a few reasons. The memory on Sphero robots is very small, so streaming allows you to use your device memory as the only constraint, which on today's mobile devices and computers is basically limitless. Also, it enables you to interact with the program in real-time through sensor data and other inputs. The streaming nature of your program requires async in certain cases such as before function startProgram(), indicating that data is transmitted to/from the robot whenever it's needed. One downside of streaming is that some commands are slower due to the latency between the device and robot. For example, running a raw motor command of async raw motor(4095, 4095, 0.05) is the fastest (shortest) amount of time you can run raw motor (1s / 20hz = 0.05s). If you used a shorter delay like 0.04s, it would still perform at 0.05s.


Syntax


Syntax is the rule set for how programs are constructed.

Character Case

Most identifiers are tough to describe with one word, so most are 2+ words known as "compound identifiers." Programming langauges generally don't allow spaces in identifers, so character case is the method by which you join compound identifiers to deliminate words. There are hundreds of programming languages in the world, but nearly all of them use one of these four joining methods: thisIsCamelCase, ThisIsPascalCase, this-is-spinal-Case, and this_is_snake_case. Javascript is case sensitive and uses camelCase, such as setSpeed to set the speed.

Punctuation

Code needs to be structured so it can be interpreted by the robot, just like the way humans have agreed on punctation standards in writing. If authors did not write with punctation rules, readers would have a tough time learning new rules in every book they read. Pay very close attention to the use of these characters or your robot will not be able to "read" your program:

async function startProgram() starts a program

{ and } contain all program code, except for global functions and variables

// indicates a comment, and does not affect the program logic

; ends a statement

( ) contains a value

, separates values

_____ a tab space starts the first statement in a program, and subsequent conditions must indent further

Errors

Errors tell you when the robot can't interpret your syntax. In the below example, notice that setSpeed is spelled incorectly. In this case the robot can't read the command and the red error message displays below the erroneous line. Copy this program and fix it so it runs without an error:

async function startProgram(){
    setSpee(188.0)
//!ReferenceError: Can't find variable: setSpee!
    setMainLed({ r: 0, g: 255, b: 0 });
    delay(2);
}

Data Types

There are different types of data in programming that describe how much space a number occupies in storage and how it's interpreted.

Some languages define more data types than others. Javascript uses the follow built-in types:

Most commonly used types
number: values like -7 and 3.14159265359
string: combinations of letters, numbers, and punctuation, like "Don't be L8 to class."
boolean: one of the logical values true or false

Special types with special uses
null: special value meaning "defined as nothing." We'll revisit this idea later.
undefined: another special value meaning, "this variable has never been defined" or, sometimes, "this variable was assigned a nonsensical value"
symbol: a relatively new type for advanced users

Javascript also supplies the Object which we will use to create custom types from the built-in ones.