uBit.display

Overview

uBit.display allows you to use the LEDs on the front of the micro:bit.

It provides a driver for a general purpose matrix display along with several high level features that make creating animations and visual effects on the micro:bit LED display easy and fun! This class lets you:

• Control the LED matrix on the micro:bit.
• Use an optimised typeface (font) so you can show upper and lower case letters, numbers of symbols on the display.
• Set display-wide or per-pixel brightness control up to 256 levels per pixel.
• Create, move, paste and animate images.
• Scroll and print images and text.
• Access the screen buffer directly, so you can manipulate individual pixels.

In its normal mode, the display will update every 18ms (55 Hz). If the display is in light saving mode the period is changed to 15ms (66 Hz).

Using the display

When using the uBit object, the display is automatically set up, and ready for you to use. Use any or all of the functions listed in the API section below to create effects on the LED display. Here are a few examples to get you started.

Scrolling text

Simply use the scroll function to specify the message you want to scroll, and sit back and watch the result. The message you provide will be scrolled, pixel by pixel across the display from right to left. If you take a look at the documentation for the scroll function in the API below, you will notice that you can also specify the speed of the scroll as an optional final parameter, in milliseconds. The lower the delay, the faster your text will scroll across the screen.

Example

uBit.display.scroll("HELLO!");
uBit.display.scroll("HELLO!", 100);

Notice that you can also scroll numbers (either constants of variables):

int c = 42;
uBit.display.scroll(c);

Printing text

Sometimes it is better to show the letters/numbers in turn on the screen rather than scrolling them. If you want to do this, print has exactly the same parameters as scroll, but with this one-by-one behaviour:

Example

uBit.display.print("HELLO!");
uBit.display.print("HELLO!", 100);
uBit.display.print(42);

Printing single characters

print behaves slightly differently if you provide a single character or numeric digit. If you do this, the value you provide will stay on the screen until you explicitly change it. If you ask the runtime to print a string with two or more characters, then each will appear in turn, then disappear. Try this and you will find it stays on the screen:

uBit.display.print(7);

Showing images

It is also possible to print and scroll bitmap images on the display. Images are represented in the runtime by using an Image. These can easily be created, just as you create any variable. Once created, you can then provide them as a parameter to the scroll and print functions. Unlike the text based animation functions, you can also specify exactly where in the screen you would like the image to appear - and you can even treat pixel values of zero as transparent if you like!

Here are a few simple examples:

Show a smiley on the screen

Image smiley("0,255,0,255, 0\n0,255,0,255,0\n0,0,0,0,0\n255,0,0,0,255\n0,255,255,255,0\n");
uBit.display.print(smiley);

Make your smiley peep up from the bottom of the screen

Image smiley("0,255,0,255, 0\n0,255,0,255,0\n0,0,0,0,0\n255,0,0,0,255\n0,255,255,255,0\n");
for (int y=4; y >= 0; y--)
{
    uBit.display.image.paste(smiley,0,y);
    uBit.sleep(500);
}

Scroll your smiley across the screen

Image smiley("0,255,0,255, 0\n0,255,0,255,0\n0,0,0,0,0\n255,0,0,0,255\n0,255,255,255,0\n");
uBit.display.scroll(smiley);

Running in the background

By now you have probably noticed that the scroll, print and animate functions are all blocking, in that they wait for the effect requested to finishes before returning. This is by design to allow you to easily synchronise your programs. However, sometimes you want to launch an effect, and let it run in the background while your program does something else.

For this, you can use their async variations. These all have identical parameters and capabilities, but will return immediately. Try some of the examples above with their async equivalents to understand this different behaviour.

For example, here we scroll the smiley across the screen, but then play a sound at the same time:

Example

Image smiley("0,255,0,255, 0\n0,255,0,255,0\n0,0,0,0,0\n255,0,0,0,255\n0,255,255,255,0\n");
uBit.display.scrollAsync(smiley);
uBit.audio.soundExpressions.play(ManagedString("hello"));

Note

Learn about playing sounds on the micro:bit in the uBit.audio documentation.

