# Lights

Lights control the color and brightness of LEDs on a robot.

### Main LED

setMainLed() changes the color of the main LED light, or the full matrix on Sphero BOLT. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as setMainLed({ r: 90, g: 255, b: 90 })

### Random Color

setMainLed(getRandomColor()) chooses a random color value from the full spectrum of 0-255 on each color channel. If used in a loop you can expect the RGB values to be different each time through the loop. On Sphero BOLT, this command sets all 64 pixels on the LED matrix to the specified color. Also see the Color Operators and Color Variables.

### Back LED - Blue Only

setBackLed() sets the brightness of the back aiming LED, aka the "Tail Light". This LED is limited to blue only, with a brightness scale from 0 to 255. For example, use setBackLed(255) to set the back LED to full brightness. Use await delay() to set it on for a duration. For example, to create a dim and a bright blink sequence use:

setBackLed(0);  // Dim
await delay(0.33);
setBackLed(255);  // Bright
await delay(0.33);

await fade() changes the main LED lights from one color to another over a period of seconds. For example, to fade from green to blue over 3s, use: await fade({ r: 0, g: 255, b: 0 }, { r: 0, g: 0, b: 255 }, 3.0)

### Strobe

await strobe() repeatedly blinks the main LED lights. The period is the time, in seconds, the light stays on during a single blink; cycles is the total number of blinks. The time for a single cycle is twice the period (time for a blink plus the same amount of time for the light to be off). Another way to say this is the period is 1/2 the time it takes for a single cycle. So, to strobe green 15 times in 3 seconds, use: await strobe({ r: 255, g: 57, b: 66 }, (3 / 15) * 0.5, 15);

# Sphero BOLT Lights

Sphero BOLT has unique lighting capabilities with a front led, back led, and 8x8 led matrix. The matrix has 3 methods to program in increasing abstraction and sophistication that are very fun to play with! The 3 methods are setting pixels, text, and animations.

### Front LED

setFrontLed() changes the color of the front LED light. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the below magenta color is expressed as setFrontLed({ r: 239, g: 0, b: 255 })

### Back LED

setBackLed() changes the color of the back LED light, aka the "Tail Light" or "Aim Light." Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as seBacktLed({ r: 0, g: 255, b: 0 }). Sphero BOLT has this as an RGB LED on the back, whereas previous Spheros are limited to Blue only.

### Matrix Animation

playMatrixAnimation(0, true) sets an image (1 frame) or animation ( > 1 frame) on the 8x8 LED matrix using 4 characteristrics: frames, palette (limited to 16 colors per animation), fps (speed from 1-30 frames per second), and transition style (fade, or not fade). Use the true boolean to play an animations in a perpetual loop, or false to play it once. If played in a perpetual loop, it will play until interuppted by a new playMatrixAnimation(x), clearMatrix(), pauseMatrixAnimation(), or resumeMatrixAnimation() commands. The animations are tedious to create in a text program, so we recommend generating them in a block program, and copying the code. You can't modify an animation while a program is running because the Sphero Edu app pre-loads the animations on the robot at program start. The animations can take large amounts of data and it would be impossible to send in real-time given the physical limitations of Bluetooth bandwidth. For example, below is a 2 frame animation and corresponding code that animates a smiley face:

async function startProgram() {
playMatrixAnimation(0);
}

registerMatrixAnimation({
frames: [[[1, 1, 6, 6, 6, 6, 1, 1], [1, 6, 6, 6, 6, 6, 6, 1], [6, 6, 1, 6, 6, 1, 6, 6], [6, 6, 6, 6, 6, 6, 6, 6], [6, 6, 6, 1, 1, 6, 6, 6], [6, 6, 6, 1, 1, 6, 6, 6], [1, 6, 6, 6, 6, 6, 6, 1], [1, 1, 6, 6, 6, 6, 1, 1]], [[6, 6, 6, 6, 6, 6, 6, 6], [6, 6, 1, 6, 6, 1, 6, 6], [6, 6, 1, 6, 6, 1, 6, 6], [6, 1, 1, 6, 6, 1, 1, 6], [6, 6, 6, 6, 6, 6, 6, 6], [6, 1, 1, 1, 1, 1, 1, 6], [1, 6, 1, 1, 1, 1, 6, 1], [1, 1, 6, 6, 6, 6, 1, 1]]],
palette: [{ r: 255, g: 255, b: 255 }, { r: 0, g: 0, b: 0 }, { r: 255, g: 0, b: 0 }, { r: 255, g: 16, b: 0 }, { r: 255, g: 128, b: 0 }, { r: 255, g: 191, b: 0 }, { r: 255, g: 255, b: 0 }, { r: 185, g: 246, b: 30 }, { r: 0, g: 255, b: 0 }, { r: 185, g: 255, b: 255 }, { r: 0, g: 255, b: 255 }, { r: 0, g: 0, b: 255 }, { r: 145, g: 0, b: 211 }, { r: 157, g: 48, b: 118 }, { r: 255, g: 0, b: 255 }, { r: 204, g: 27, b: 126 }],
fps: 6,
transition: MatrixAnimationTransition.None
});

