Matrix
Matrix commands control the 8x8 LED matrix on BOLT and the LCD screen on BOLT+.
Matrix Animation
playMatrixAnimation(0, true) sets an image (1 frame) or animation ( > 1 frame) on the matrix using 4 characteristics: 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 animation in a perpetual loop, or false to play it once. If played in a perpetual loop, it will play until interrupted 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 Scroll Text
await scrollMatrixText('hi mom!', { r: 66, g: 56, b: 255 }, 30, true) displays a string of characters. You can also 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 Clear
clearMatrix() clears the matrix so all matrix LED's are off. For example, this is useful if you want to change from displaying playMatrixAnimation(x) to displaying a setMainLed().
Matrix Rotate
setMatrixRotation(MatrixRotation.0) 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 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 Frame Rate
overrideMatrixAnimationFramerate() 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 overrideMatrixAnimationFramerate(0) to disable this override and use the default frame rate set for the subsequent matrix animations in your program.
Matrix Transition
overrideMatrixAnimationTransition(MatrixAnimationTransition.Fade) sets the transition between animation frames to fade, and overrideMatrixAnimationTransition(MatrixAnimationTransition.None) sets the transition to not fade. This transition overrides the type set in subsequent matrix animations. Set to overrideMatrixAnimationTransition() to disable this override and use the default transition for the subsequent matrix animations in your program.
When using a fade transition, the matrix LED colors will fade between each frame. This effect is not noticeable if your frame rate is high (like 30 frames per second), but it is noticeable when you have a low frame rate. When the frame rate is low, you will see each LED color in one frame blend into the color set in the next frame.
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 programmatically 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 colored pixel at the (x, y) coordinate (2, 3).
drawMatrixLine({ r: 0, g: 0, b: 255 }, { x: 2, y: 3 }, { x: 2, y: 7 }) draws a colored line from the (x, y) coordinate (2, 3) to the (x, y) coordinate (2, 7). Lines can only be drawn between straight or diagonal connections between pixels. If you provide pixels that are not in a line, then nothing will be drawn.
drawMatrixFill({ r: 0, g: 0, b: 255 }, { x: 0, y: 1}, { x: 6, y: 7 }) draws a filled colored rectangle from the (x, y) coordinate (0, 1) to the (x, y) coordinate (6, 7).