Is there a simple image format which can be parsed and displayed? Yes! The ancient Portable PixMap (PPM) format.

The standard is beautiful in its simplicity. Here's the header:

P6
# Created by GIMP version 2.10.38 PNM plug-in
120 120
255
���t�{...

The P6 identifies it as a PPM file. The # is a comment. 120 120 says that the image's dimensions are 120 pixels horizontal, and 120 vertical. 255 is the maximum value for each colour.

Then comes a big blob of binary data. Each byte is a value from 0 to 255.

To find the Red, Green, and Blue values of the first pixel, read the first 3 bytes. The next 3 bytes are the RGB of the next pixel. And so on.

There's no compression. Just pure pixel values.

Because of the low memory limits of the Tildagon, I found it impossible to load the entire file into memory and then paint it on the screen. Instead, I read it in chunks.

First, load the file as a read-only binary. Then skip the header and get straight to the pixel data.

#   Open a 120px x 120px Raw / Binary PPM file
with open('/apps/ppm/chrome120.ppm', 'rb') as ppm_file:
    print("Skipping Header")
    # Skip the header
    header = b''
    while True:
        line = ppm_file.readline()
        header += line
        if header.endswith(b'\n255\n'):
            break

Images on the Tildagon are drawn from the top left, which has co-ordinates -120,-120

    #   Start at the top left
    x, y = -120, -120

Next, read in a line of pixels. The image is 120px wide, each pixel has 3 values, so that's 360 bytes. Grab the pixel values and draw them to screen:

    while True:
        #   Read in 1 line at a time (3 bytes * 120px)
        chunk = ppm_file.read(360)
        if not chunk:
            break  # End of file
        #   Read the RGB, convert to float
        for i in range(0, len(chunk), 3):
            r = chunk[i]    /255
            g = chunk[i + 1]/255
            b = chunk[i + 2]/255
            #   Draw the pixel in a 2x2 square
            ctx.rgb(r, g, b).rectangle(x, y, 2, 2).fill()

The screen's resolution is 240x240, so each pixel from the 120x120 image needs to be drawn as 2x2 rectangle.

Once that's done, move to the next square to be drawn. Once a full line has been drawn, move down to drawing the next line.

            #   Move the the next square
            x += 2
            #   If a complete line has been drawn
            #   Move down a line (2px) and reset the x coordinate
            if x >= 120:
                x = -120
                y += 2
        #   Clear the chunk from memory
        del chunk
        #   Perform garbage collection
        gc.collect()

A bit of manual garbage collection doesn't hurt! And then a bit more for good luck!

del(ppm_file)
#   Final collection
print("Collecting")
gc.collect()

Here's how to set the time on the badge. There's a hardware clock which should keep time between reboots.

1. Install mpremote on your computer.
2. Connect the Tildagon to your computer using a USB-C data cable
3. On your computer's command line, run mpremote. You should see: > Connected to MicroPython at /dev/ttyACM0 > Use Ctrl-] or Ctrl-x to exit this shell
4. Hold down the ctrl key on your computer. While holding it down, press the C key on your computer. This will open up a shell for you to enter commands.
5. Enter the following commands one at a time, followed by enter

from machine import RTC
rtc = RTC()
rtc.datetime()

That will display the time that the badge currently thinks it is.

For example: (2000, 1, 1, 5, 0, 1, 47, 984022)

This is a slightly unusual format. It is: year, month, day, weekday, hours, minutes, seconds, subseconds.

The "weekday" is 0 for Monday, 1 for Tuesday etc.

This is an array. So, to access individual elements of the time, you can say:

year = rtc.datetime()[0]

Alternatively, you can do:

import time
time.localtime()

That will return something like: (2024, 6, 11, 15, 11, 39, 1, 163)

Which, according to the documentation, is "year, month, mday, hour, minute, second, weekday, yearday".

Setting the clock

To manually set the date and time, run:

rtc.datetime((2023, 6, 16, 1, 15, 36, 0, 0))

NTP

If you want to use NTP to synchronise the time with an Internet-based atomic clock, here's what you need to do.

1. Connect your badge to WiFi.
2. As above, connect with USB and run mpremote, then obtain a shell.
3. Enter the following commands one at a time, followed by enter:

import ntptime
ntptime.settime()
rtc.datetime()

That will now show you the synchronised time. Note, it will be set to UTC. There's no way to set the timezone - you'll have to deal with that in your code elsewhere.

You can also read the reference documentation about the Real Time Clock.

Here's the end result:

Background

I'm going to assume that you have updated your badge to the latest firmware version.

You will also need to install mpremote on your development machine.

You should also have successfully run the basic Hello, World! app.

Drawing surface

The Tildagon screen is 240x240 pixels. However, it is also a circle. This gives an internal square of 170x170 pixels. The drawing co-ordinates have 0,0 in the centre. Which means the target area is the red square as shown here:

Generate a QR code

As you can see, there isn't much space here. A Version 1 QR Code is a mere 21x21 pixels. When set to "Low" error correction, it can contain up to 25 characters. A URl should start with https:// - which is 8 characters. That leaves 17 characters for the domain and path.

Use your favourite QR generator to make the tiniest QR code you can. Make sure there's no border. It should be 21x21 pixels. Here's mine:

See? Tiny!

Prepare the QR code

Next, we need to turn the QR code into a binary matrix. There may be easier ways to do this, but I used a scrap of Python:

from PIL import Image
import numpy as np

#    Load the image
image = Image.open("qr.png")

#    Convert the image to grayscale
gray_image = image.convert("L")

#    Threshold the image to get binary black and white image
threshold = 128
bw_image = gray_image.point(lambda x: 0 if x > threshold else 1, '1')

#    Convert the image to a NumPy array
pixel_array = np.array(bw_image, dtype=int)

#    Convert the array to a string with commas between the elements
array_str = np.array2string(pixel_array, separator=',', formatter={'int':lambda x: str(x)})

print(array_str)

Copy the output - we'll need it later!

Calculate size

We have a canvas of 170 pixels and a QR code of 21 pixels. 170 / 21 = 8.1 pixels. Ah. Drawing fractional pixels isn't fun. Luckily, QR codes benefit from having a safe area around them. If we make each QR pixel 7 screen pixels, that gives us (21 x 7) = 147 pixels. Which gives us enough space for a small white border.

If the QR code is to be centred, the top left corner will be in position (147 / 2) = 74. That means it will need to be drawn at position -74,-74. The top left corner is -120,-120.

So the offset used to calculate the location is (-120 + 74) = 46.

(You might be able to get away with 8 pixels and an offset of 36 pixel. Try it!)

Remember those numbers!

Write the app

This reuses a lot of the Hello World code.

import app
from app_components import TextDialog, clear_background
from events.input import Buttons, BUTTON_TYPES

class QrApp(app.App):
    #   Define the colours
    black = (  0,   0,   0)
    white = (255, 255, 255)

    def __init__(self):
        self.button_states = Buttons(self)

    def update(self, delta):
        if self.button_states.get(BUTTON_TYPES["CANCEL"]):
            self.button_states.clear()
            self.minimise()

    def draw(self, ctx):
        clear_background(ctx)

        #   QR code data (21x21 matrix)
        qr_code =[[1,1,1,1,1,1,1,0,0,1,1,0,0,0,1,1,1,1,1,1,1],
                  [1,0,0,0,0,0,1,0,1,0,1,0,0,0,1,0,0,0,0,0,1],
                  [1,0,1,1,1,0,1,0,1,1,1,1,1,0,1,0,1,1,1,0,1],
                  [1,0,1,1,1,0,1,0,0,1,1,0,0,0,1,0,1,1,1,0,1],
                  [1,0,1,1,1,0,1,0,1,1,1,1,0,0,1,0,1,1,1,0,1],
                  [1,0,0,0,0,0,1,0,1,1,0,1,0,0,1,0,0,0,0,0,1],
                  [1,1,1,1,1,1,1,0,1,0,1,0,1,0,1,1,1,1,1,1,1],
                  [0,0,0,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0,0,0,0],
                  [1,1,0,1,0,0,1,1,0,0,1,0,0,0,1,1,1,0,1,1,0],
                  [1,0,1,1,1,1,0,1,1,0,0,1,1,0,1,1,1,0,0,0,1],
                  [1,0,1,0,0,1,1,1,0,1,1,0,1,0,0,0,0,0,1,0,1],
                  [1,1,1,1,0,1,0,1,0,0,0,0,0,0,1,0,1,1,0,1,1],
                  [1,0,1,0,0,1,1,1,0,0,1,1,1,0,0,1,0,1,0,0,0],
                  [0,0,0,0,0,0,0,0,1,0,0,0,1,1,0,1,0,0,0,0,1],
                  [1,1,1,1,1,1,1,0,1,0,1,0,1,1,0,0,1,1,1,1,0],
                  [1,0,0,0,0,0,1,0,0,0,0,1,1,0,0,1,1,0,0,0,0],
                  [1,0,1,1,1,0,1,0,0,0,1,1,0,1,0,0,1,1,0,1,1],
                  [1,0,1,1,1,0,1,0,1,0,0,0,1,0,1,0,1,0,0,0,1],
                  [1,0,1,1,1,0,1,0,0,0,1,1,1,0,1,0,1,0,1,0,1],
                  [1,0,0,0,0,0,1,0,1,1,1,0,0,1,0,0,0,0,0,0,0],
                  [1,1,1,1,1,1,1,0,1,0,1,0,1,0,1,0,1,0,0,1,0]]

        #   Draw background
        ctx.rgb(*self.white).rectangle(-120, -120, 240, 240).fill()

        #   Size of each QR code pixel on the canvas
        pixel_size = 7

        #   Offset size in pixels
        offset_size = 46

        #   Calculate the offset to start drawing the QR code (centre it within the available space)
        offset = -120 + offset_size

        #   Loop through the array
        for row in range(21):
            for col in range(21):
                if qr_code[row][col] == 1:
                    x = (col * pixel_size) + offset
                    y = (row * pixel_size) + offset
                    ctx.rgb(*self.black).rectangle(x, y, pixel_size, pixel_size).fill()

__app_export__ = QrApp

Installation

• Follow the instructions
• Run mpremote cp ~/Documents/badge/* :/apps/qr/
• Restart the badge
• Scroll down the app list and launch the QR app

The non-stupid way!

OK, that was the hard way - here's the easy way.

Use the MicroPython QR Generation library uQR.

If you pop that file in your project directory, and upload it to the badge, then you can import it with:

from .uQR import QRCode

The QR code has its own white margin and is a 2D array of True & Falses.

# QR code data (29x29 matrix)
qr = QRCode()
qr.add_data("https://edent.tel")
qr_code = qr.get_matrix()
qr_size = len( qr_code )

#   Draw background
ctx.rgb(*self.white).rectangle(-120, -120, 240, 240).fill()

#   Size of each QR code pixel on the canvas
pixel_size = int( 170 / qr_size ) + 1

#   Border size in pixels
border_size = ( 240 - (pixel_size*qr_size) ) / 2

#   Calculate the offset to start drawing the QR code (centre it within the available space)
offset = -120 + border_size

#   Loop through the array
for row in range( len(qr_code) ):
    for col in range( len(qr_code) ):
        if qr_code[row][col] == True:
            x = (col * pixel_size) + offset
            y = (row * pixel_size) + offset
            ctx.rgb(*self.black).rectangle(x, y, pixel_size, pixel_size).fill()

Next steps

• This is hardcoded for a single QR code - mine! Perhaps it should be configurable?
• Add some text to the screen?
• Animations? Colour? Flashing LEDs?

Got any thoughts? Stick them in the box!