### Matrix Animation Controls

pauseMatrixAnimation() pauses an animation or scrolling text. Use resumeMatrixAnimation(); to resume an animation after pausing to start from the last frame played.

### Matrix Clear

clearMatrix() clears the matrix so all matrix LED's are off. Useful if you want to change from displaying playMatrixAnimation(x) to dislpaying a setMainLed().

### Matrix Frame Rate

overrideMatrixAnimationFramerate(20) sets a frame rate for all subsequent animations, from 1 - 30 frames per second. This rate overrides the frame rate set in the animation definition. Set to default to disable this overide and use the default.

### Matrix Transition

overrideMatrixAnimationTransition(MatrixAnimationTransition.Fade);() sets the transition between animation frames to fade, or overrideMatrixAnimationTransition(MatrixAnimationTransition.None);() sets the trasnition to not fade. This transition overrides the type set in the original animation. Set to default to disable this overide and use the default.

### Matrix Rotate

setMatrixRotation(MatrixRotation.180);() rotates the display direction of the matrix for all subsequent animations and scrolling text. 0° is the default, forward facing direction where the origin (0, 0) is maintained in the bottom left corner of the matrix as shown below, 90° is right, 270° is left, and 180° is upside down:

### Matrix Scroll Text

await scrollMatrixText('hi mom!', { r: 66, g: 56, b: 255 }, 30, true); display a string of characters, or use the string builder to include or concatenate variables and sensor values. You are limited to 25 ASCII characters, a single text color, and can set a frame speed from 1 to 30. You can use the buildString() operator here to concatenate dynamic strings and values. When text scrolling starts, using the true boolean forces the program to wait until the scroll completes before continuing to the next command, whereas using the false boolean will progress the program to the next command immediately.

### Matrix Character

setMatrixCharacter() displays a single ASCII character on the LED matrix, in a specified color. For example, use setMatrixCharacter('z', { r: 255, g: 255, b: 255 }) to display "z" in white.

### Matrix Draw

You can programatically draw pixels, lines and fills on the matrix with these 3 commands:

drawMatrixPixel({ r: 0, g: 0, b: 255 }, { x: 2, y: 3 });() draws a single pixel at position X (0 - 7), Y (0-7), in a color.

drawMatrixLine({ r: 0, g: 0, b: 255 }, { x: 2, y: 3 }, { x: 2, y: 7 }); draws a line or from X (0-7) Y (0-7) pixel to X (0-7) Y (0-7) pixel, in a color. Lines can only be drawn bnetween straight or diagonal connections between pixels, such that if you provide pixels that are not in a line, then nothing will be drawn.

drawMatrixBox({ r: 0, g: 0, b: 255 }, { x: 2, y: 3 }, { x: 2, y: 7 });({ r: 255, g: 250, b: 175 }, { x: 2, y: 3 }, { x: 2, y: 7 }); draws an area from an X (0 - 7) Y (0-7) pixel to X (0 - 7) Y (0-7) pixel, in a color.

# Sphero RVR Lights

setLeftHeadlightLed() changes the color of the front left headlight LED on RVR. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above pink color is expressed as setLeftHeadlightLed({ r: 253, g: 159, b: 255 })

setRightHeadlightLed() changes the color of the front right headlight LED on RVR. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above blue color is expressed as setRightHeadlightLed({ r: 0, g: 28, b: 255 })

### Left LED

setLeftLed() changes the color of the LED on RVR's left side (which is the side with RVR's battery bay door). Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as setLeftLed({ r: 0, g: 255, b: 34 })

### Right LED

setRightLed() changes the color of the LED on RVR's right side (which is the side with RVR's power button). Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above red color is expressed as setRightLed({ r: 255, g: 18, b: 0 })

### Front LED

setFrontLed() changes the color of RVR's front two LED headlights together. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above magenta color is expressed as setFrontLed({ r: 239, g: 0, b: 255 })

### Back LED

setBackLed() changes the color of the back LED light, aka the "Tail Light" or "Aim Light." Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as setBackLed({ r: 0, g: 255, b: 0 }).

# BB-9E Lights

### Dome LEDs

setDomeLeds() controls the brightness of the two single color LEDs (red and blue) in the dome, from 0 to 15. We don't use 0-255 for this light because it has less granular control. For example, set them to full brightness using setDomeLeds(15).

# R2-D2 & R2-Q5 Lights

### Front LED

setFrontLed() changes the color of the front LED light. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above fuchsia color is expressed as setFrontLed({ r: 232, g: 0, b: 255 })

### Back LED

setBackLed() changes the color of the back LED light. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as setBackLed({ r: 0, g: 255, b: 0 }).

### Holo Projector LED

setHoloProjectorLed() changes the brightness of the Holographic Projector white LED, from 0 to 255. For example, set it to full brightness using setHoloProjectorLed(255).

### Logic Display LEDs

setLogicDisplayLeds() changes the brightness of the Logic Display LEDs, from 0 to 255. For example, set it to full brightness using setLogicDisplayLeds(255).