Example Programs

These examples run on the LilyGo TTGO T-Display-S3 available from the usual locations. See https://github.com/Xinyuan-LilyGO/T-Display-S3 for more information.

lines.py

 1"""
 2lines.py
 3
 4    Draws lines and rectangles in random colors at random locations on the
 5    display.
 6
 7"""
 8import random
 9import st7789s3 as st7789
10import tft_config
11
12
13def main():
14    tft = tft_config.config(0)
15    tft.fill(st7789.BLACK)
16
17    while True:
18        tft.line(
19            random.randint(0, tft.width),
20            random.randint(0, tft.height),
21            random.randint(0, tft.width),
22            random.randint(0, tft.height),
23            st7789.color565(
24                random.getrandbits(8),
25                random.getrandbits(8),
26                random.getrandbits(8)
27                )
28            )
29
30        width = random.randint(0, tft.width // 2)
31        height = random.randint(0, tft.height // 2)
32        col = random.randint(0, tft.width - width)
33        row = random.randint(0, tft.height - height)
34        tft.fill_rect(
35            col,
36            row,
37            width,
38            height,
39            st7789.color565(
40                random.getrandbits(8),
41                random.getrandbits(8),
42                random.getrandbits(8)
43            )
44        )
45
46
47main()

hello.py

 1"""
 2hello.py
 3
 4    Writes "Hello!" in random colors at random locations on the display.
 5
 6"""
 7import random
 8import st7789s3 as st7789
 9import tft_config
10
11# Choose a font
12
13# import vga1_8x8 as font
14# import vga2_8x8 as font
15# import vga1_8x16 as font
16# import vga2_8x16 as font
17# import vga1_16x16 as font
18# import vga1_bold_16x16 as font
19# import vga2_16x16 as font
20# import vga2_bold_16x16 as font
21# import vga1_16x32 as font
22# import vga1_bold_16x32 as font
23# import vga2_16x32 as font
24import vga2_bold_16x32 as font
25
26
27def main():
28    tft = tft_config.config(0)
29
30    while True:
31        for rotation in range(4):
32            tft.rotation(rotation)
33            tft.fill(0)
34            col_max = tft.width - font.WIDTH*6
35            row_max = tft.height - font.HEIGHT
36
37            for _ in range(100):
38                tft.text(
39                    font,
40                    "Hello!",
41                    random.randint(0, col_max),
42                    random.randint(0, row_max),
43                    st7789.color565(
44                        random.getrandbits(8),
45                        random.getrandbits(8),
46                        random.getrandbits(8)),
47                    st7789.color565(
48                        random.getrandbits(8),
49                        random.getrandbits(8),
50                        random.getrandbits(8))
51                )
52
53
54main()

feathers.py

 1"""
 2feathers.py
 3
 4    Smoothly scroll mirrored rainbow colored random curves across the display.
 5
 6"""
 7
 8import random
 9import math
10import utime
11from machine import Pin
12import st7789s3 as st7789
13import tft_config
14
15def between(left, right, along):
16    """returns a point along the curve from left to right"""
17    dist = (1 - math.cos(along * math.pi)) / 2
18    return left * (1 - dist) + right * dist
19
20
21def color_wheel(position):
22    """returns a 565 color from the given position of the color wheel"""
23    position = (255 - position) % 255
24
25    if position < 85:
26        return st7789.color565(255 - position * 3, 0, position * 3)
27
28    if position < 170:
29        position -= 85
30        return st7789.color565(0, position * 3, 255 - position * 3)
31
32    position -= 170
33    return st7789.color565(position * 3, 255 - position * 3, 0)
34
35
36def main():
37    '''
38    The big show!
39    '''
40    #enable display and clear screen
41
42    tft = tft_config.config(1)
43
44    height = tft.height         # height of display in pixels
45    width = tft.width           # width if display in pixels
46
47    tfa = tft_config.TFA        # top free area when scrolling
48    bfa = tft_config.BFA        # bottom free area when scrolling
49
50    scroll = 0                  # scroll position
51    wheel = 0                   # color wheel position
52
53    tft.vscrdef(tfa, width, bfa)    # set scroll area
54    tft.vscsad(scroll + tfa)        # set scroll position
55    tft.fill(st7789.BLACK)          # clear screen
56
57    half = (height >> 1) - 1    # half the height of the dislay
58    interval = 0                # steps between new points
59    increment = 0               # increment per step
60    counter = 1                 # step counter, overflow to start
61    current_y = 0               # current_y value (right point)
62    last_y = 0                  # last_y value (left point)
63
64    # segment offsets
65    x_offsets = [x * (width // 8) -1 for x in range(2,9)]
66
67    while True:
68        # when the counter exceeds the interval, save current_y to last_y,
69        # choose a new random value for current_y between 0 and 1/2 the
70        # height of the display, choose a new random interval then reset
71        # the counter to 0
72
73        if counter > interval:
74            last_y = current_y
75            current_y = random.randint(0, half)
76            counter = 0
77            interval = random.randint(10, 100)
78            increment = 1/interval      # increment per step
79
80        # clear the first column of the display and scroll it
81        tft.vline(scroll, 0, height, st7789.BLACK)
82        tft.vscsad(scroll + tfa)
83
84        # get the next point between last_y and current_y
85        tween = int(between(last_y, current_y, counter * increment))
86
87        # draw mirrored pixels across the display at the offsets using the color_wheel effect
88        for i, x_offset in enumerate(x_offsets):
89            tft.pixel((scroll + x_offset) % width, half + tween, color_wheel(wheel+(i<<2)))
90            tft.pixel((scroll + x_offset) % width, half - tween, color_wheel(wheel+(i<<2)))
91
92        # increment scroll, counter, and wheel
93        scroll = (scroll + 1) % width
94        wheel = (wheel + 1) % 256
95        counter += 1
96
97
98main()

fonts.py

 1"""
 2fonts.py
 3
 4    Pages through all characters of four fonts on the display.
 5
 6"""
 7import utime
 8import st7789s3 as st7789
 9import tft_config
10
11# Choose fonts
12
13# import vga1_8x8 as font
14import vga2_8x8 as font1
15# import vga1_8x16 as font
16import vga2_8x16 as font2
17# import vga1_16x16 as font
18# import vga1_bold_16x16 as font
19# import vga2_16x16 as font
20import vga2_bold_16x16 as font3
21# import vga1_16x32 as font
22# import vga1_bold_16x32 as font
23# import vga2_16x32 as font
24import vga2_bold_16x32 as font4
25
26
27def main():
28    tft = tft_config.config(0)
29    tft.vscrdef(tft_config.TFA, 320, tft_config.BFA)
30
31    while True:
32        for font in (font1, font2, font3, font4):
33            tft.fill(st7789.BLUE)
34            line = 0
35            col = 0
36
37            for char in range(font.FIRST, font.LAST):
38                tft.text(font, chr(char), col, line, st7789.WHITE, st7789.BLUE)
39                col += font.WIDTH
40                if col > tft.width - font.WIDTH:
41                    col = 0
42                    line += font.HEIGHT
43
44                    if line > tft.height-font.HEIGHT:
45                        utime.sleep(3)
46                        tft.fill(st7789.BLUE)
47                        line = 0
48                        col = 0
49
50            utime.sleep(3)
51
52
53main()

scroll.py

 1"""
 2scroll.py
 3
 4    Smoothly scrolls all font characters up the screen on the display.
 5
 6"""
 7import utime
 8import random
 9import st7789s3 as st7789
10import tft_config
11
12# choose a font
13
14# import vga1_8x8 as font
15# import vga2_8x8 as font
16# import vga1_8x16 as font
17# import vga2_8x16 as font
18# import vga1_16x16 as font
19# import vga1_bold_16x16 as font
20# import vga2_16x16 as font
21import vga2_bold_16x16 as font
22
23
24def main():
25    tft = tft_config.config(0)
26    last_line = tft.height - font.HEIGHT
27    tfa = tft_config.TFA
28    tfb = tft_config.BFA
29    tft.vscrdef(tfa, 320, tfb)
30
31    tft.fill(st7789.BLUE)
32    scroll = 0
33    character = 0
34    while True:
35        tft.fill_rect(0, scroll, tft.width, 1, st7789.BLUE)
36
37        if scroll % font.HEIGHT == 0:
38            tft.text(
39                font,
40                '\\x{:02x}= {:s} '.format(character, chr(character)),
41                0,
42                (scroll + last_line) % tft.height,
43                st7789.WHITE,
44                st7789.BLUE)
45
46            character = character + 1 if character < 256 else 0
47
48        tft.vscsad(scroll + tfa)
49        scroll += 1
50
51        if scroll == tft.height:
52            scroll = 0
53
54        utime.sleep(0.01)
55
56
57main()

toasters.py

Flying toasters sprite demo using bitmaps created from spritesheet using the imgtobitmap.py utility. See the maketoast script in the utils directory for details. See the 320x240 toasters example for a more advanced example that uses the sprites2bitmap utility and indexed bitmaps.

 1"""
 2toasters.py
 3
 4    An example using bitmap to draw sprites on the display.
 5
 6    Spritesheet from CircuitPython_Flying_Toasters
 7    https://learn.adafruit.com/circuitpython-sprite-animation-pendant-mario-clouds-flying-toasters
 8
 9"""
10
11import random
12from machine import Pin
13import st7789s3 as st7789
14import tft_config
15
16import t1, t2, t3, t4, t5
17
18TOASTERS = [t1, t2, t3, t4]
19TOAST = [t5]
20
21
22class toast():
23    '''
24    toast class to keep track of a sprites locaton and step
25    '''
26    def __init__(self, sprites, x, y):
27        self.sprites = sprites
28        self.steps = len(sprites)
29        self.x = x
30        self.y = y
31        self.step = random.randint(0, self.steps-1)
32        self.speed = random.randint(2, 5)
33
34    def move(self):
35        if self.x <= 0:
36            self.speed = random.randint(2, 5)
37            self.x = 135 - 64
38
39        self.step += 1
40        self.step %= self.steps
41        self.x -= self.speed
42
43
44def main():
45    """
46    Initialize the display and draw flying toasters and toast
47    """
48    tft = tft_config.config(0)
49    tft.fill(st7789.BLACK)
50
51    # create toast spites in random positions
52    sprites = [
53        toast(TOASTERS, 135-64, 0),
54        toast(TOAST, 135-64*2, 80),
55        toast(TOASTERS, 135-64*4, 160)
56    ]
57
58    # move and draw sprites
59    while True:
60        for man in sprites:
61            bitmap = man.sprites[man.step]
62            tft.fill_rect(
63                man.x+bitmap.WIDTH-man.speed,
64                man.y,
65                man.speed,
66                bitmap.HEIGHT,
67                st7789.BLACK)
68
69            man.move()
70
71            if man.x > 0:
72                tft.bitmap(bitmap, man.x, man.y)
73            else:
74                tft.fill_rect(
75                    0,
76                    man.y,
77                    bitmap.WIDTH,
78                    bitmap.HEIGHT,
79                    st7789.BLACK)
80
81
82main()

chango.py

Test for font2bitmap converter for the driver. See the font2bitmap program in the utils directory.

 1"""
 2chango.py
 3
 4    Test for font2bitmap converter for the driver.
 5    See the font2bitmap program in the utils directory.
 6"""
 7import gc
 8import st7789s3 as st7789
 9import tft_config
10
11import chango_16 as font_16
12import chango_32 as font_32
13import chango_64 as font_64
14
15gc.collect()
16
17
18def main():
19    # enable display and clear screen
20    tft = tft_config.config(1)
21    tft.fill(st7789.BLACK)
22
23    row = 0
24    tft.write(font_16, "abcdefghijklmnopqrst", 0, row, st7789.RED)
25    row += font_16.HEIGHT
26
27    tft.write(font_32, "abcdefghij", 0, row, st7789.GREEN)
28    row += font_32.HEIGHT
29
30    tft.write(font_64, "abcd", 0, row, st7789.BLUE)
31    row += font_64.HEIGHT
32
33
34main()

noto_fonts.py

Test for font2bitmap converter for the driver. See the font2bitmap program in the utils directory.

 1"""
 2noto_fonts Writes the names of three Noto fonts centered on the display
 3    using the font. The fonts were converted from True Type fonts using
 4    the font2bitmap utility.
 5"""
 6
 7import st7789s3 as st7789
 8import tft_config
 9
10import NotoSans_32 as noto_sans
11import NotoSerif_32 as noto_serif
12import NotoSansMono_32 as noto_mono
13
14
15def main():
16
17    def center(font, string, row, color=st7789.WHITE):
18        screen = tft.width                        # get screen width
19        width = tft.write_width(font, string)     # get the width of the string
20        col = tft.width // 2 - width // 2 if width and width < screen else 0
21        tft.write(font, string, col, row, color)  # and write the string
22
23    # enable display and clear screen
24    tft = tft_config.config(1)
25    tft.fill(st7789.BLACK)
26
27    row = 16
28
29    # center the name of the first font, using the font
30    center(noto_sans, "NotoSans", row, st7789.RED)
31    row += noto_sans.HEIGHT
32
33    # center the name of the second font, using the font
34    center(noto_serif, "NotoSerif", row, st7789.GREEN)
35    row += noto_serif.HEIGHT
36
37    # center the name of the third font, using the font
38    center(noto_mono, "NotoSansMono", row, st7789.BLUE)
39    row += noto_mono.HEIGHT
40
41
42main()