Changing display mode

uBit.display supports either on/off LED display, or displays where each pixel has an individual brightness value between 0 and 255. The former costs much less processor time and battery power to operate, so it is the default. The latter does provide more useful effects though, so you can change between these modes by using setDisplayMode. Valid values are:

Display mode	Brief Description
DISPLAY_MODE_BLACK_AND_WHITE	Each pixel can be just on or off. Using setBrightness sets the brightness of all pixels.
DISPLAY_MODE_BLACK_AND_WHITE_LIGHT_SENSE	Each pixel can be just on or off, and the display driver will also sense the ambient brightness from the LEDs.
DISPLAY_MODE_GREYSCALE	Each pixel can independently have 256 levels of brightness.

Here, we print a smiley with glowing eyes! Spooky.

Example

Image smiley("0,255,0,255, 0\n0,255,0,255,0\n0,0,0,0,0\n32,0,0,0,32\n0,32,32,32,0\n");
uBit.display.setDisplayMode(DISPLAY_MODE_GREYSCALE);
uBit.display.print(smiley);

Accessing the display buffer

The memory buffer that is used to drive the LEDs is itself an Image. This means that you can also access and call any of the functions there listed directly on the display buffer. Examples here include setPixelValue, as illustrated below, but read the above documentation link for full details.

// set a single pixel by co-ordinate
uBit.display.image.setPixelValue(2,2,255);

Detecting light levels

When we invert the current on an LED, it becomes sensitive to light. We can use this to turn the micro:bit into a light sensor, using readLightLevel. While the display cannot emit light and sense light at the same time, the current implementation allows the display and the light sensor to operate in an interleaving manner. This interleaving is enabled due to a special display mode on the display which is automatically activated when readLightLevel is called by the user.

This special mode (DISPLAY_MODE_BLACK_AND_WHITE_LIGHT_SENSE) increases the rate of the systemTick callback to 5ms. The display is then configured to drop the fourth frame for user processing, which in this case, is entirely consumed by the light sensor. This reduces the display refresh rate from 55Hz to around 50Hz.

readLightLevels will return a value between 0 and 255.

Printing current light level on serial

int main(){
    uBit.init();

    while(true){
        uBit.serial.send(ManagedString(uBit.display.readLightLevel()) + "\n");
        uBit.sleep(100);
    }
}

Other useful functions

• clear will clear the screen immediately.
• stopAnimation will terminate any on-going print, scroll or animate functions.
• setBrightness lets you set the overall maximum brightness of the display, as a value between 1 and 255.
• enable and disable turn on and off the display. When disabled, you can reuse many if the GPIO pins. See uBit.io for more information.

Message Bus Info

Message Bus ID

Constant	Value
DEVICE_ID_DISPLAY	7

Message Bus Events

Constant	Value
DISPLAY_EVT_ANIMATION_COMPLETE	1
MICROBIT_DISPLAY_EVT_LIGHT_SENSE	2

Notify Events

These events use the notification channel DEVICE_ID_NOTIFY, which provides general purpose synchronisation.

Constant	Value
DISPLAY_EVT_FREE	1

API

getWidth

int

getWidth

()

Description

Returns the width of the display

Returns

display width

---

getHeight

int

getHeight

()

Description

Returns the height of the display

Returns

display height

---

setBrightness

int

setBrightness

(

int

b)

Description

Configures the brightness of the display.

Parameters

int

b - The brightness to set the brightness to, in the range 0 - 255.

Returns

DEVICE_OK, or DEVICE_INVALID_PARAMETER

---

getBrightness

int

getBrightness

()

Description

Fetches the current brightness of this display.

Returns

the brightness of this display, in the range 0..255.

---

enable

void

enable

()

Description

Enables the display, should only be called if the display is disabled.

---

disable

void

disable

()

Description

Disables the display.

---

screenShot

Image

screenShot

()

Description

Captures the bitmap currently being rendered on the display.

Returns

a Image containing the captured data.

---

render

void

render

()

Description

