Display

OLEM’s display is a LCD-TFT screen enabled with a capacitive touch panel. Its technical specifications are :

320*240px
RGB565 colors which means that each pixel is stored on 2 bytes. Red and Blue are represented on 5 bits while Green is represented on 6 bits.
(x=0, y=0) is top left of screen

The callbacks used with display components such as buttons are implemented as events stored in a queue. Each component can be associated to an id which is then added to the queue when the event is triggered. That queue can be read using the API.

Preparing images

Later on we will handle other formats, for now, the only supported format is the one generated by https://lvgl.io/tools/imageconverter in V8

To generate the image file :

Prepare the image by setting it to the size it will have on screen (screen is 320*240px)
Set version to: LVGL v8
Select Color format: CF_TRUE_COLOR_ALPHA or CF_TRUE_COLOR
Output format: Binary RGB565
Convert it

Now the output image can be used.

Examples

Text

import olem

message = "Hello world !"

# Display in the middle of the screen
text_obj = olem.display_text(message, olem.FONT_DEFAULT, olem.ALIGN_CENTER)
olem.display_center(text_obj)
olem.delay_ms(5000)

# Change contents
olem.display_set_text(text_obj, "Now I barely fit on screen")
olem.delay_ms(5000)

# Resize
olem.display_set_size(text_obj, 200, 100)
olem.delay_ms(1000)

# Recolor
olem.display_set_text(text_obj, "Now I do.\nI can also change color!")
olem.display_set_text_color(text_obj, "#00FF00")
olem.delay_ms(5000)

# Move
olem.display_set_text(text_obj, "Or move")
for i in range(6):
    olem.display_set_pos(text_obj, i * 10, i * 10)
    olem.display_wait_for_next_frame()

# Delete
olem.display_del(text_obj)

# Font size
text_obj = olem.display_text("New texts are still white", olem.FONT_SMALL, olem.ALIGN_CENTER)
olem.display_center(text_obj)
olem.delay_ms(5000)

# Change the default color, all new texts use this color
olem.display_set_default_text_color("#FF00FF")

# Delete all displayed objects
olem.display_del_all()

# New text uses the default color
olem.display_mutex_take()
text_obj = olem.display_text("But not anymore !", olem.FONT_BIG, olem.ALIGN_CENTER)
olem.display_set_size(text_obj, 320, 100)
olem.display_center(text_obj)
olem.display_mutex_give()

olem.delay_ms(5000)

Buttons

Three buttons change the color of the LEDs, the image button ends the example. The events are checked periodically with display_get_event().

import olem

X_MARGIN = 10

# Events id
EVENT_RED   = 1
EVENT_GREEN = 2
EVENT_BLUE  = 3
EVENT_EXIT  = 4

# Init display components
b = olem.display_button("Red", EVENT_RED)
olem.display_set_pos(b, X_MARGIN, 20)

b = olem.display_button("Green", EVENT_GREEN)
olem.display_set_pos(b, X_MARGIN, 80)

b = olem.display_button("Blue", EVENT_BLUE)
olem.display_set_pos(b, X_MARGIN, 140)

b = olem.display_img_button("/common/images/settings.bin")
olem.display_add_event_cb(b, EVENT_EXIT)
olem.display_set_pos(b, X_MARGIN, 180)
olem.display_set_size(b, 50, 50)

# Check events by polling
should_exit = False
while not should_exit:
    event = olem.display_get_event()

    if event == EVENT_RED:
        olem.led_on(olem.LEDALL, "#FF0000")
    elif event == EVENT_GREEN:
        olem.led_on(olem.LEDALL, "#00FF00")
    elif event == EVENT_BLUE:
        olem.led_on(olem.LEDALL, "#0000FF")
    elif event == EVENT_EXIT:
        should_exit = True

    olem.delay_ms(50)

To wait for the events instead of checking them periodically, replace the loop with display_wait_for_event(), or with display_wait_for_event_timeout() to do something else when no event happens in time:

