AWS Builder Center
The lazy guide: Hacking a conference badge

The lazy guide: Hacking a conference badge

Most people glance at the small black rectangle on my lanyard and assume it is a name tag. It is a Pimoroni Badger 2040, a small e-ink computer, and between handshakes it switches from my photo to a contact QR code to a company logo. Everything it shows comes from one JSON file. People keep asking how it works, so here is the whole build, start to finish.

Series: IoT, Electronics, Wearables & Hackable Badges (1 article)

  1. 1
    The lazy guide: Hacking a conference badge This article
At every conference you receive a paper badge with your name on it. Sometimes it has a QR code, and the fancy ones include an NFC tag. Afterwards it goes in a drawer. You cannot change what it says, and you cannot put your own QR code on it for people to scan.
Below is my personal Badger 2040 and all the accessories I have 3D printed or purchased to customize my badge to my needs

The Pimoroni Badger 2040 fixes that. It is a small, hackable e-ink computer you wear on a lanyard, and it can show a different face for every event, every room, or every conversation.
By the end of this guide you will have a Badger 2040 with one section per front button, showing a photo badge, a logo, and QR codes that open a link or save your contact. All of it is described in one JSON file and pushed to the badge over USB with one command. You flash the board once. After that, a different badge is one edit and one deploy away.

The hardware

Badger2040

The Badger 2040 is a Raspberry Pi RP2040 microcontroller (a small dual-core chip, not a Linux computer) wired to a 296 by 128 pixel black-and-white e-ink screen, with five buttons on the front and a battery clip on the back. It is about the size of a credit card and costs roughly the same as lunch.
Two properties make it interesting to hack on.
The screen is e-ink, so it holds its image with no power at all. A normal screen has to be driven continuously to show anything. E-ink only spends power when the picture changes, and then holds the result for free. On a badge, that is the difference between hours and years: one in regular use for about three years has never needed a charge.
It runs real code. The board ships with Badger OS, a MicroPython build (version 1.23.0 on Badger OS v0.0.5) with a launcher that lists every Python file in its app folder as an icon you select with the buttons. There is no app store and no sandbox. You write Python, copy it over USB, and it runs. That openness is why a badge can become a contact card, a stand sign, or anything else you can draw in 296 by 128 pixels.
The catch is that writing raw drawing code for every badge gets old fast, which is where customization comes in.

How you customize it

The badge in this guide is driven entirely by one file. The firmware is a small, fixed renderer that understands four kinds of page. Everything the badge actually says, the words, the images, the QR codes, lives in a JSON config. You describe a badge in the config, and the renderer draws it.
The interaction model is deliberately simple. Three front buttons each open a section. Up and Down page through the current section and wrap at the ends. A section is a title and a list of pages, and each page is one of four types:
  •  badge : a photo on one side, a few lines of text on the other, like a name, a role and a website.
  •  image : a full-screen picture, such as a logo, a poster or a diagram.
  •  qr : a QR code that either opens a link or carries a vCard, the standard contact-card format every phone reads, so a scan offers to save the person with no typing.
  •  text : a title bar and up to six short lines.
Badge Architecture

Here is the shape of a small config: three button sections and the Project section, with a few pages between them.
{
"sections": {
"a": {"title": "Me", "pages": [
{"type": "badge", "header": "Hello", "name": "Your Name", "title": "Your role",
"website": "example.com", "image": "/images/me.png"},
{"type": "qr", "title": "Save my contact",
"vcard": {"name": "Your Name", "email": "you@example.com"}}
]},
"b": {"title": "Work", "pages": [
{"type": "image", "image": "/images/logo.png"},
{"type": "qr", "title": "What we do", "url": "https://example.com"}
]},
"c": {"title": "Here", "pages": [
{"type": "qr", "title": "Schedule", "url": "https://example.com/agenda"}
]},
"p": {"title": "Project", "pages": [
{"type": "qr", "title": "Build your own",
"url": "https://github.com/henniefrancis/badger2040"}
]}
}
}
Sections  a ,  b ,  c  and  p  are all required. The values above are placeholders, and the validator rejects them on purpose ("Your Name", any  example.com  address) so a half-edited badge never reaches the device. Step 5 shows how to get past that for a first trial.