Configure the next frame to be drawn.

---

setDisplayMode

void

setDisplayMode

(

DisplayMode

mode)

Description

Configures the mode of the display.

Parameters

DisplayMode

mode - The mode to swap the display into. One of: DISPLAY_MODE_GREYSCALE, DISPLAY_MODE_BLACK_AND_WHITE, DISPLAY_MODE_BLACK_AND_WHITE_LIGHT_SENSE

Example

 display.setDisplayMode(DISPLAY_MODE_GREYSCALE); //per pixel brightness 

---

getDisplayMode

DisplayMode

getDisplayMode

()

Description

Retrieves the mode of the display.

Returns

the current mode of the display

---

enable

void

enable

()

Description

Enables the display, should only be called if the display is disabled.

Example

 display.enable(); //Enables the display mechanics 

Note

Only enables the display if the display is currently disabled.

---

disable

void

disable

()

Description

Disables the display, which releases control of the GPIO pins used by the display, which are exposed on the edge connector.

Example

 display.disable(); //disables the display 

Note

Only disables the display if the display is currently enabled.

---

clear

void

clear

()

Description

Clears the display of any remaining pixels.

display.image.clear() can also be used!

Example

 display.clear(); //clears the display 

---

setBrightness

int

setBrightness

(

int

b)

Description

Configures the brightness of the display.

Parameters

int

b - The brightness to set the brightness to, in the range 0 - 255.

Returns

DEVICE_OK, or DEVICE_INVALID_PARAMETER

---

readLightLevel

int

readLightLevel

()

Description

Determines the last ambient light level sensed.

Returns

The light level sensed, as an unsigned 8-bit value in the range 0..255

---

setSleep

int

setSleep

(

bool

doSleep)

Description

Puts the component in (or out of) sleep (low power) mode.

Parameters

bool

doSleep

---

periodicCallback

void

periodicCallback

()

Description

Frame update method, invoked periodically to strobe the display.

---

stopAnimation

void

stopAnimation

()

Description

Stops any currently running animation, and any that are waiting to be displayed.

---

printCharAsync

int

printCharAsync

(

char

c)

Description

Prints the given character to the display, if it is not in use.

Parameters

char

c - The character to display.

Returns

DEVICE_OK, DEVICE_BUSY is the screen is in use, or DEVICE_INVALID_PARAMETER.

Example

 display.printCharAsync('p'); 
 display.printCharAsync('p',100); 

int

printCharAsync

(

char

c,

int

delay)

Description

Prints the given character to the display, if it is not in use.

Parameters

char

c - The character to display.

int

delay - Optional parameter - the time for which to show the character. Zero displays the character forever, or until the Displays next use.

Returns

DEVICE_OK, DEVICE_BUSY is the screen is in use, or DEVICE_INVALID_PARAMETER.

Example

 display.printCharAsync('p'); 
 display.printCharAsync('p',100); 

---

printAsync

int

printAsync

(

ManagedString

s)

Description

Prints the given ManagedString to the display, one character at a time. Returns immediately, and executes the animation asynchronously.

Parameters

ManagedString

s - The string to display.

Returns

DEVICE_OK, or DEVICE_INVALID_PARAMETER.

Example

 display.printAsync("abc123",400); 

int

printAsync

(

ManagedString

s,

int

delay)

Description

Prints the given ManagedString to the display, one character at a time. Returns immediately, and executes the animation asynchronously.

Parameters

ManagedString

s - The string to display.

int

delay - The time to delay between characters, in milliseconds. Must be > 0. Defaults to: DISPLAY_DEFAULT_PRINT_SPEED.

Returns

DEVICE_OK, or DEVICE_INVALID_PARAMETER.

Example

 display.printAsync("abc123",400); 

---

printChar

int

printChar

(

char

c)

Description

Prints the given character to the display.

Parameters

char

c - The character to display.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 display.printAsync('p'); 
 display.printAsync('p',100); 

int

printChar

(

char

c,

int

delay)

Description

Prints the given character to the display.

Parameters

char

c - The character to display.

