From Badge team
Jump to navigation Jump to search

Badge splash screen service API

Introduction to splash screen services

What is a service?

A service is a small program bundled with an app which allows apps to execute background tasks while the badge shows the splash / home screen.

How can I create a service?

A service is a small program included with an app as a separate Python file, from which a couple of functions are executed. The file should be called “” and it should be bundled with your app files.

What does a service script look like?

Each service script contains three functions: setup, loop and draw. Each of this functions is called by the splash application at different moments. In the next chapter of this document each of these three functions will be discussed in detail.


Your service has to contain each of the following three functions, even if no action is to be performed at all.

void setup ( void )

The setup function is called directly after wakeup and is to be used to initialize the service.

prevent_sleep loop ( counter )

The loop function is called by a timer ran a configurable amount of times before the badge starts sleeping again. Sleep can be prevented by returning True. Normal operation requires this function to return False.

The counter value represents the amount of times the loop function will be ran before the badge starts sleeping. The lowest value your service will see is 1, when the counter is at 1 the current execution will be the last one before sleep kicks in.

height draw ( x , y )

This function is called just before the screen is updated and allows your service to add information or widgets to the homescreen. The x and y coordinates provided to you are the location of the bottom-left corner of the location designated to your service. Currently x is always set to 0 and you may use the full width of the screen. The return value should be set to the amount of pixels used by your information string or widget. The next widget will be drawn upwards from coordinate (x+height, 0).

Should you decide not to use the location appointed to you then please return 0. Also note that conflicts between multiple services can occur if you place your content at an arbitrary place on the screen. Because of this I suggest you to never do that. Unless of course the purpose of your app is overriding existing elements like the nickname.

NVS settings

You can use these via the badge nvs getter / setter features.

Namespace Key Type Info
badge wifi.ssid string WiFi access point to connect to
badge wifi.password string WiFi password (optional)
owner name string Your (nick) name
splash header.invert string 0: normal operation, 1: inverted

Controls the way the header is drawn (default: 0)

splash header.hws string 0: normal operation, 1: hide header while sleeping

(default: 0)

splash header.hbws string 0: normal operation, 1: hide battery indicator while sleeping

(default: 0)

splash sleep.duration string 30000 up to 120000 (default: 60000)

Amount of time the badge deep-sleeps between updates

splash battery.volt.min string Voltage of battery when completely empty in mV (default: 3800)
splash battery.volt.max string Voltage of battery when completely full (n mV (default: 4300)
splash battery.percent.empty string Battery percentage below which the badge will become unusable

(default: 1)

splash ntp.timeout string Amount of connection tries before NTP fails

(default: 40)

splash bpp.count string Amount of wake-up or reboot cycles before BPP triggers

(default: 5)

splash timer.interval string Interval between timer executions (default: 500ms)
splash timer.amount string Amount of times the timer loops before sleep is invoked (default:

10 times)

badge mpr121.base.0 uint16 Touch baseline for the A button
badge mpr121.base.1 uint16 Touch baseline for the B button
badge mpr121.base.2 uint16 Touch baseline for the START button
badge mpr121.base.3 uint16 Touch baseline for the SELECT button
badge mpr121.base.4 uint16 Touch baseline for the DOWN button
badge mpr121.base.5 uint16 Touch baseline for the RIGHT button
badge mpr121.base.6 uint16 Touch baseline for the UP button
badge mpr121.base.7 uint16 Touch baseline for the LEFT button