The rules worth knowing

A few schema rules shape what you can put in a config. The section keys  a ,  b ,  c are the three buttons, and  p is a Project section reached from the launcher. You can add your own sections with any lowercase key matching  ^[a-z][a-z0-9_]{1,15}$ . A section title is up to 20 characters, and a section holds 1 to 8 pages. Each page's  type decides which other fields are legal: a  badge needs an  image , a  header and a  name ; a  qr needs exactly one of  url or  vcard .
The vCard is the one page that reaches into someone else's phone, so it pays to get right. You give it plain fields:
{"type": "qr", "title": "Save my contact", "vcard": {
"name": "Ada Lovelace", "title": "Engineer", "company": "Analytical Engines",
"email": "ada@example.com", "phone": "+44 20 7946 0000",
"url": "https://example.com", "linkedin": "https://linkedin.com/in/ada"}}
The renderer turns that into a vCard 3.0 record, and two details keep it from breaking on a strict phone. Text fields are escaped per RFC 2426, so a company like "Smith, Jones & Co" cannot split the record on its comma. The URL fields,  url  and  linkedin , are treated as URIs rather than text: their punctuation is preserved, and only control characters are stripped, so a newline hidden in a value cannot forge a new line and inject a property. LinkedIn goes out as a second  URL: property, which the spec allows.

What the screen does to your choices

Badge Screen Constraints

Customizing a 1-bit e-ink badge means living with four facts about the panel. None is hard once you know it, and each one surprises people the first time.
Every page is a full redraw. E-ink can update two ways: a fast partial refresh that nudges only the changed pixels, and a slower full refresh that clears the panel first. Partial is quicker, but it leaves ghosting, a faint afterimage of the previous page, and a ghost of a photo sitting under a QR grid is enough to stop a scan. The renderer takes the full refresh every time, trading a visible flash and a second of latency for a clean, scannable image. That decision is why paging feels deliberate rather than instant, and it is the right one on a device whose whole job is to be read.
Text only comes in whole sizes. The renderer uses a bitmap font drawn at whole integer scales, because a bitmap scaled by a whole number maps each source pixel onto an exact block of screen pixels and stays crisp. A vector font scaled to any size you like looks ragged on a 1-bit panel at small sizes. The practical effect: text fits at a whole scale or it does not, so the renderer takes the largest whole scale that fits and truncates with an ellipsis rather than shrinking. At scale 3, a name fits about 20 characters across.
Images are never resized. The decoder draws each image at its native size, so every image has to be the exact pixel dimensions of its slot. A badge photo is 104 by 128; anything wider spills off the edge. You pre-size on your computer, which is what the conversion tool in the next section is for.
QR codes have a hard size budget. A denser code has more squares, called modules, and on a 128-pixel screen each module can only be so small before a phone cannot read it. A full vCard is right at that limit, which has a surprising consequence covered in the build guide: when a packed contact card will not scan, the fix is to remove fields, because the code cannot get any bigger.

What you need

  • A Pimoroni Badger 2040 (the RP2040 model with the 296 by 128 screen).
  • A USB cable that carries data. A charge-only cable will not show the board as a drive.
  • A computer with Python 3.11 or newer, and Git.
  • A photo and a logo you are entitled to use.
What you need


The deep build guide: publishing to the badge

This is the part people get stuck on. Customizing a config is easy. Getting it onto the hardware, correctly and repeatably, is where the real work is. Here is the whole path, start to finish.

Step 1: Install the tools on your computer

Everything that builds and checks a badge runs on your laptop, not the device. Clone the repo and install the Python tools into a virtual environment:
git clone https://github.com/henniefrancis/badger2040.git
cd badger2040
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
That pulls in three things:  mpremote  (the standard tool for copying files to a MicroPython board and running them),  Pillow  (for image conversion), and  pytest  (for the test suite, if you want to run it).

