TiLDA MK3/ugfx

The badge makes use of uGFX for providing drawing functions on the LCD. Most of this functionality is available through the micropython interface, and you may wish to browse the uGFX documentation for more details

Basic usage

uGFX is comprised of 'widgets,' such as buttons and labels, and 'containers' which are used to group widgets.

To create a button on the screen, use ugfx.Button(x,y,width,height,text), and a button will be drawn on the screen.

As well as widgets, there are 'primitives' such as drawing circles and lines, which can be drawn anywhere on the screen or in a container. For example ugfx.circle(50,50,20,ugfx.RED) will draw a circle.

Detailed documentation

Note. all co-ordinates are from the top left (battery symbol) corner.

Colour format

Internally, ugfx uses 565 format (5 bits for red and blue, 6 for green). Preset colours are available, for example ugfx.RED, ugfx.ORANGE, etc. To convert from 24 bit RGB format, use ugfx.html_color(0xRRGGBB) to return the 16 bit 565 format.

Styles and Fonts

Use ugfx.set_default_font("c*") to change the font. Note that widgets use the font which was default when they were created, while the container.text() primitive uses the font that was default when the container was created

Containers

Containers can be used to group widgets together. They can also perform primitive drawing functions. When drawing widgets or primitives, the coordinates are relative to the top left corner of the container.

Containers can be shown or hidden, and all the widgets will be redrawn. Containers can also be placed on top of other widgets. When the top container is hidden, the widgets below will be redrawn.

Upon creation a style can be passed to a container, which will then be used by default by widgets created as part of that container. If no style is specified at creation, the current default style will be used.

The following example shows how to create a container, add an object and show it.

c = ugfx.Container(100,100,200,100{,style}  # the style is optional
b = ugfx.Button(10, 10, 40, 30, "OK", parent = c}
c.show()            # the container will not be shown until this point

Primitives

All primitives can be drawn anywhere on the screen with, for example ugfx.circle(..), or anywhere within a container, with c=ugfx.Container(30,30,100,100); c.circle(..)

Circle

.circle(<x>,<y>,<diameter>,<colour>)

.fill_circle(<x>,<y>,<diameter>,<colour>)

Draws a circle at <x>,<y> of <diameter> using <colour>, either with a 1 pixel border or filling the area.

eg. ugfx.circle(180,150,40,ugfx.RED)

Lines

.line(<x1>, <y1>, <x2>, <y2>, <colour>)

.thickline(<x1>, <y1>, <x2>, <y2>, <colour>, <width>, <round>)

Draws a line from x1,y1 to x2,y2 using <colour>. Thickline will draw a line or arbitrary width, with the option of rounded corners

eg. ugfx.thickline(0,0,100,170,ugfx.YELLOW,7,0)

Widgets

ugfx.text(<x>,<y>,<text>,<colour>)

Draws a text string <text> at <x>,<y> in <colour>.

eg. ugfx.text(40,40,"My name is...",ugfx.BLUE)

Tips and tricks

Tearing

When writing large areas of the screen, a 'tearing' [1] effect may be observed.

The screen module is comprised of a large memory, with one memory location to store the RGB data for each pixel. The LCD driver continuously updates the LCD pixels, by reading the memory in a sequential, line-by-line manner, and updating the LCD with the data from the memory. This 'read line-pointer' moves from the top to the bottom of the screen (when viewed in portrait), at about 70Hz (the refresh rate of the screen)

This large memory as part of the screen means it can be driven by a microcontroller which may have a considerably smaller memory. The microcontroller therefore only needs to update the memory when it whats the content to change.

Consider the scenario where the microcontroller wants to set the screen from one colour to another. The microcontroller needs to update the entire memory (320x240x2 = 153kB) with the new colour. At the same time the 'read line-pointer' is reading the same memory to update the LCD. In this case, tearing occurs if the 'read line-pointer' reads the top half of the memory containing the new colour, but then catches up with microcontroller writing to the memory, then the 'read line-pointer' starts reading the old colour in the bottom half of the memory.

To avoid tearing the 'read line-pointer' should not cross the region the microcontroller is updating. Since the microcontroller writes to the screen slightly slower than the LCD reads it, providing the microntroller starts writes to the top of the memory just after the LCD starts reading from the top, the read and write pointers will not overlap, and tearing will not occur. To sync the microcontroller with the LCD 'read line-pointer,' there is a vsync/tear output (connected to pin named 'TEAR') which is pulled high when the 'read line-pointer' reaches a given line (default is line 0). This can be turned on and off with ugfx.enable_tear() and ugfx.disable_tear(). To change the line at which the tear output is generated, use ugfx.set_tear_line(0..319).

Reducing power consumption

Use the following to dim the backlight, which uses about 80mA at full brightness

ugfx.backlight(b)     # sets the backlight. Range is 0-100
b = ugfx.backlight()   # reads the current backlight