Troopers 19 – Hack your badge

Sadly, TROOPERS 19 is already over. I had great fun meeting all of you, helping you with your badge problems and seeing others hacking on their badges for example to get custom images on there.

With this year’s badge we wanted to give you something you can reuse after the conference, learn new things new build something on your own.

As promised in our talk Jeff and I would like to give you a short introduction into the badge internals. Along with this post we will release the source code for the badge firmware, the provisioning server and the schematics for the PCB.

Firmware

The firmware is based on micropython and implements a custom ePaper display driver alongside a custom framebuffer. The code can be found at ports/esp32/moddisplay.

All the infrastructure and application related code – the framework – can be found in ports/esp32/modules and is split into three different directories.

• apps: Implementation of built-in applications. Those applications will not appear in the file system on the badge but can be imported using import apps.{name, settings, ...}.
• libs: The libs module contains mostly third-party libraries used to interact with hardware.
• system: This module builds the foundation for the whole framework. It contains the kernel which controls Wi-Fi, storage, input, events, logging and application loading. Additionally, the application and screen classes are defined within here.

The Kernel is invoked by the bootstrap.py file in the ports/esp32/modules directory. The building process for the firmware follows micropython’s instructions which can be found here and here.

The display driver and framebuffer are to be found in ports/esp32/moddisplay.

After successfully flashing the firmware onto the badge you should be able to use the badge. For features that require backend connectivity please follow the instructions in section backend to set up a working backend to connect your badge to.

If you don’t want to run your own provisioning server there is also the possibility to copy applications directly onto your badge using ampy.py. The applications must have the following directory structure /apps/$APPNAME/ where $APPNAME is a valid python module name (e.g. no spaces, no number as first character, …) and the content of that folder must be a valid python module (init.py) that exposes a class called App that is derived from system.app.App. A valid App must specify at least one screen that is derived from system.screen.Screen.

A very simple app could look like this:

python
import display
from system import app, screen

class ExampleScreen(screen.Screen):

    HIDE_KERNEL = True

    def update(self, delta=0):
        self.display.fill(display.BACKGROUND)
        self.display.text('Hello world!', 0, y=0)
        self.display.update()

class App(app.App):
    screens = [
        ExampleScreen(),
    ]

To convert your images, I included my conversion script that uses GIMP’s .h file export and requires you to convert the image to the correct format by selection Image > Mode > Indexed... > Use black and white (1-bit) palette before the export.

Therefore, I recommend using one of the awesome tools written by attendees during the conference. I could only find Philippe’s one, but thanks to all of you!

Backend

The backend is a simple Django server with a few models. For those not familiar with Django I recommend reading the tutorial or looking at the documentation. Using a virtualenv for the installation is strongly recommended.

To recreate the development environment used to develop the server follow this simple steps:

1. Clone the provisioning server repository to your local machine and navigate to the folder in a terminal of your choice.
2. python3 -m virtualenv .venv
3. source .venv/bin/activate
4. pip install -r requirements.txt
5. python manage.py runserver

This should spawn the server listening on localhost port 8080. To create an administrative user run python manage.py createsuperuser.

The badge can connect to your server either via

HTTP: You don’t have to setup any special software. This is only recommended for local trusted networks.

HTTPS: To use encryption set up nginx, apache, socat, … together with an SSL/TLS certificate to reverse proxy your python server.

To add your own apps to the server just navigate to the admin interface (/admin/) and look for Badge > App > Add. The applications available during the conference can be downloaded in the GitHub repository shown below.

Source Code

All sources are available from the ERNW GitHub account within these repositories:

• https://github.com/ernw/tr19-badge-backend
• https://github.com/ernw/tr19-badge-firmware
• https://github.com/ernw/tr19-badge-apps

We are very excited to see what apps and hacks for the badge will be created. Hopefully, you enjoy your badge!

Until next year… Stay tuned! #TR20

Cheers,
Jeff and Malte