Step 2: Flash Badger OS onto the board

The badge needs Badger OS v0.0.5 on it. Flashing means writing that OS image to the board's flash memory:
  1. Download the  badger2040.uf2  for v0.0.5 from Pimoroni's  releases page .
  1. Hold the BOOT/USR button on the back while you plug the board into USB. It mounts as a plain USB drive called  RPI-RP2 .
  1. Copy the  .uf2  file onto that drive. The board reboots on its own and comes up in the Badger OS launcher.
You only do this when you first set the board up or when you deliberately reset it. Deploying a new config later does not need a reflash.

Step 3: Write your config in a private folder

Keep your real config out of the public repo. Make a folder somewhere private, with subfolders for images and launcher icons, and start from the example.
macOS or Linux:
mkdir -p ~/my-badge/images ~/my-badge/icons
cp config/badge.example.json ~/my-badge/badge.json
Windows (PowerShell):
mkdir $HOME\my-badge\images, $HOME\my-badge\icons
Copy-Item config\badge.example.json $HOME\my-badge\badge.json
On Windows, use  $HOME\my-badge  wherever the commands below say  ~/my-badge .
Leave the file as it is for now. The next two steps get the untouched example onto the badge, so you know the toolchain works before you change anything. Image paths in the config are device paths like  /images/me.png ; the matching files live in  ~/my-badge/images/  and are copied across at deploy time.

Step 4: Convert your images

The board cannot resize images, so each one has to be the exact size and format of its slot.  convert_image.py  does the resizing, 1-bit conversion and dithering, with one  --kind  per slot. The file names matter: these are the ones the example config and the launcher look for.
# Pages: your photo and two full-screen logos
python tools/convert_image.py photo.jpg ~/my-badge/images/me.png --kind photo # 104 x 128
python tools/convert_image.py logo.png ~/my-badge/images/company.png --kind logo # 296 x 128
python tools/convert_image.py event.png ~/my-badge/images/event.png --kind logo # 296 x 128

# Launcher icons, 52 x 52, in the icons folder (not images)
python tools/convert_image.py logo.png ~/my-badge/icons/icon-company.png --kind icon
python tools/convert_image.py event.png ~/my-badge/icons/icon-event.png --kind icon
python tools/convert_image.py logo.png ~/my-badge/icons/icon-project.png --kind icon
You can skip this step on a first trial. The repo ships labeled placeholder images, and the next step shows the flag that allows them.
Dithering is what makes a photo legible in one bit: it scatters black and white pixels in a pattern your eye blends into gray.

Images on Badge


Step 5: Validate before you deploy

