Matrix

Matrix  commands control the 8x8 LED matrix on BOLT and the LCD screen on BOLT+.

Matrix Animation

There are two functions required to play a matrix animation. First, the animation must be registered. 

Register Matrix Animation: 

Registers an image or animation for the 8x8 LED matrix. Allows for both single-frame images or multi-frame animations.

Use the examples below to register a single frame animation in all white for everymatrix LED:
JavaScript:

registerMatrixAnimation({

    frames: [

        [

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0],

            [0, 0, 0, 0, 0, 0, 0, 0]

        ]

    ],

    palette: [{ r: 255, g: 255, b: 255 }],

    fps: 10,

    transition: MatrixAnimationTransition.None

});

Python: 

register_matrix_animation(

    {

        'frames': [

            [

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

                [0, 0, 0, 0, 0, 0, 0, 0],

            ]

        ],

        'palette': [{ 'r': 255, 'g': 255, 'b': 255 }],

        'fps': 10,

        'transition': MatrixAnimationTransition.NONE,

    }

)

Parameters:
animation {object} - The animation object to register, which includes the defined frames, pallet, frame rate, and transition type. 'Frames' is an array of frames; each frame is an 8×8 matrix of palette indices, with each index selecting a color for the corresponding pixel. 'Pallet' is an object of up to 16 colors that can be used for the frames. 'Fps' is a number for the speed at which the frames are shown (from 1 to 30). 'Transition' is a string for the effect between frames (fade or no fade).

Returns:
{number} The index at which the animation is registered

Play Matrix Animation: 

Plays a registered image or animation on the 8x8 LED matrix (BOLT) and the LCD screen (BOLT+), with optional looping. A matrix animation must first be registered with the Register Matrix Animation function before it can be played. If the animation is played in a perpetual loop (true), it will continue until interrupted by a new animation, a clear matrix command, or a pause/resume animation matrix command.

Use the following example to loop the registered animation at index 0:
JavaScript: playMatrixAnimation(0, true)
Python: play_matrix_animation(0, True)

Parameters:
index {number} - number for the specific registered matrix animation
looping {boolean} - Boolean that determines whether the animation should loop indefinitely (true) or play once (false)

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:

JavaScript:

async function startProgram() {

  playMatrixAnimation(0, true);

}

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

});

Python:

async def start_program():

    play_matrix_animation(0, True)

register_matrix_animation({

    '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

})

Compatible Robots:
BOLT, BOLT+

Matrix Scroll Text

Displays a scrolling string of characters on the matrix. 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 "Build String" 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.

Use the example below to scroll text, in blue, at 30 frames per second:
JavaScript: await scrollMatrixText('hi mom!', { r: 66, g: 56, b: 255 }, 30, true)
Python: await scroll_matrix_text('hi mom!', { 'r': 66, 'g': 56, 'b': 255 }, 30, True)

Parameters:
text {string} - The string of scrolling text, limited to 25 ASCII characters
color {{ r: number; g: number; b: number }} - An object containing the RGB color values for the scrolling text (0 to 255 per color channel)
speed {number} - The frame rate of the scrolling text, specified as an integer from 1 to 30
blocking {boolean} - A boolean that controls if the scrolling text completes before moving to the next command (true = on, false = off) 

Compatible Robots:
BOLT, BOLT+

Matrix Clear

Clears the 8x8 LED matrix for BOLT and the LCD screen for BOLT+.

JavaScript: clearMatrix()
Python: clear_matrix()

Compatible Robots:
BOLT, BOLT+

Matrix Rotate

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. 

Use the example below to rotate the matrix 90 degrees:
JavaScript: setMatrixRotation(90)
Python: set_matrix_rotation(90)

Parameters:
rotation {number} - The rotation angle in degrees (0° = default, 90° = right, 180° = upside down, 270° = left)

Compatible Robots:
BOLT, BOLT+

Matrix Animation Controls

Pauses or resumes a matrix animation or scrolling text on the 8x8 LED matrix (BOLT) or the LCD screen (BOLT+). 

Use the examples below to pause the matrix:
JavaScript: pauseMatrixAnimation()
Python: pause_matrix_animation()

Use the examples below to resume the matrix from the last frame played:
JavaScript: resumeMatrixAnimation()
Python: resume_matrix_animation()

Compatible Robots:
BOLT, BOLT+

Matrix Frame Rate

Sets the frame rate for all subsequent matrix animations, overriding the default frame rate defined in the animation. Accepts values from 1 to 30 frames per second. Set to 0 to disable this override and use the default frame rate set for the subsequent matrix animations. 

Use the examples below to set the matrix animation frame rate to 15 frames per second:
JavaScript: overrideMatrixAnimationFramerate(15)
Python: override_matrix_animation_framerate(15)

