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

LibraryFunctionMCH 2022SHA2017Disobey 2019HackerHotel 2019CampZone 2019CampZone 2020
displayControl the display of your badge: create and display text and graphics
buttonsRead button status and attach callback functions to button interactions
wifiAbstraction layer wrapping the network API for connection to WiFi networks
systemAbstraction layer for starting apps and controlling badge behaviour and sleep mode
constsReference containing constants describing your badge and it’s firmware
audioEasy to use wrapper around sndmixer for playing audio files
sndmixerAudio related functions in active development, may change at ANY timePartially
terminalHelper functions for presenting a user interface over the serial port or telnet
neopixelControl the addressable LEDs on your badge
mpu6050MPU6050 accelerometer and gyroscope control
ugTTSA small library to generate and play back Text-to-Speech voice messages
espnowMesh networking API utilizing the Espressif ESPNOW features of the ESP32
hidSend keyboard and mouse events over USB (only on supported boards)
midiSend MIDI messages over USB (only on supported boards)
keypadCampZone 2020 specific silicon keypad button event handler
touchpadsRegister callbacks that trigger when ESP32 touch pads are touched
samdDisobey 2019 specific hardware interface module
rgbLegacy display API for CampZone 2019 badges
keyboardDisplay a text entry form complete with on-screen-keyboard
umqttMQTT client library
ssd1306Direct SSD1306 display control (will be removed in a future release)
erc12864Direct ERC12864 display control (will be removed in a future release)
einkDirect E-INK display control (will be removed in a future release)
rtcLegacy real-time-clock API (please use machine.RTC and utime instead)✅  
_buttonsGeneric GPIO button handler API, usefull for adding extra buttons to GPIO headers✅  
voltagesAPI for reading various voltages, exact functionality differs per badge
esp32_ulpCollection 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.

LibraryFunctionDocumentation
mathMathematical functionsMicroPython
cmathMathematical functions for complex numbersMicroPython
ubinasciiUtilities for working with binary data (Hex-string, base64 and CRC32 calculationMicroPython
ucollectionsCollection and container typesMicroPython
uerrnoSystem error code referenceMicroPython
uhashlibSHA1 and SHA256 hashing algorithmsMicroPython
uheapqHeap queue algorithmMicroPython
uioInput/output streamsMicroPython
ujsonJSON encoding and decodingMicroPython
uosBasic “operating system” servicesMicroPython
ureSimple regular expressionsMicroPython
uselectWait for events on a set of streamsMicroPython
usocketSockets (TCP, UDP)MicroPython
usslSSL/TLS moduleMicroPython
ustructPack and unpack primitive data typesMicroPython
utimeTime related functionsMicroPython
uzlibZlib decompressionMicroPython
_threadMultithreading supportMicroPython
gcControl the garbage collectorMicroPython
sysSystem specific functionsMicroPython
machineFunctions related to the hardware (Note: different from upstream version)[Badge.team]](machine)
micropythonAccess and control MicroPython internalsMicroPython
networkNetwork configuration (Please use the wifi library instead when possible)MicroPython
espESP32 specific functions (Note: direct flash access has been disabled)MicroPython

Utilities

LibraryFunction
pyeBuilt-in text editor