uBit.display

Overview

The MicroBitDisplay class is a general purpose device driver for controlling LED matrix displays. LED matrix displays are simple, inexpensive devices that use a single LED as a display pixel. They therefore tend to be of relatively low resolution, but often provide visually attractive displays due to the high coherence and brightness of the LEDs.

LEDs in matrix displays are connected to general purpose I/O (GPIO) pins on CPU. Although they could be connected such that each LED has its own GPIO pin, this is not usually the case, as the scarce resource of GPIO pins would soon be used up. For example, on the micro:bit, the LED matrix has 25 LEDs. If this required 25 GPIO pins, then there would be none left for anything else!

Instead, these LEDs are controlled by 12 GPIO pins. Three of those pins provide power to LEDs, the other nine provide a route to ground. The pins that source power are called rows. The pins that sink power are called columns. The following diagram shows how the 5x5 grid is connected into 3 logical 'rows' and 9 'columns':

light-sensing info graphic

Where the format is: ROW.COLUMN

So, if we wanted to light up the middle LED, we would need to put a HIGH voltage (logic 1) on row 2, and a LOW voltage (logic 0) on column 3. Notice that when row 2 is HIGH, we the value we write to the 9 column pins affect all of the LEDs 2.1 to 2.7, without affecting any of the LEDS on row 1 or row 3. Sharing GPIO pins in this way is known as multiplexing. Moreover, if we scan through the different rows fast enough - faster than the eye can see - then we can provide the illusion of all the LEDS being on at the same time! This is a technique known as persistence of vision... and was also the same basis of the very first TV sets (although that did not use LEDs!).

In it's 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).

Capabilities

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

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 though!

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. The lower the delay, the faster your text will scroll across the screen.

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, the 'print' function has exactly the same parameters as 'scroll', but with this behaviour. e.g.

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

Do notice that print behaves slightly differently if you provide a single character or numeric digit though. if you do this, the value you provide will stay on the screen until you explicitly change the screen. If you ask the runtime to print a string with two or more characters, then each will appear in turn, then disappear. e.g. 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 a MicroBitImage. 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! See the MicroBitImage page for more details on images, but here are a few simple examples:

// show your smiley on the screen...
MicroBitImage 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...
MicroBitImage 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...
MicroBitImage 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 all 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 the Async variations of the scroll, print and animate functions. 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:

// scroll your smiley across the screen, without waiting for it to finish...
MicroBitImage 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);

Changing Display Mode

The MicroBitDisplay class 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 the 'setDiplayMode' function. Valid values are:

Display mode Brief Description
DISPLAY_MODE_BLACK_AND_WHITE Each pixel can be just on or off. The brightness of all pixels is controlled by the setBrightness function.
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.

for example:

// show a smiley with bright eyes!
MicroBitImage 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 a MicroBitImage. This means that you can also access and call any of the functions listed in the MicroBitImage API documentation 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);

Other Useful Functions

Message Bus ID

Constant Value
MICROBIT_ID_DISPLAY 6

Message Bus Events

Constant Value
MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE 1
MICROBIT_DISPLAY_EVT_LIGHT_SENSE 2

Notify Events

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

Constant Value
MICROBIT_DISPLAY_EVT_FREE 1

API

Constructor


MicroBitDisplay()

Description

Constructor.

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

Example
 MicroBitDisplay display; 


MicroBitDisplay(
uint16_t
id)

Description

Constructor.

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

Parameters

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

Example
 MicroBitDisplay display; 


MicroBitDisplay(
uint16_t
id,
const MatrixMap &
map)

Description

Constructor.

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

Parameters

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

const MatrixMap &
map - The mapping information that relates pin inputs/outputs to physical screen coordinates. Defaults to microbitMatrixMap, defined in MicroBitMatrixMaps.h .

Example
 MicroBitDisplay 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

MICROBIT_OK, MICROBIT_BUSY is the screen is in use, or MICROBIT_INVALID_PARAMETER.