Parameters:
fps {number} - the desired frame rate (0 to 30)

Compatible Robots:
BOLT, BOLT+

Matrix Transition

Sets the transition effect between matrix animation frames for all subsequent animations. When using a fade transition, the matrix LED colors will fade between each frame. This effect is more noticeable at lower frame rates. If no parameter is provided, the transition override will be disabled and the default will be used.  

Use the examples below to set the transition between animation frames to fade:
JavaScript: overrideMatrixAnimationTransition(MatrixAnimationTransition.Fade)
Python: override_matrix_animation_transition(MatrixAnimationTransition.FADE)

Use the examples below to set the transition between animation frames to not fade:
JavaScript: overrideMatrixAnimationTransition(MatrixAnimationTransition.None)
Python: override_matrix_animation_transition(MatrixAnimationTransition.NONE)

Use the examples below to disable this override and use the default transition for subsequent matrix animations:
JavaScript: overrideMatrixAnimationTransition()
Python: override_matrix_animation_transition()

Parameters:
param {MatrixAnimationTransition} [transition] - the transition type to apply (Fade or None)

Compatible Robots:
BOLT, BOLT+

Matrix Character

Displays a single ASCII character on the 8x8 LED matrix for BOLT and the LCD screen for BOLT+.

For example, use the following to display "z" in white:
JavaScript: setMatrixCharacter('z', { r: 255, g: 255, b: 255 })  
Python: set_matrix_character('z', { 'r': 255, 'g': 255, 'b': 255 }) 

Parameters:
character {string} - A single ASCII character to display
color {{ r: number; g: number; b: number }} - An object containing the RGB color values for the character (0 to 255 per color channel)

Compatible Robots:
BOLT, BOLT+

Matrix Draw

You can programmatically draw pixels, lines and fills on the matrix with these 3 functions:

Draws a single colored pixel at the specified (x, y) coordinate on the 8x8 LED matrix for BOLT and the LCD screen for BOLT+.

Use the example below to draw a single colored pixel at the (x, y) coordinate (2, 3):
JavaScript: drawMatrixPixel({ r: 0, g: 0, b: 255 }, { x: 2, y: 3 })  
Python: draw_matrix_pixel({ 'r': 0, 'g': 0, 'b': 255 }, { 'x': 2, 'y': 3 }) 

Parameters:
color {{ r: number; g: number; b: number }} - An object containing the RGB color values for the pixel (0 to 255 per color channel)
coordinate {{ x: number; y: number }} - An object containing the x and y coordinates for the pixel, between 0 and 7 for each axis

Compatible Robots:
BOLT, BOLT+

Draws a colored line between two specified (x, y) coordinates on the 8x8 LED matrix for BOLT and the LCD screen for BOLT+.

Use the example below to draw a colored line from the (x, y) coordinate (2, 3) to the (x, y) coordinate (2, 7):
JavaScript: drawMatrixLine({ r: 0, g: 0, b: 255 }, { x: 2, y: 3 }, { x: 2, y: 7 })  
Python: draw_matrix_line({ 'r': 0, 'g': 0, 'b': 255 }, { 'x': 2, 'y': 3 }, { 'x': 2, 'y': 7 }) 

Parameters:
color {{ r: number; g: number; b: number }} - An object containing the RGB color values for the fill (0 to 255 per color channel)
from {{ x: number; y: number }} - An object containing the x and y coordinates for the starting point of the line, between 0 and 7 for each axis
to {{ x: number; y: number }} - An object containing the x and y coordinates for the ending point of the line, between 0 and 7 for each axis

Compatible Robots:
BOLT, BOLT+

Draws a filled colored rectangle between two specified (x, y) coordinates on the 8x8 LED matrix for BOLT and the LCD screen for BOLT+.

Use the example below to draw a filled colored rectangle from the (x, y) coordinate (0, 1) to the (x, y) coordinate (6, 7):
JavaScript: drawMatrixFill({ r: 0, g: 0, b: 255 }, { x: 0, y: 1}, { x: 6, y: 7 })  
Python: draw_matrix_fill({ 'r': 0, 'g': 0, 'b': 255 }, { 'x': 0, 'y': 1}, { 'x': 6, 'y': 7 }) 

Parameters:
color {{ r: number; g: number; b: number }} - An object containing the RGB color values for the fill (0 to 255 per color channel)
from {{ x: number; y: number }} - An object containing the x and y coordinates for the top left starting point of the fill, between 0 and 7 for each axis
to {{ x: number; y: number }} - An object containing the x and y coordinates for the bottom right ending point of the fill, between 0 and 7 for each axis

Compatible Robots:
BOLT, BOLT+