Display

Display commands control the LCD screen of your Sphero BOLT+. Whereas BOLT has an 8x8 LED matrix, BOLT+ has a 128x128 LCD screen. With BOLT, animation and image data for the matrix is stored in the application and sent to the robot when a program is run. This means every time a program starts, the user has to wait while matrix data is transferred over Bluetooth. This is fast enough for matrix assets since there are 8x8 (or 64) "pixels" of data to send per frame. But with the BOLT+ display, that would be 128x128 (or 16,384) "pixels" of data to send per frame. Sending these display assets over Bluetooth would take more time, so all image and animation assets are stored in memory on the BOLT+ robot itself for quick access. As a result, there is  no asset "transfer" step when running a program that uses BOLT+ display commands. 

Display Image

await setDisplayImage() displays an image on the Sphero BOLT+ LCD screen. Set a specific asset on the display by using either the asset ID or the firmware ID. As an example with an asset ID, use  await setDisplayImage("slightly-smiling") to display a smiling emoji on the screen.  As an example with a firmware ID, use await setDisplayImage("287") to display the same smiling emoji on the screen. The library of all supported image assets and their associated IDs can be found below:

Display Animation

await setDisplayAnimation() displays an animation on the Sphero BOLT+ LCD screen. Set a specific asset on the display by using either the asset ID or the firmware ID. As an example with an asset ID, use await setDisplayAnimation("fireworks", true) to display a fireworks animation.  As an example with a firmware ID, use await setDisplayAnimation("1029", true) to display the same fireworks animation. If  true is set then the animation will loop and the program will proceed to the next line of code. This allows you to loop an animation while sending additional commands to your robot . If false is set, the program will wait to run the animation once before your code proceeds. The library of all supported animation assets and their associated IDs can be found below:

Display Text

await setDisplayText() displays user selected text on the Sphero BOLT+ LCD screen. Users have control over: 

• Font size

• Text string

• Text color

• Background color

Here's an example:  await setDisplayText(`Hello\\nWorld!`, { r: 255, g: 255, b: 255 }, { r: 0, g: 0, b: 0 }, 0

To better understand the anatomy of a display text command, let's break this example down: 

 `Hello\\nWorld!`  is the text string. This the text you want to display on the the screen itself. All text must start and end with ` to ensure it escapes properly. Unlike other commands with strings, we use ` instead of " since " is a valid character you can use in the text string itself. \\n is used to set a line break. In this example, \\n ensures that Hello will appear on the first row of the display, and World! will appear on the second row of the display. If this is not properly set, text will run "off" the right side of the screen. Since the BOLT+ firmware does not automatically wrap characters, these line breaks are needed to ensure all characters are on the screen. 

{ r: 255, g: 255, b: 255 }, { r: 0, g: 0, b: 0 } are the RGB values used to set the text color and the background color. In this example, the text will be white on a black background. If both the text color and background color are the same, the displayed text will not be legible. The first RGB value is the text color and the second RGB value is the background color. 

At the very end of the display text command, you can use either 0 or 1 to set the font size. There are two font sizes that you can set, and each will impact the number of characters per line (row) and the number of total lines per the display.
The normal font size allows for 6 lines and 10 characters per line. The large font size allows for 5 lines and 7 characters per line. Make sure you factor in your chosen font size when you manually set line breaks in your text string. 

Supported Characters: 

Both the normal and large fonts are stored in BOLT+ memory. As a result, there are limitations on which characters are supported. Both fonts support  Extended ASCII characters as defined in the ISO/IEC 8859-1 standard. Any entered characters that are not part of the standard will display as a Sphero error character on the BOLT+ screen. Below is a table of the ISO/IEC 8859-1 standard characters that are supported:

Clear Display

clearDisplay() clears the Sphero BOLT+ LCD screen, resulting in it being "off" (black).

clearDisplay() will also clear any matrix images, animations, or text strings that are used with BOLT+. The BOLT+ firmware simulates the behavior of the BOLT LED matrix by displaying an 8x8 grid of colored circles on the display. In this sense, all matrix commands are a subset of display commands, which means matrix images and animations can be cleared with the "clear display" command as well as the "clear matrix" command. 

Display Rotation

setDisplayRotation() rotates the display direction of the Sphero BOLT+ LCD screen for all subsequent images, animations and text. 0° is the default, forward facing direction. 90° is right, 270° is left, and 180° is upside down. 

setDisplayRotation() will also rotate any matrix images, animations, or text strings that are used with BOLT+. The BOLT+ firmware simulates the behavior of the BOLT LED matrix by displaying an 8x8 grid of colored circles on the display. In this sense, all matrix commands are a subset of display commands, which means matrix images and animations can be controlled by the "display rotation" command as well as the "matrix rotation" command. 

Display Sensor Data

await setLiveSensorData()  displays live sensor data on the Sphero BOLT+ LCD screen. Displaying data directly to the screen means it isn't first streamed over Bluetooth to the Sphero Edu application before it's ready for review. Since streaming is bypassed, there is lower latency and and the sample rate for the data is higher.

In order to set the sensor data on the display, you’ll need to send a number to the robot to tell it which sensor to use. Why do we send a number as opposed to a string with the name of the preferred sensor type? That's because we are using a bitmask. A bitmask is a simple, efficient way to tell a robot which of a few options to choose.

A robot only understands binary numbers, or bits ( a portmanteau of binary digit). Binary is a way of doing math where you only have two digits instead of ten by using multiples of two. So 1 in binary is 00000001, 2 in binary is 00000010, and 64 is 01000000. A bit mask is a way of using binary to send a series of yes-no options. In this case, we are stating which sensor we want to show. The table below provides the available sensor options and their respective bitmask numbers that can be used in the await setLiveSensorData() command. The binary is also provided for reference. 

Based on the table above, you would use await setLiveSensorData(16) to display live velocity data, and await setLiveSensorData(64) to display live gyroscope data. 

Display Color

await setDisplayColor() sets the Sphero BOLT+ LCD screen to a user selected color. As an example, use await setDisplayColor({ r: 0, g: 255, b: 0 }) to display green. To randomize the color of the display, you can use await setDisplayColor(getRandomColor()).

 await setDisplayColor() does not have a respective block in the block canvas. As a result, it is only useable in the text canvas.