int

delay - Optional parameter - the time for which to show the character. Zero displays the character forever, or until the Displays next use.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 display.printAsync('p'); 
 display.printAsync('p',100); 

---

print

int

print

(

ManagedString

s)

Description

Prints the given string to the display, one character at a time.

Blocks the calling thread until all the text has been displayed.

Parameters

ManagedString

s - The string to display.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 display.print("abc123",400); 

int

print

(

ManagedString

s,

int

delay)

Description

Prints the given string to the display, one character at a time.

Blocks the calling thread until all the text has been displayed.

Parameters

ManagedString

s - The string to display.

int

delay - The time to delay between characters, in milliseconds. Defaults to: DISPLAY_DEFAULT_PRINT_SPEED.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 display.print("abc123",400); 

---

scrollAsync

int

scrollAsync

(

ManagedString

s)

Description

Scrolls the given string to the display, from right to left. Returns immediately, and executes the animation asynchronously.

Parameters

ManagedString

s - The string to display.

Returns

DEVICE_OK, DEVICE_BUSY if the display is already in use, or DEVICE_INVALID_PARAMETER.

Example

 display.scrollAsync("abc123",100); 

int

scrollAsync

(

ManagedString

s,

int

delay)

Description

Scrolls the given string to the display, from right to left. Returns immediately, and executes the animation asynchronously.

Parameters

ManagedString

s - The string to display.

int

delay - The time to delay between characters, in milliseconds. Defaults to: DISPLAY_DEFAULT_SCROLL_SPEED.

Returns

DEVICE_OK, DEVICE_BUSY if the display is already in use, or DEVICE_INVALID_PARAMETER.

Example

 display.scrollAsync("abc123",100); 

---

scroll

int

scroll

(

ManagedString

s)

Description

Scrolls the given string across the display, from right to left. Blocks the calling thread until all text has been displayed.

Parameters

ManagedString

s - The string to display.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 display.scroll("abc123",100); 

int

scroll

(

ManagedString

s,

int

delay)

Description

Scrolls the given string across the display, from right to left. Blocks the calling thread until all text has been displayed.

Parameters

ManagedString

s - The string to display.

int

delay - The time to delay between characters, in milliseconds. Defaults to: DISPLAY_DEFAULT_SCROLL_SPEED.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 display.scroll("abc123",100); 

---

animateAsync

int

animateAsync

(

Image

image,

int

delay,

int

stride)

Description

"Animates" the current image across the display with a given stride, finishing on the last frame of the animation. Returns immediately.

Parameters

Image

image - The image to display.

int

delay - The time to delay between each update of the display, in milliseconds.

int

stride - The number of pixels to shift by in each update.

Returns

DEVICE_OK, DEVICE_BUSY if the screen is in use, or DEVICE_INVALID_PARAMETER.

Example

 const int heart_w = 10; 
 const int heart_h = 5; 
 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; 

 Image i(heart_w,heart_h,heart); 
 display.animateAsync(i,100,5); 

int

animateAsync

(

Image

image,

int

delay,

int

stride,

int

startingPosition)

Description

"Animates" the current image across the display with a given stride, finishing on the last frame of the animation. Returns immediately.

Parameters

Image

image - The image to display.

int

delay - The time to delay between each update of the display, in milliseconds.

int

stride - The number of pixels to shift by in each update.

int

startingPosition - the starting position on the display for the animation to begin at. Defaults to DISPLAY_ANIMATE_DEFAULT_POS.

Returns

DEVICE_OK, DEVICE_BUSY if the screen is in use, or DEVICE_INVALID_PARAMETER.

Example

 const int heart_w = 10; 
 const int heart_h = 5; 
 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; 

 Image i(heart_w,heart_h,heart); 
 display.animateAsync(i,100,5); 

int

animateAsync

(

Image

image,

int

delay,

int

stride,

int

startingPosition,

int

autoClear)

Description

"Animates" the current image across the display with a given stride, finishing on the last frame of the animation. Returns immediately.

Parameters

Image

image - The image to display.

int

