API reference

Welcome to the API reference for the BADGE.TEAM platform firmware.

This reference describes all officially supported APIs of our platform. We try to keep these APIs as stable as possible. There are many more (undocumented) APIs in the firmware, all of which may change at any time!

Our platform firmware uses MicroPython at it’s core. Most of the libraries and APIs from the upstream MicroPython project are available in the BADGE.TEAM firmware.

The MicroPython documentation describes the builtin libraries and functions.

Specifically, the MicroPython core in our firmware is based on the ESP32 port of MicroPython by Loboris. He changed some parts of MicroPython to suit the ESP32 better. The wiki of his project describes the changes he made.

We have made a lot of changes on top of the work done by Loboris. We’ve added some badge specific APIs, a brand new framebuffer system for displaying graphics and drivers for the hardware specific to the supported badges.

By doing this we aim to take the resource intensive parts of driving the hardware to the C level beneath Python. This allows for a much more speedy experience and a lot more possibilities and flexibility.

Things to keep in mind while looking up documentation

  • There is currently no API available for directly controlling the SPI bus(ses) of your badge from within Python.
  • I2C should be used with caution as the I2C bus on most badges is used for system peripherals as well.
  • The Neopixel (LED) driver differs greatly from the neopixel API in the Loboris port.
  • The Display driver differs greatly from the display API in the Loboris port.

If you want to help with firmware development please tell us! We’re always happy to accept PRs and improvements.

Should you have ideas, problems or observations but no means to act on them then you can always create an issue on Github.

BADGE.TEAM platform APIs

Library Function SHA2017 Disobey 2019 HackerHotel 2019 CampZone 2019 CampZone 2020
display Control the display of your badge: create and display text and graphics
buttons Read button status and attach callback functions to button interactions
wifi Abstraction layer wrapping the network API for connection to WiFi networks
system Abstraction layer for starting apps and controlling badge behaviour and sleep mode
consts Reference containing constants describing your badge and it’s firmware
audio Easy to use wrapper around sndmixer for playing audio files
sndmixer Audio related functions in active development, may change at ANY time Partially
terminal Helper functions for presenting a user interface over the serial port or telnet
opus Opus encoding and decoding
neopixel Control the addressable LEDs on your badge
mpu6050 MPU6050 accelerometer and gyroscope control
ugTTS A small library to generate and play back Text-to-Speech voice messages
espnow Mesh networking API utilizing the Espressif ESPNOW features of the ESP32
hid Send keyboard and mouse events over USB (only on supported boards)
midi Send MIDI messages over USB (only on supported boards)
keypad CampZone 2020 specific silicon keypad button event handler
touchpads Register callbacks that trigger when ESP32 touch pads are touched
samd Disobey 2019 specific hardware interface module
rgb Legacy display API for CampZone 2019 badges
keyboard Display a text entry form complete with on-screen-keyboard
umqtt MQTT client library
ssd1306 Direct SSD1306 display control (will be removed in a future release)
erc12864 Direct ERC12864 display control (will be removed in a future release)
eink Direct E-INK display control (will be removed in a future release)
rtc Legacy real-time-clock API (please use machine.RTC and utime instead) ✅  
_buttons Generic GPIO button handler API, usefull for adding extra buttons to GPIO headers ✅  
voltages API for reading various voltages, exact functionality differs per badge
esp32_ulp Collection of helper functions for using the Ultra Low Power co-processor

APIs that differ from their upstream counterparts

Other libraries and APIs

This section lists most of the other libraries that you can use in your apps.

Library Function Documentation
math Mathematical functions MicroPython
cmath Mathematical functions for complex numbers MicroPython
ubinascii Utilities for working with binary data (Hex-string, base64 and CRC32 calculation MicroPython
ucollections Collection and container types MicroPython
uerrno System error code reference MicroPython
uhashlib SHA1 and SHA256 hashing algorithms MicroPython
uheapq Heap queue algorithm MicroPython
uio Input/output streams MicroPython
ujson JSON encoding and decoding MicroPython
uos Basic “operating system” services MicroPython
ure Simple regular expressions MicroPython
uselect Wait for events on a set of streams MicroPython
usocket Sockets (TCP, UDP) MicroPython
ussl SSL/TLS module MicroPython
ustruct Pack and unpack primitive data types MicroPython
utime Time related functions MicroPython
uzlib Zlib decompression MicroPython
_thread Multithreading support MicroPython
gc Control the garbage collector MicroPython
sys System specific functions MicroPython
machine Functions related to the hardware (Note: different from upstream version) [BADGE.TEAM]](machine)
micropython Access and control MicroPython internals MicroPython
network Network configuration (Please use the wifi library instead when possible) MicroPython
esp ESP32 specific functions (Note: direct flash access has been disabled) MicroPython

Utilities

Library Function
pye Built-in text editor