# Wait for each event, for 500 ms at most
should_exit = False
while not should_exit:
    event = olem.display_wait_for_event_timeout(500)

    if event == EVENT_RED:
        olem.led_on(olem.LEDALL, "#FF0000")
    elif event == EVENT_GREEN:
        olem.led_on(olem.LEDALL, "#00FF00")
    elif event == EVENT_BLUE:
        olem.led_on(olem.LEDALL, "#0000FF")
    elif event == EVENT_EXIT:
        should_exit = True
    elif event == 0:
        print("no event before timeout")

QR code

The text encoded in the QR code changes each time a hand goes above the top sensor.

import olem

qr_code = olem.display_qr_code(220, "Hello OLEM")
olem.display_center(qr_code)

for i in range(5):
    # Wait for a hand above the top sensor, then for it to leave
    while not olem.ir_top_is_hand_present():
        olem.delay_ms(50)
    while olem.ir_top_is_hand_present():
        olem.delay_ms(50)

    olem.display_set_qr_code_data(qr_code, "Hello OLEM " + str(i + 1))

Constants and functions

Constants

Constant	Value	Description
`FONT_DEFAULT`	`0`	Default font size.
`FONT_SMALL`	`1`	Small font size.
`FONT_BIG`	`2`	Big font size.
`ALIGN_LEFT`	`0`	Text aligned on the left.
`ALIGN_CENTER`	`1`	Text centered.
`ALIGN_RIGHT`	`2`	Text aligned on the right.

`class lv_obj`

Type of the screen objects returned by the display functions, such as display_text() or display_button(). It cannot be created directly.

The screen is 320 x 240 px, (0, 0) is its top left corner.

`display_text(text, font_size, align)`

Create a text object.

Parameter	Description
`text`	text to display
`font_size`	`FONT_SMALL`, `FONT_DEFAULT` or `FONT_BIG`
`align`	`ALIGN_LEFT`, `ALIGN_CENTER` or `ALIGN_RIGHT`

Returns: the text object

`display_button(text, event_id)`

Create a button. When it is pressed, event_id is added to the event queue, see display_get_event().

Parameter	Description
`text`	text of the button
`event_id`	integer identifying the button in the event queue, 0 is not allowed

Returns: the button object

`display_img(file_name)`

Create an image object from a file. Images must be converted with the LVGL v8 image converter, in binary RGB565.

Parameter	Description
`file_name`	path of the image file, relative to the assets folder of the game

Returns: the image object

`display_img_button(file_name)`

Create a clickable image object from a file. Use display_add_event_cb() to choose the event it triggers.

Parameter	Description
`file_name`	path of the image file, relative to the assets folder of the game

Returns: the image object

`display_qr_code(size, data)`

Create a QR code object, black on white.

Parameter	Description
`size`	width and height in px
`data`	text encoded in the QR code

Returns: the QR code object

`display_set_qr_code_data(lvgl_obj, data)`

Change the text encoded in a QR code object.

Parameter	Description
`lvgl_obj`	QR code object created with `display_qr_code()`
`data`	new text to encode

`display_add_event_cb(lvgl_obj, event_id)`

Make an object clickable: when it is clicked, event_id is added to the event queue, see display_get_event().

Parameter	Description
`lvgl_obj`	object to make clickable
`event_id`	integer identifying the object in the event queue, 0 is not allowed

`display_del(lvgl_obj)`

Delete an object from the screen. It must not be used afterwards.

Parameter	Description
`lvgl_obj`	object to delete

`display_del_all()`

Delete all the objects from the screen. The background color is kept.

`display_center(lvgl_obj)`

Center an object on the screen.

Parameter	Description
`lvgl_obj`	object to center

`display_set_pos(lvgl_obj, x, y)`

Move an object on the screen.

Parameter	Description
`lvgl_obj`	object to move
`x`	position of its left side in px
`y`	position of its top side in px

`display_get_pos(lvgl_obj)`

Parameter	Description
`lvgl_obj`	displayed object

