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 | MCH 2022 | 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 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 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 |