Everything that can be wrong with a config should be caught on your laptop, where you can read the error, not on a 296-pixel screen. The validator runs the same checks the device runs, sizes every QR code, confirms every referenced image exists, and reports anything that will not fit.
For a first trial, with the untouched example and the repo's placeholder images:
python tools/validate_config.py ~/my-badge --allow-placeholders --allow-placeholder-images
It prints one line per QR page, warns about each placeholder image, and ends with  config OK :
QR section a page 2 216 bytes 53 modules border 0 2 px/module 106 px
QR section a page 3 19 bytes 25 modules border 0 5 px/module 125 px
QR section p page 1 43 bytes 29 modules border 0 4 px/module 116 px
...
WARNING: launcher icon icon-company.png would fall back to a repo PLACEHOLDER; put your own file in ~/my-badge
config OK
Each QR line reads: page, payload bytes, modules per side, quiet-zone border, pixels per module, final size. Section  a  page 2 is the full seven-field vCard; section  p  page 1 is a plain URL.
Once the trial badge works, edit  badge.json  with your real details, convert your own images (step 4), and run the validator with no flags:
python tools/validate_config.py ~/my-badge
Without the flags it fails on anything still set to an example value ("Your Name", an  example.com  address, the  +00 000 000 0000  phone number, a  your-handle  LinkedIn URL) and on any logo or launcher icon you have not replaced. Fix what it names and run it again until you see  config OK .
The QR sizing is exact, because the module count comes from the same capacity math the device uses. Text fitting is the one estimate: without the device font, the validator approximates each character at about 4.8 pixels and labels those warnings as estimates, so the device stays the final authority on text width.
This step is also where the QR budget bites. A full seven-field vCard lands between about 53 and 61 modules, which at 128 pixels sits right at the two-pixel-per-module floor below which phones stop reading. Whether it can also carry a quiet zone, the blank margin a scanner likes, depends on where in that range it lands. At 53 modules a four-module border still fits ( 128 // (53 + 8) = 2 ). At 61 it does not ( 128 // (61 + 8) = 1 , below the floor), so the code goes out with no margin at all.
The codes use the lowest error-correction level, L, and that is a deliberate choice. Error correction is spare capacity a scanner uses to rebuild a code from a bad photo, and the stronger levels buy that resilience by adding modules, which is the one resource a 128-pixel screen does not have. Level L keeps the code as small as it can be. The trade-off: a dense vCard at level L has no margin in reserve, so it reads cleanly in good light and gets fussy in bad. That is the real reason the hosted-URL option exists. If the validator refuses your vCard, drop a field or two. If reliability at a dim, crowded booth matters more than working with no network at all, host the vCard somewhere and encode a short URL instead: that is about 29 modules, with room for a real quiet zone and stronger error correction.

Step 6: Deploy over USB

With the board plugged in, deploy pushes your badge to it. First find the serial port:
  • On Windows it is a  COM  port, listed in Device Manager (often  COM3 ).
  • On macOS or Linux it looks like  /dev/tty.usbmodem...  or  /dev/ttyACM0 .
  • Either way,  mpremote connect list  prints the connected boards.
If the badge already has anything on it you want to keep, back it up first:
python -m mpremote connect COM3 fs cp -r :images backup/files/
Then preview the deploy.  --dry-run  validates and prints the exact file list without touching the badge:
python tools/deploy.py --config ~/my-badge --dry-run
Then deploy, using your own port:
python tools/deploy.py --config ~/my-badge --port COM3 # Windows
python tools/deploy.py --config ~/my-badge --port /dev/ttyACM0 # Linux
For the first trial with the untouched example, add  --allow-placeholders --allow-placeholder-images  to both commands.
 deploy.py  does four things in order. It validates the config first and refuses to copy anything if validation fails. It copies a precise file list over USB with  mpremote : the launcher, the renderer (lib/badgekit.py), the small wrapper apps and their icons, your images, and your  badge.json . It resets the launcher state, writing /state/launcher.json back to  {"page": 0, "running": "launcher"} , because Badger OS remembers the last running app and a deploy that skips this boots straight back into the old app instead of your new launcher. And it leaves everything else on the device untouched.
A failed or half-finished copy is the one thing validation cannot prevent, so the renderer has its own net. If the config on the device is missing, truncated, or not valid JSON, it draws an error page naming the problem ("Config is not valid JSON") with a hint at the path, rather than a blank screen or a Python prompt you would need a cable to read.

Step 7: Verify on the device

Unplug the data cable or leave it connected, then exercise the badge by hand. Press A, B and C to open each section. Press Up and Down to page through a section and confirm it wraps at the ends. Point a phone at each QR page and check that links open and the vCard offers to save a contact. In practice the embedded vCard scans on the first try, which is why it stays in the config; the day it misses once, switch that page to a hosted URL.
If you want to trust changes without the hardware in hand, run the test suite. Because the renderer's logic is plain Python with no hardware imports, the repo ships fake  badger2040 ,  badger_os ,  pngdec and  qrcode modules and tests the real layout, paging, vCard and validation code against them: 1306 tests that finish in under a minute with no device attached.
python -m pytest -q

Step 8: Wipe it when you are done

The config sits on the badge as plain text, so clear it before you lend, sell or bin the board. Delete the config, the saved state and your images:
python -m mpremote connect COM3 fs rm :badge/config/badge.json
python -m mpremote connect COM3 fs rm -r :state
python -m mpremote connect COM3 fs rm -r :images
E-ink keeps the last picture with no power, so press a button afterwards to make the screen redraw. The badge then shows its error page instead of your details. To use it again, deploy a new config.

Troubleshooting the publish

A few failures are common enough to name:
  • The badge boots into the wrong screen after a deploy. The launcher state was not reset. Deploy normally handles this; if you copied files by hand, write /state/launcher.json back to  {"page": 0, "running": "launcher"} .
  • A page is blank or text is missing. On a 1-bit panel, "nothing drew" and "it drew white on white" look identical. This is usually a drawing color left wrong after an image decode; the renderer guards against it, so suspect a custom page first.
  • A photo overflows its slot. The image is not the exact slot size. Re-run  convert_image.py  with the right  --kind .
  • A QR will not scan. It is too dense. Shorten the vCard or switch to a hosted URL (see step 5).
  • Updates do not appear. Confirm the port, confirm deploy reported success, and remember that between button presses on battery the board powers itself off, so give it a moment to wake and redraw.

Keeping your details private

A badge carries a real name, phone number and email, and the reference code is public. The safeguard is the folder structure, so it does not depend on you remembering. The public repo holds the renderer, the tools, and clearly labeled placeholder images. Your real config, photo and logos live in the private folder from step 3, which is why  deploy.py  takes a  --config  flag pointing at it and why  .gitignore  keeps real config out of the tree. A hygiene test backs that up by failing the build if a tracked file contains anything that looks like a real email, phone number or handle, though it scans the current tree, not git history, so it needs a pre-commit hook to stop a leak before it is pushed. One thing no tool can fix: the config is stored as plain text on the device, readable by anyone who plugs in a cable, so put only business-card detail on it and wipe it before you lend, sell or bin it.

When this is overkill

If you are building one badge, for one event, that you will never change, skip the config machinery and hardcode it. The schema, the validator and the tooling only pay back across changes a one-off never makes. And if you want an animation, a live sensor readout, or a game, that is behavior rather than content, so write a normal MicroPython app instead of bending a config to host it. The approach in this guide fits content that varies on a device whose behavior does not, which is exactly what a conference badge is.

Credit where it is due: Badger 2040 Studio

While finishing this article I found  Badger 2040 Studio , an open-source project by Enrique Gamboa. It is a visual editor for the Badger 2040 that runs in your browser. You drag text, shapes and lines onto a canvas, press one button, and the design goes to the badge over USB through the Web Serial API. There is no Python environment to install and no code to edit. It can also run and customize Pimoroni's official examples, such as the standard badge, the clock and the ebook reader.
Enrique explains the project in his Medium post,  The Ultimate UI for Pimoroni Badger 2040 , and the source is on  GitHub . Go and give it a star.
This matters because everything above assumes you are comfortable in a terminal. Plenty of people who would love a badge like this are not: event organizers, speakers, recruiters, community managers, teachers, students, a sales team on a stand. If that is you, or someone you are setting a badge up for, start with the Studio. You need the badge, a USB-C data cable and a browser that supports Web Serial, such as Chrome or Edge.
The two approaches solve different problems. The Studio is the quickest way to get a design you drew yourself onto the screen. The config in this guide is for a badge with several sections, QR codes and a contact card that you redeploy for every event. I have not run both on the same badge yet, so back up your badge before you switch from one to the other.

Show me your badge

If you have a Badger 2040, build something with it and tag me (@henniefrancis here on Builder Center) in a photo of your design. Conference badges, stand signs, desk signs, a QR code to your talk slides: I want to see what you come up with.

Series: IoT, Electronics, Wearables & Hackable Badges (1 article)

  1. 1
    The lazy guide: Hacking a conference badge This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article