Building an Epaper Badge with a Raspberry PI Zero

I’ve been wanting to build an electronic badge for Defcon for the past few year, this year I finally did it. Unfortunately during the build I did not keep an actual log, so this will be missing images at key portions. This overview assumes the reader has prior experience with soldering, python, linux, and the raspberry pi.

Parts List

• Raspberry Pi Zero, I used a Zero W, a standard Zero will work just as well. https://www.amazon.com/Raspberry-Zero-v1-3-Development-Board/dp/B01L3IU6XS
• Raspberry Pi Zero header pins, or purchase a raspberry pi zero kit that comes with these. https://www.amazon.com/Break-away-2x20-pin-Strip-Header-Raspberry/dp/B0756KM7CY
• Waveshare 3 color E-Ink display, there are other similar displays, I have no idea how well they’ll work with the python code I wrote. https://www.amazon.com/gp/product/B07DH6HLCK
• Pimoroni Buttonshim, https://shop.pimoroni.com/products/button-shim
• Raspberry Pi Zero case, https://www.amazon.com/gp/product/B01KTG03M4
• Self adhesive belt clip, https://www.amazon.com/gp/product/B00HUV8FWW

Other Parts and Tools

• Soldering Iron
• Soldering helping hands
• Solder
• USB micro cable
• USB battery
• MicroSD card
• Some means of writing to a MicroSD card

Install Header Pins

The Pi Zero usually comes without the header pins installed, so the first step is to solder the pins on.

Install ButtonShim

Now with the pins installed, flip the Pi over and solder the ButtonShim on. Make sure to leave the top of the pins clean since the E-Ink screen needs to go above this.

Install Raspberry Pi Zero Case

Only install the bottom half of the case, the screen won’t fit with the top half installed.

Install E-In Screen

Take screen, put on to of header pins, press down.

Download and Install Raspbian

Download the latest version of Raspbian, there are other distros, they should all work equally, I choose Raspbian. Additionally since I used a zero I setup wifi and ssh for remote access.

Download Waveshare Dependencies

Based on https://www.waveshare.com/wiki/Pioneer600#Libraries_Installation_for_RPi first install the necessary packages, under the latest version of raspbian all of the libraries they mention are available at packages in os repository.

sudo apt-get update && sudo apt-get install python-dev python-smbus python-serial python-imaging python-rpi.gpio wiringpi python-spidev fonts-freefont-ttf

Download ButtonShim Dependencies

The team at Pimoroni makes this step very very easy, run the following

curl https://get.pimoroni.com/buttonshim | bash

This installs the python buttonshim library which provides decor

Enable interfaces

Run the raspi-config command, then select Interfacing options, then enable SPI I2C Serial

afterwards reboot your Pi

Testing the Hardware

First check the screen, download the waveshare demo from https://www.waveshare.com/wiki/File:2.13inch-e-paper-hat-b-code.7z

Unzip the archive, navigate to the raspberry pi demo, run the demo, if everything worked the screen should cycle through some images

Next check the buttonshim, download the demo code from https://github.com/pimoroni/button-shim/blob/master/examples/rainbow.py

run that, hit some buttons, watch the led change colors.

Installing the Badge Code

Assuming all hardware is functioning as expected, its time to either write your own badge code, or install the code I wrote.

Download https://github.com/jheise/ebadge/blob/master/badge.py into the same directory as the demo code for the epaper screen, there are a number of libraries that are not accessible system wide and this is the fastest way to make use of them.

Next run `sudo mkdir -p /var/badge/images`, /var/badge is where all data for the badge is stored. Using your text editor of choice open /var/badge/slogans.txt, this is a tab separated file holding all the text that gets displayed on the badge, lines need to be written as follows:

“DISOBEY <TAB> [scale|static|any] <TAB> [centered|static|any]”

In the above example, the first field is the slogan to display; the next field determines if the text should be scaled, not scaled, or randomly chosen; the final field determines if text should be centered, always start left justified, or randomly chose. Additionally lines can be commented out by making the first character in the string “#”.

Once slogans are ready its time to add some images, images for the screen must be in the form of bitmaps with a resolution of 104 x 212, images also must use only black and white as the image acts as a mask for what pixels to flip. The image loading function in script will only load images to black and white, but the screen is fully capable of loading two separate bitmaps that match together to make a three color image. Place any image you’ve made in /var/badge/images

Give the script a quick test run, make sure at least one slogan and one image loads before moving on.

Starting the Badge Script at Launch

There are plenty of ways of handling this, this was the method I used because I had no interest in dealing with init scripts or systemd or whatever means raspbian is using to launch things at boot

First move the python directory from the demo, where you downloaded the badge script to, move that /var/badge along with the rest of the files

With your favorite text editor open /home/pi/launcher.sh, write the following

#!/bin/sh
echo "Launcher starting..."
cd /
cd /var/badge/python
echo "sleeping for 20 seconds while spi interface comes up"
sleep 20
/usr/bin/python badge.py
cd /

Make the script executable and then add it to root’s crontab with the following

@reboot sh /home/pi/launcher.sh > /home/pi/logs 2>&1

Now reboot and see if it works.

Bonus Points: Using the USB Gadget Mode of the Pi Zero

By now the badge should be powering up and changing text and images without human interaction, but when you want to change slogans or add images you either need a network connection or to pop the sd card out and write to it directly. Fortunately the raspberry pi zero can also act as a mass storage device, with this set up you just need to plug the badge into a computer and edit any code, text, or images your want over usb. These directions have been adapted from https://www.raspberrypi.org/magpi/pi-zero-w-smart-usb-flash-drive/

First move /var/badge to /var/badge.bak, the new partition is going to be mounted at /var/badge.

Next we need to allocate some space for the new part, put a file system on it, and create the mount point

sudo dd of=/var/badgefs.bin if=/dev/zero bs=1M count=2048
sudo mkdosfs /var/badgefs.bin -F 32 -I
sudo mkdir /var/badge

Now make the entry in /etc/fstab with your favorite text editor

/var/badgefs.bin /var/badge vfat users,umask=000 0 2

Mount the partition back and copy the contents of /var/badge.bak into the new version

sudo mount /var/badge
cp -r /var/badge.bak/* /var/badge

To actually turn on the USB mass storage functionality a few different modules need to be enabled.

First enable the USB overlay driver, open /boot/config.txt with your favorite text editor, and at the bottom add

dtoverlay=dwc2

then open /etc/modules and add the following to the bottom

dwc2

Now to actually make the partition available on USB, add this line into /etc/rc.local, this line needs to go above exit 0 at the end of the file

modprobe g_mass_storage file=/var/badgefs.bin removable=1 ro=0 stall=0

Now plug the pi directly into a computer and see if it mounts. I’ve only tested this on Ubuntu 18.04 Desktop edition and MacOS, I’m not certain if there will be issues under Windows