Returns: position of the object as a list [x, y] in px

`display_get_size(lvgl_obj)`

The object must already be drawn on screen, see display_wait_for_next_frame().

Parameter	Description
`lvgl_obj`	displayed object

Returns: size of the object as a list [width, height] in px

`display_set_size(lvgl_obj, width, height)`

Resize an object. Images are not scaled, only their container is resized.

Parameter	Description
`lvgl_obj`	object to resize
`width`	new width in px
`height`	new height in px

`display_set_text(lvgl_obj, text)`

Change the text of a text object.

Parameter	Description
`lvgl_obj`	text object created with `display_text()`
`text`	new text to display

`display_set_img_src(lvgl_obj, file_name)`

Change the image of an image object.

Parameter	Description
`lvgl_obj`	image object created with `display_img()`
`file_name`	path of the new image file, relative to the assets folder of the game

`display_move_to_foreground(lvgl_obj)`

Draw an object above all the others.

Parameter	Description
`lvgl_obj`	object to move

`display_move_to_layer(lvgl_obj, index)`

Choose in which order an object is drawn.

Parameter	Description
`lvgl_obj`	object to move
`index`	0 is the background, the foreground is the number of objects on screen minus 1

`display_wait_for_next_frame()`

Wait until the next frame is drawn on screen.

`display_mutex_take()`

Prevent the screen from being redrawn, so that several objects can be created and configured before they appear. The screen is frozen until display_mutex_give() is called.

`display_mutex_give()`

Allow the screen to be redrawn again after display_mutex_take().

`display_get_event()`

Get the oldest event triggered by a button or a clickable object, without waiting.

Returns: id of the oldest event, or 0 if there is none

`display_clear_events()`

Delete the events that were not read yet.

`display_wait_for_event()`

Wait for an event triggered by a button or a clickable object. The game can still be stopped during the wait.

Returns: id of the event

`display_wait_for_event_timeout(timeout)`

Wait for an event triggered by a button or a clickable object, for a limited time.

Parameter	Description
`timeout`	maximum time to wait in ms

Returns: id of the event, or 0 if no event happened in time

`display_set_bkg_color(color)`

Change the background color of the screen.

Parameter	Description
`color`	color as a "#RRGGBB" string

`display_set_text_color(lvgl_obj, color)`

Change the color of a text object.

Parameter	Description
`lvgl_obj`	text object created with `display_text()`
`color`	color as a "#RRGGBB" string

`display_set_default_text_color(color)`

Change the color of the text objects created after this call.

Parameter	Description
`color`	color as a "#RRGGBB" string

`display_set_backlight(value)`

Set the brightness of the screen.

Parameter	Description
`value`	brightness from 0 to 100, other values are clamped

Preparing images​

Examples​

Text​

Buttons​

QR code​

Constants and functions​

Constants​

class lv_obj​

display_text(text, font_size, align)​

display_button(text, event_id)​

display_img(file_name)​

display_img_button(file_name)​

display_qr_code(size, data)​

display_set_qr_code_data(lvgl_obj, data)​

display_add_event_cb(lvgl_obj, event_id)​

display_del(lvgl_obj)​

display_del_all()​

display_center(lvgl_obj)​

display_set_pos(lvgl_obj, x, y)​

display_get_pos(lvgl_obj)​

display_get_size(lvgl_obj)​

display_set_size(lvgl_obj, width, height)​

display_set_text(lvgl_obj, text)​

display_set_img_src(lvgl_obj, file_name)​

display_move_to_foreground(lvgl_obj)​

display_move_to_layer(lvgl_obj, index)​

display_wait_for_next_frame()​

display_mutex_take()​

display_mutex_give()​

display_get_event()​

display_clear_events()​

display_wait_for_event()​

display_wait_for_event_timeout(timeout)​

display_set_bkg_color(color)​

display_set_text_color(lvgl_obj, color)​

display_set_default_text_color(color)​

display_set_backlight(value)​