Machine

1: Non Volatile Storage
2: The I2C bus
3: Pin: direct GPIO control

The machine API makes it possible to access certain hardware interfaces directly, allowing for example direct control of GPIOs, busses (I2C) and other interfaces.

This API is variation on the standard MicroPython machine API which has been extended and modified.

Not all features described in the official MicroPython documentation are available on the Badge.team platform firmware. And additionally some functions will differ in syntax from the official MicroPython for ESP32 firmware.

Non Volitile Storage (NVS)

The NVS functions allow for storage and retrieval of small amounts of data to be stored. This API is used to access WiFi credentials and other system information and can be used to manipulate system settings as well as for storing settings specific to your app.

Direct GPIO control

The Pin API can be used to directly control GPIOs of your badge.

I2C bus

The machine API for I2C allows you to control the system I2C bus of your badge, the I2C bus exposed on the SAO, Grove, Qwiic or other extension ports as well as a second I2C bus on any two broken out GPIOs of your choice.

SPI bus

Direct control over the SPI bus is currently not supported on the Badge.team platform firmware. Sorry!

1 - Non Volatile Storage

This page describes the Non-Volatile-Storage (NVS) functions of the machine API. This NVS is used to store settings such as WiFi credentials and your nickname.

The NVS storage is a function of the ESP-IDF which allows for settings to be stored in a special partition on the flash of the ESP32 and is ment for small quantities of data. If you want to store large(er) amounts of data we suggest you use the filesystem functions of MicroPython to store your data on the FAT partition instead.

Reference

Command	Parameters	Description
nvs_set_u8	[space], [key], [value]	Store an unsigned 8-bit value
nvs_get_u8	[space], [key]	Retrieve an unsigned 8-bit value
nvs_set_u16	[space], [key[, [value]	Store an unsigned 16-bit value
nvs_get_u16	[space], [key]	Retreive an unsigned 16-bit value
nvs_setint	[space], [key], [value]	Store a signed integer value
nvs_getint	[space], [key]	Retreive a signed integer value
nvs_setstr	[space], [key], [value]	Store a string
nvs_getstr	[space], [key]	Retreive a string
nvs_erase	[space], [key]	Remove an entry from the NVS
nvs_erase_all	[space]	Remove all entries in a space from the NVS

NVS settings used by the firmware

The following list describes the settings stored by the Badge.team firmware.

Space	Key	Type	Function
owner	nick	string	The nickname of the owner of the badge
system	default_app	string	The app/egg launched on powerup

NVS settings for your app

Please use the slug name of your app as the name of the space used to store your settings.

Examples

Nickname

Reading the nickname

import nvs
nickname = nvs.nvs_getstr("owner", "nickname")
print("Your nickname is '{}'!".format(nickname))

Setting the nickname

import nvs
nvs.nvs_setstr("owner", "nickname", "Badge.team")

2 - The I2C bus

The ESP32 has two I2C controllers, each of which can be set to master or slave mode. Most of our badges use one of these I2C controllers for their internal I2C bus. You can take control over this system I2C bus using the machine API without directly causing issues but be adviced that doing this might possibly disrupt communications with one or more system components like the touch-button controller IC or the display.

Alternatively you can use the I2C API to define a secondary I2C bus on any two broken out GPIO pins.

Direct I2C access

The firmware contains a second API for working with the system I2C bus, allowing you to directly call some ESP-IDF I2C functions from within MicroPython.

(to-do)

Using the MicroPython machine.I2C API

While the directly exposed functions do already allow you to control i2c devices it is also possible to use the MicroPython I2C API on the same bus, simply by creating the bus using the exact settings used by the firmware itself.

The following snippet redefines i2c to be the MicroPython variant of the API instead of our direct functions. This snippet should work on all badges since it automatically uses the right pins for SDA and SCL as well as the correct bus speed for the board you are using.

import i2c, machine
i2c = machine.I2C(sda=machine.Pin(i2c.GPIO_SDA), scl=machine.Pin(i2c.GPIO_CLK), freq=i2c.SPEED)

If your board does not have a system I2C bus or if you want to use separate GPIOs for connecting your I2C device then you can also define a custom I2C interface on pins you choose. Keep in mind that the ESP32 can handle up to two I2C busses at once so if the firmare itself uses one then you can create only one custom i2c bus interface.

import machine
my_i2c_interface = machine.I2C(sda=machine.Pin(22), scl=machine.Pin(21), freq=100000)

3 - Pin: direct GPIO control

Direct GPIO control

The machine.Pin API allows you to directly control GPIOs of the ESP32 on your badge.

Please check the schematics of your badge before using this API. If you configure the GPIOs of the ESP32 in a wrong way your might cause your badge to crash, stop responding or even permanently damage it. Be carefull!

Basic digital input

from machine import Pin
myInput = Pin(0) # GPIO0 (exposed as the "flash" button on most badges)
value = myInput.value()
print("The value of GPIO0 is {}.".format(value))

Basic digital output

from machine import Pin
myOutput = Pin(<GPIO NUMBER>, Pin.OUT) # Check the schematic of your badge to find the numbers which can be entered here
myOutput.value(True) # Set the pin state to 1 or "HIGH"

Interrupts

(To-Do)

Pulse Width Modulation (PWM)

(To-Do)

Wakeup from deep-sleep

(To-Do)