Skip to content
Universal badge platform for ESP32 based devices! Runs on the event badges from SHA2017, HackerHotel 2019, Disobey 2019, CampZone 2019 and more!
C Python C++ Makefile Roff Shell Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
esp-idf @ 559a9de

New ESP32 Firmware

This repository contains the reworked firmware platform for generic ESP32-based hardware devices. firmware has been used by many event badges, such as:

  • SHA2017
  • HackerHotel 2019
  • Disobey 2019
  • CampZone 2019

Debian prerequisites

sudo apt-get install make unzip git libncurses5-dev flex bison gperf python-serial libffi-dev libsdl2-dev libmbedtls-dev perl

Preparing your setup

First, make sure you pull the submodules in the project:

git submodule update --init --recursive

Next, copy the xtensa build toolchain for your OS (currently supporting Linux and Mac OS) from /toolchains/, and unpack and save it as /xtensa-esp32-elf/ in the project root folder:

unzip -p toolchain/ xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar | tar xv

Building for a specific existing badge

Copy the relevant config file from /firmware/configs/<badge>_defconfig to /firmware/sdkconfig:

cp firmware/configs/sha2017_defconfig firmware/sdkconfig

Build instructions

Set the path to esp32-toolchain (you have to repeat that on every new terminal) (usually it is located in your ESP32-platform-firmware directory):

export PATH="$PATH:/path/to/my/toolchain/xtensa-esp32-elf/bin"

To build and flash the basic generic firmware:


Make sure you have downloaded the appropriate driver for the USB UART chip on your device. Below are some from popular badges.

If you have this issue with flashing: serial.serialutil.SerialException: [Errno 2] could not open port : [Errno 2] No such file or directory: '' Then you need to copy the python2 command that ./ suggests, and make sure the --port argument has the right value.

Interacting via serial

By default, the firmware activates a simple python shell or serial menu after booting. You can interact with it by running:


Creating new hardware

You can use firmware for your own-designed badge or device. The workflow for this is described below.

  • Run ./, configure the Firmware & device configuration submenu (for the folder option in the Hardware description section, think of any name. We will use it later.), and set up the drivers that your hardware will use in the Components submenu.
  • If you need to write drivers of your own, take a look at the driver documentation.
  • Create a directory with the folder name you configured in the first step in /firmware/python_modules, and copy /firmware/python_modules/generic/* into it.
  • In this directory, you can write Python code that will be built into the firmware image. The files and are executed after each other on boot, and from there you can launch your own things.
  • Build and flash, and you're done!

License and information

Copyright (C) 2017-2019 BADGE.TEAM

Uses the Micropython port for ESP32 by Loboris

Uses ESP-IDF by Espressif

You can’t perform that action at this time.