Image Display (JPG / PNG / Animation)
A screen only ever shows pixels, never "files". The Beetle S1 image APIs split by how they decode: jpg() decodes and pushes in one go (simplest), png() streams row by row (lowest memory, supports transparency), and bitmap() shows a pre-converted bitmap (fastest). What people call "playing a GIF" is really just showing frame after frame as fast as possible, so this page gives three workable frame-by-frame approaches.
The third argument is st7789.FAST (default) or st7789.SLOW. Use FAST for small images and SLOW for full-screen backgrounds.
When the window runs past the screen edge the whole image is simply not shown (not half of it), and no error is raised.
png() decodes one row at a time and needs only a single-row buffer, while jpg() needs room for the whole image.
Quick Start
Copy the image to the SD card, say /sd/apps/myapp/logo.jpg, then:
import st7789
import tft_config
tft = tft_config.config(1) # 1 = landscape 240×135
tft.init()
tft.fill(st7789.BLACK)
tft.jpg('/sd/apps/myapp/logo.jpg', 10, 10, st7789.FAST)
What you'll see: the image with its top-left corner at (10, 10).
To fill the whole screen with one image, use this form, which covers the screen under any rotation:
tft.jpg('/sd/apps/myapp/bg.jpg', 0, 0, st7789.SLOW)
Displaying a JPG
tft.jpg('/sd/apps/myapp/logo.jpg', 10, 10, st7789.FAST)
The first argument can be a file path string or a bytes buffer in memory (for example image data downloaded over the network).
Choosing FAST vs SLOW
st7789.FAST (value 0) | st7789.SLOW (value 1) | |
|---|---|---|
| Decoding | Decodes the whole image into memory, then pushes it in one window | Decodes and pushes one 8×8 (or 16×16) block at a time |
| Memory | 2 × width × height bytes, must be contiguous | 2 × (width rounded up to 8) × (height rounded up to 8) bytes |
| Speed | Faster for small images (one SPI transfer) | Steadier for large images and full-screen backgrounds (block by block) |
| Best for | Icons, frame-by-frame animation | Full-screen backgrounds |
Omitting the third argument defaults to FAST. The official light-painting app confirms exactly this split: SLOW for the full-screen background, FAST for small images.
tft.jpg('/sd/apps/light-painter/main.jpg', 0, 0, st7789.SLOW) # full-screen background
tft.jpg('/sd/image/photo.jpg', (tft.width() - 100) // 2, 20, st7789.FAST) # small image
The image must fit on screen
This is the easiest trap to fall into. Before pushing pixels, the driver sets a display window, and a window that runs out of range is rejected as a whole:
- FAST: the window is
(x, y)to(x + width - 1, y + height - 1), so it needsx + width ≤ screen widthandy + height ≤ screen height. - SLOW: each block sets its own window, and out-of-range blocks stay unpainted.
When that happens there is no error at all — the image does not appear at all, or part of the screen shows garbage. The Beetle S1 screen is only 135 × 240 (landscape 240 × 135), so this limit is easy to hit; compute the position with width() / height() before drawing:
w, h = 100, 100
x = (tft.width() - w) // 2
y = (tft.height() - h) // 2
tft.jpg('/sd/image/logo.jpg', x, y, st7789.FAST)
Displaying a PNG
tft.png('/sd/apps/myapp/logo.png', 10, 10) # opaque, alpha ignored
tft.png('/sd/apps/myapp/logo.png', 10, 10, True) # transparency on: transparent pixels keep what's on screen
png() accepts only a file path (unlike jpg(), which also takes bytes). It decodes row by row and needs only a one-row buffer (image width × 2 bytes), so it is lighter than jpg() and suits large images.
The fourth argument is the transparency switch:
False(default): the alpha channel is ignored and transparent pixels are drawn opaque using their own RGB.True: pixels with alpha 0 are skipped, so whatever is already on screen shows through — that is how you overlay a PNG icon on top of another background.
Pixels that land outside the screen are skipped without error.
Playing Frame-by-Frame Animation (GIF)
The firmware has no built-in GIF decoder. To play an animation, split the GIF into still frames first (or generate bitmap frames with a tool), then loop over them with one of the three approaches below.
Approach 1: A sequence of JPG frames (simplest)
Split the GIF into frame-0.jpg, frame-1.jpg, … on the SD card and loop:
import os
import time
import st7789
import tft_config
tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)
frame_dir = '/sd/apps/myapp/frames/'
frames = sorted(os.listdir(frame_dir))
delay = 0.05 # 50 ms per frame ≈ 20 fps
try:
while True:
for name in frames:
tft.jpg(frame_dir + name, 17, 70, st7789.FAST)
time.sleep(delay)
except KeyboardInterrupt:
tft.fill(st7789.BLACK)
- Pros: no conversion needed; changing the frame rate is just changing
delay. - Cons: every frame is decoded again, so high frame rates cannot keep up.
- Best for: animations with many frames, each with few pixels.
Approach 2: jpg_decode() + blit_buffer() (decode and display separately)
jpg_decode() turns an image into a pixel buffer you can blit straight onto the screen, and blit_buffer() places it anywhere. Good when one decoded frame is reused at several positions.
import time
import st7789
import tft_config
tft = tft_config.config(1)
tft.init()
# with no crop args, decode the whole image as (buffer, width, height)
frame, w, h = tft.jpg_decode('/sd/apps/myapp/hero.jpg')
for i in range(20):
tft.fill_rect(i * 6, 20, w, h, st7789.BLACK) # erase the previous frame
tft.blit_buffer(frame, i * 6, 20, w, h) # draw this frame
time.sleep(0.03)
With six arguments, jpg_decode(path, x, y, width, height) means which region to crop from the source image (not where to draw it), and the returned buffer is exactly width × height.
In the driver source, every jpg_decode() call allocates 2 × width × height bytes and never frees it. Calling it repeatedly inside a loop will exhaust the heap. Decode once and blit_buffer() repeatedly, or use Approach 1 / Approach 3 instead.
Approach 3: Bitmap frames with bitmap() (fastest)
Use the PC-side sprites2bitmap.py to pre-convert a sprite sheet into a Python module; at runtime there is no JPEG decoding at all, only palette expansion.
python3 sprites2bitmap.py frames.bmp 64 64 4 > sprites.py
The generated module carries WIDTH / HEIGHT / BPP / PALETTE / BITMAPS / BITMAP; copy it to the SD card and import it directly before handing it to bitmap():
import time
import st7789
import tft_config
import sprites # the bitmap frame module generated above
tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)
while True:
for i in range(sprites.BITMAPS): # BITMAPS is the total frame count
tft.bitmap(sprites, 30, 30, i) # the third argument is the frame index
time.sleep(0.06)
- Pros: no decoding at runtime, so the highest achievable frame rate.
- Cons: needs a conversion step, and the whole frame sequence must fit in memory.
PALETTEentries must be byte-swapped RGB565 (the conversion script handles this; be careful if you write a module by hand).- A frame index beyond
BITMAPSraisesOSError: index out of range; omitting the index shows frame 0.
Drawing Text on a Background Image
text() draws with only a foreground and background color and covers the background. To overlay text on a background image while keeping the background detail, use the bg_tuple and fill arguments of write():
import st7789
import tft_config
import NotoSans_32 as font
tft = tft_config.config(1)
tft.init()
tft.jpg('/sd/apps/myapp/main.jpg', 0, 0, st7789.SLOW) # 1. lay down the background
# 2. crop the patch of background where the text will go, sized to the font
bg, w, h = tft.jpg_decode('/sd/apps/myapp/main.jpg', 10, 10, font.MAX_WIDTH, font.HEIGHT)
# 3. write(font, text, x, y, fg, bg, (buffer, width, height), fill)
tft.write(font, "Hello", 10, 10, st7789.WHITE, st7789.BLACK, (bg, w, h), 1)
How it works (from the driver source): pixels whose glyph bit is 1 are painted with the foreground color, while bits that are 0 keep the background color at the same position from bg_tuple. With fill set to 1 each character is padded to the font's widest character width, which keeps the background patches aligned. The background buffer must be exactly font.MAX_WIDTH × font.HEIGHT.
write()uses fonts generated byfont2bitmap(withMAX_WIDTH/WIDTHS/OFFSETS/BITMAPS) and cannot use fixed-widthvga*fonts. See Font Library.
API Reference
tft is the st7789.ST7789 instance returned by tft_config.config(), and every image API hangs off it.
jpg(src, x, y[, mode])
tft.jpg(src, x, y, st7789.FAST)
| Parameter | Type | Required | Description |
|---|---|---|---|
src | str or bytes | yes | File path, or JPEG data in memory |
x / y | int | yes | Top-left corner of the image on screen |
mode | int | no | st7789.FAST (0, default) or st7789.SLOW (1) |
Returns None. Fails when the image is out of range or memory runs out (see the troubleshooting table).
png(filename, x, y[, mask])
tft.png(filename, x, y, mask)
| Parameter | Type | Required | Description |
|---|---|---|---|
filename | str | yes | File path; paths only |
x / y | int | yes | Top-left corner |
mask | bool | no | Default False. When True, pixels with alpha 0 are skipped so the screen content shows through |
Returns None. Row-by-row decoding keeps memory low.
jpg_decode(src[, x, y, width, height])
buffer, width, height = tft.jpg_decode(src)
buffer, width, height = tft.jpg_decode(src, x, y, width, height)
| Parameter | Type | Required | Description |
|---|---|---|---|
src | str or bytes | yes | File path or in-memory data |
x / y | int | no | Crop origin in the source image, not a screen coordinate |
width / height | int | no | Crop size; the returned buffer has exactly these dimensions |
Returns a 3-tuple (buffer, width, height): buffer is a byte-swapped RGB565 bytearray, ready to hand to blit_buffer(). Passing 1 argument (2 in total, counting self) decodes the whole image; any argument count other than 2 or 6 raises TypeError: jpg_decode requires either 2 or 6 arguments.
blit_buffer(buffer, x, y, width, height)
tft.blit_buffer(buffer, x, y, width, height)
Copies an RGB565 pixel buffer to (x, y) on screen and requires all 6 arguments. The driver sends min(buffer length, width × height × 2) bytes, so an undersized buffer shows only part of the image without raising.
bitmap(bitmap_module, x, y[, index])
tft.bitmap(bitmap_module, x, y, index)
| Parameter | Type | Required | Description |
|---|---|---|---|
bitmap_module | module | yes | Must define WIDTH, HEIGHT, BPP, PALETTE, BITMAP; multi-frame modules also need BITMAPS |
x / y | int | yes | Where to draw |
index | int | no | Frame index, starting at 0, default 0 |
An index beyond BITMAPS raises OSError: index out of range; a frame whose x + WIDTH runs off screen is not drawn at all.
write(font, s, x, y[, fg, bg, bg_tuple, fill])
tft.write(font, s, x, y, fg, bg, (buffer, width, height), fill)
| Parameter | Type | Default | Description |
|---|---|---|---|
font | module | — | A font generated by font2bitmap |
s | str | — | Text to draw |
x / y | int | — | Start coordinate |
fg | int | WHITE | Color for glyph bits set to 1 |
bg | int | BLACK | Color for glyph bits set to 0 when there is no background image |
bg_tuple | tuple | none | (buffer, width, height), usually from jpg_decode() |
fill | int | 0 | When 1, each character pads out to the font's widest character width; use with a background image |
Returns the number of pixels actually printed. Characters absent from the font are skipped silently.
Common Pitfalls
| Pitfall | Cause and fix |
|---|---|
| The image never appears | x + width or y + height is off screen, so the window is rejected as a whole with no error → compute positions from width() / height() |
| Full-screen background does not fill | The image resolution does not match the screen (135 × 240 / 240 × 135) → make the image match the screen resolution, or cover the screen with an opaque full-size image |
out of memory on a large image | jpg() needs 2 × width × height contiguous bytes → shrink the image, or switch to png() |
Setting buffer_size makes init fail | buffer_size is a resident buffer; anything smaller than what an operation needs raises OSError: buffer too small. N bytes required. → normally leave it at 0 |
jpg_decode() in a loop exhausts memory | The driver never frees that allocation → decode once and blit_buffer() repeatedly, or use jpg(FAST) per frame |
bitmap() shows garbage or wrong colors | PALETTE must hold byte-swapped RGB565 → generate with the matching sprites2bitmap.py / imgtobitmap.py |
write() shows no text | Wrong font family: write() needs a font2bitmap library (with MAX_WIDTH), while text() takes fixed-width vga* fonts |
| Animation flickers | Clearing the whole screen before each frame → erase only the previous frame and draw only the new one, or overwrite with an opaque full frame |
| Frame-by-frame animation stutters | Every frame decodes the JPEG again → shrink the frames, lower the frame rate, or switch to the bitmap-frame approach |
Troubleshooting
| Error / symptom | Fix |
|---|---|
TypeError: jpg_decode requires either 2 or 6 arguments | jpg_decode() accepts only 2 or 6 arguments (including self); to decode the whole image, pass no crop arguments |
OSError: out of memory | The image is too large; the 2 × width × height allocation for jpg() failed |
OSError: buffer too small. N bytes required. | The buffer_size set at init is smaller than this operation needs; enlarge it or set 0 |
OSError: index out of range | The bitmap() frame index is ≥ BITMAPS |
RuntimeError: jpg prepare failed. | Not a valid JPEG, or the path does not exist |
RuntimeError: jpg decompress failed. | Corrupted JPEG data |
RuntimeError: png decompress failed: ... | Corrupted PNG or an unsupported format |
| All black / garbage | The image is out of range (window rejected), or buffer_size does not match the image size |
| Only part of the image draws | The blit_buffer() buffer is smaller than width × height × 2 → pass the w / h returned by jpg_decode() unchanged |
Related modules: Display (ST7789) · Font Library · USB Serial Control (CDC)
AI usage (coming soon)
Soon you won't need to remember the FAST vs SLOW difference or work out whether an image fits on screen: describe the picture you want in plain language, and the Agent will follow the APIs in this document to generate a complete program that runs on the Beetle S1.
For example, just tell it:
Show a full-screen background at boot, then loop a 12-frame animation in the bottom-right corner, and clear the screen on exit.
It will combine jpg(), jpg_decode() / blit_buffer(), and tft_config into a runnable program and place it under /sd/apps/ on the SD card.
The entry link will go here. Once it is live, one click takes you straight to describing the app you want.