delay - The time to delay between each update of the display, in milliseconds.

int

stride - The number of pixels to shift by in each update.

int

startingPosition - the starting position on the display for the animation to begin at. Defaults to DISPLAY_ANIMATE_DEFAULT_POS.

int

autoClear - defines whether or not the display is automatically cleared once the animation is complete. By default, the display is cleared. Set this parameter to zero to disable the autoClear operation.

Returns

DEVICE_OK, DEVICE_BUSY if the screen is in use, or DEVICE_INVALID_PARAMETER.

Example

 const int heart_w = 10; 
 const int heart_h = 5; 
 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; 

 Image i(heart_w,heart_h,heart); 
 display.animateAsync(i,100,5); 

---

animate

int

animate

(

Image

image,

int

delay,

int

stride)

Description

"Animates" the current image across the display with a given stride, finishing on the last frame of the animation. Blocks the calling thread until the animation is complete.

Parameters

Image

image

int

delay - The time to delay between each update of the display, in milliseconds.

int

stride - The number of pixels to shift by in each update.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 const int heart_w = 10; 
 const int heart_h = 5; 
 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; 

 Image i(heart_w,heart_h,heart); 
 display.animate(i,100,5); 

int

animate

(

Image

image,

int

delay,

int

stride,

int

startingPosition)

Description

"Animates" the current image across the display with a given stride, finishing on the last frame of the animation. Blocks the calling thread until the animation is complete.

Parameters

Image

image

int

delay - The time to delay between each update of the display, in milliseconds.

int

stride - The number of pixels to shift by in each update.

int

startingPosition - the starting position on the display for the animation to begin at. Defaults to DISPLAY_ANIMATE_DEFAULT_POS.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 const int heart_w = 10; 
 const int heart_h = 5; 
 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; 

 Image i(heart_w,heart_h,heart); 
 display.animate(i,100,5); 

int

animate

(

Image

image,

int

delay,

int

stride,

int

startingPosition,

int

autoClear)

Description

"Animates" the current image across the display with a given stride, finishing on the last frame of the animation. Blocks the calling thread until the animation is complete.

Parameters

Image

image

int

delay - The time to delay between each update of the display, in milliseconds.

int

stride - The number of pixels to shift by in each update.

int

startingPosition - the starting position on the display for the animation to begin at. Defaults to DISPLAY_ANIMATE_DEFAULT_POS.

int

autoClear - defines whether or not the display is automatically cleared once the animation is complete. By default, the display is cleared. Set this parameter to zero to disable the autoClear operation.

Returns

DEVICE_OK, DEVICE_CANCELLED or DEVICE_INVALID_PARAMETER.

Example

 const int heart_w = 10; 
 const int heart_h = 5; 
 const uint8_t heart[] = { 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, }; 

 Image i(heart_w,heart_h,heart); 
 display.animate(i,100,5); 

---

Component Constructor

Advanced users only

Do not use this unless you really know what you're doing. It's usually best to use uBit.

MicroBitDisplay(

const MatrixMap &

map)

Description

Constructor.

Create a software representation of the micro:bit's 5x5 LED matrix. The display is initially blank.

map

The mapping information that relates pin inputs/outputs to physical screen coordinates.

id

The id the display should use when sending events on the MessageBus . Defaults to DEVICE_ID_DISPLAY.

Parameters

const MatrixMap &

map - The mapping information that relates pin inputs/outputs to physical screen coordinates.

MicroBitDisplay(

const MatrixMap &

map,

uint16_t

id)

Description

Constructor.

Create a software representation of the micro:bit's 5x5 LED matrix. The display is initially blank.

map

The mapping information that relates pin inputs/outputs to physical screen coordinates.

id

The id the display should use when sending events on the MessageBus . Defaults to DEVICE_ID_DISPLAY.

Parameters

const MatrixMap &

map - The mapping information that relates pin inputs/outputs to physical screen coordinates.

uint16_t

id - The id the display should use when sending events on the MessageBus . Defaults to DEVICE_ID_DISPLAY.

---