Example
 display.printAsync('p'); 
 display.printAsync('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

MICROBIT_OK, MICROBIT_BUSY is the screen is in use, or MICROBIT_INVALID_PARAMETER.

Example
 display.printAsync('p'); 
 display.printAsync('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

MICROBIT_OK, or MICROBIT_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: MICROBIT_DEFAULT_PRINT_SPEED.

Returns

MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.

Example
 display.printAsync("abc123",400); 


int
printAsync
(
MicroBitImage
i)

Description

Prints the given image to the display, if the display is not in use. Returns immediately, and executes the animation asynchronously.

Parameters

MicroBitImage
i - The image to display.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
printAsync
(
MicroBitImage
i,
int
x)

Description

Prints the given image to the display, if the display is not in use. Returns immediately, and executes the animation asynchronously.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
printAsync
(
MicroBitImage
i,
int
x,
int
y)

Description

Prints the given image to the display, if the display is not in use. Returns immediately, and executes the animation asynchronously.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

int
y - The vertical position on the screen to display the image. Defaults to 0.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
printAsync
(
MicroBitImage
i,
int
x,
int
y,
int
alpha)

Description

Prints the given image to the display, if the display is not in use. Returns immediately, and executes the animation asynchronously.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

int
y - The vertical position on the screen to display the image. Defaults to 0.

int
alpha - Treats the brightness level '0' as transparent. Defaults to 0.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
printAsync
(
MicroBitImage
i,
int
x,
int
y,
int
alpha,
int
delay)

Description

Prints the given image to the display, if the display is not in use. Returns immediately, and executes the animation asynchronously.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

int
y - The vertical position on the screen to display the image. Defaults to 0.

int
alpha - Treats the brightness level '0' as transparent. Defaults to 0.

int
delay - The time to delay between characters, in milliseconds. Defaults to 0.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 

printChar


int
printChar
(
char
c)

Description

Prints the given character to the display.

Parameters

char
c - The character to display.

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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: MICROBIT_DEFAULT_PRINT_SPEED.

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.

Example
 display.print("abc123",400); 


int
print
(
MicroBitImage
i)

Description

Prints the given image to the display. Blocks the calling thread until all the image has been displayed.

Parameters

MicroBitImage
i - The image to display.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
print
(
MicroBitImage
i,
int
x)

Description

Prints the given image to the display. Blocks the calling thread until all the image has been displayed.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
print
(
MicroBitImage
i,
int
x,
int
y)

Description

Prints the given image to the display. Blocks the calling thread until all the image has been displayed.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

int
y - The vertical position on the screen to display the image. Defaults to 0.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
print
(
MicroBitImage
i,
int
x,
int
y,
int
alpha)

Description

Prints the given image to the display. Blocks the calling thread until all the image has been displayed.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

int
y - The vertical position on the screen to display the image. Defaults to 0.

int
alpha - Treats the brightness level '0' as transparent. Defaults to 0.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,400); 


int
print
(
MicroBitImage
i,
int
x,
int
y,
int
alpha,
int
delay)

Description

Prints the given image to the display. Blocks the calling thread until all the image has been displayed.

Parameters

MicroBitImage
i - The image to display.

int
x - The horizontal position on the screen to display the image. Defaults to 0.

int
y - The vertical position on the screen to display the image. Defaults to 0.

int
alpha - Treats the brightness level '0' as transparent. Defaults to 0.

int
delay - The time to display the image for, or zero to show the image forever. Defaults to 0.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.print(i,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

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_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: MICROBIT_DEFAULT_SCROLL_SPEED.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 display.scrollAsync("abc123",100); 


int
scrollAsync
(
MicroBitImage
image)

Description

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

Parameters

MicroBitImage
image - The image to display.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.scrollAsync(i,100,1); 


int
scrollAsync
(
MicroBitImage
image,
int
delay)

Description

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

Parameters

MicroBitImage
image - The image to display.

int
delay - The time between updates, in milliseconds. Defaults to: MICROBIT_DEFAULT_SCROLL_SPEED.

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.scrollAsync(i,100,1); 


int
scrollAsync
(
MicroBitImage
image,
int
delay,
int
stride)

Description

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

Parameters

MicroBitImage
image - The image to display.

int
delay - The time between updates, in milliseconds. Defaults to: MICROBIT_DEFAULT_SCROLL_SPEED.

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

Returns

MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.scrollAsync(i,100,1); 

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

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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: MICROBIT_DEFAULT_SCROLL_SPEED.

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.

Example
 display.scroll("abc123",100); 


int
scroll
(
MicroBitImage
image)

Description

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

Parameters

MicroBitImage
image - The image to display.

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.scroll(i,100,1); 


int
scroll
(
MicroBitImage
image,
int
delay)

Description

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

Parameters

MicroBitImage
image - The image to display.

int
delay - The time between updates, in milliseconds. Defaults to: MICROBIT_DEFAULT_SCROLL_SPEED.

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.scroll(i,100,1); 


int
scroll
(
MicroBitImage
image,
int
delay,
int
stride)

Description

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

Parameters

MicroBitImage
image - The image to display.

int
delay - The time between updates, in milliseconds. Defaults to: MICROBIT_DEFAULT_SCROLL_SPEED.

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

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.

Example
 MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n"); 
 display.scroll(i,100,1); 

animateAsync


int
animateAsync
(
MicroBitImage
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

MicroBitImage
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

MICROBIT_OK, MICROBIT_BUSY if the screen is in use, or MICROBIT_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, }; 

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


int
animateAsync
(
MicroBitImage
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

MicroBitImage
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 MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS.

Returns

MICROBIT_OK, MICROBIT_BUSY if the screen is in use, or MICROBIT_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, }; 

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


int
animateAsync
(
MicroBitImage
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

MicroBitImage
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 MICROBIT_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

MICROBIT_OK, MICROBIT_BUSY if the screen is in use, or MICROBIT_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, }; 

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

animate


int
animate
(
MicroBitImage
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

MicroBitImage
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

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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, }; 

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


int
animate
(
MicroBitImage
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

MicroBitImage
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 MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS.

Returns

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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, }; 

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


int
animate
(
MicroBitImage
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

MicroBitImage
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 MICROBIT_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

MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_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, }; 

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

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

MICROBIT_OK, or MICROBIT_INVALID_PARAMETER

Example
 display.setBrightness(255); //max brightness 

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


int
getDisplayMode
()

Description

Retrieves the mode of the display.

Returns

the current mode of the display

getBrightness


int
getBrightness
()

Description

Fetches the current brightness of this display.

Returns

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

Example
 display.getBrightness(); //the current brightness 

rotateTo


void
rotateTo
(
DisplayRotation
position)

Description

Rotates the display to the given position.

Axis aligned values only.

Parameters

DisplayRotation
position

Example
 display.rotateTo(MICROBIT_DISPLAY_ROTATION_180); //rotates 180 degrees from original orientation 

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 

setFont


void
setFont
(
MicroBitFont
font)

Description

Updates the font that will be used for display operations.

Parameters

MicroBitFont
font - the new font that will be used to render characters.

Note

DEPRECATED! Please use MicroBitFont::setSystemFont() instead.

getFont


MicroBitFont
getFont
()

Description

Retrieves the font object used for rendering characters on the display.

Note

DEPRECATED! Please use MicroBitFont::getSystemFont() instead.

screenShot


MicroBitImage
screenShot
()

Description

Captures the bitmap currently being rendered on the display.

Returns

a MicroBitImage containing the captured data.

readLightLevel


int
readLightLevel
()

Description

Gives a representative figure of the light level in the current environment where are micro:bit is situated.

Internally, it constructs an instance of a MicroBitLightSensor if not already configured and sets the display mode to DISPLAY_MODE_BLACK_AND_WHITE_LIGHT_SENSE.

This also changes the tickPeriod to MICROBIT_LIGHT_SENSOR_TICK_SPEED so that the display does not suffer from artifacts.

Returns

an indicative light level in the range 0 - 255.

Note

this will return 0 on the first call to this method, a light reading will be available after the display has activated the light sensor for the first time.