SHA2017Badge/Splash
Contents
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 “service.py” 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.
API
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 |
