API

From Badge team
Revision as of 16:17, 23 August 2019 by SynQ (talk | contribs)
Jump to navigation Jump to search

This page describes each of the officially supported APIs of the badge.team platform firmware. Some would call this page the 'API reference'.

System

The system API allows you to control basic features your app needs to provide a smooth experience to the user.

Command Parameters Description
reboot - Reboot the badge into the currently running app
sleep [duration], [status] Start sleeping forever or for the provided duration (in seconds).

By defaut the function shows the fact that the badge is sleeping on the serial console, this can be disabled by setting the status argument to False.

start app, [status] Start an app. Optionally shows that an app is being started on the screen and in the serial console, for this to happen the status variable must be set to True.
home [status] Start the splash screen / default application. To show a message to the user set the optional status flag to True.
launcher [status] Start the application launcher. To show a message to the user set the optional status flag to True.
shell [status] Start a raw Python REPL prompt. To show a message to the user set the optional status flag to True.
ota [status] Initiate an Over-The-Air update session. Does NOT check if a newer firmware is available.

To prevent hijacking other peoples badges it is NOT possible to provide a different update server or URL at this time.

serialWarning - Show a message telling the user that the currently running app can only be controlled over the USB-serial connection.
crashedWarning - Show a message telling the user that the currently running app has crashed.
isColdBoot - Returns True if the badge was started from RESET state. This function will only ever return true if the currently runing app was set as the default app.
isWakeup [timer], [button], [infrared], [ulp] Returns True if the badge was started from a WARM state. Normally this can be any warm state, however by setting the parameters specific wake reasons can be selected or ruled-out.
currentApp - Returns the name of the currently running app.

Display

The display API allows you to control the display of your badge.

Note: This API is still under active development and may change at any time. Not all functions are usable at the moment. The functions marked with DO NOT USE do not work in the currently provided firmware version.

Command Parameters Description
flush [flags] Flush the contents of the framebuffer to the display.

Optionally you may provide flags (see the table down below)

size [window] Get the size (width, height) of the framebuffer or a window as a tuple
width [window] Get the width of the framebuffer or a window as an integer
height [window] Get the height of the framebuffer or a window as an integer
orientation [window], [angle] Get or set the orientation of the framebuffer or a window
getPixel [window], x, y Get the color of a pixel in the framebuffer or a window
drawRaw [window], x, y, width, height, data Copy a raw bytes buffer directly to the framebuffer or the current frame of a window.

The length of the bytes buffer must match the formula width*height*(bitsPerPixel//8). This is a direct copy: color format (bitsPerPixel) must match the specific display of the badge this command is used on.

drawPixel [window], x, y, color Draw a pixel in the framebuffer or a window
drawFill [window], color Fill the framebuffer or a window
drawLine [window], x0, y0, x1, y1, color Draw a line from (x0, y0) to (x1, y1)
drawRect [window], x, y, width, height, color Draw a rectangle at (x, y) with size (width, height)
drawCircle [window], x0, y0, radius, a0, a1, fill, color Draw a circle with center point (x0, y0) with the provided radius from angle a0 to angle a1, optionally filled (boolean)
drawText [window], x, y, text, [color], [font], [x-scale], [y-scale] Draw text at (x, y) with a certain color and font. Can be scaled (drawn with rects instead of pixels) in both the x and y direction
drawPng [window], x, y, [data or filename] Draw a PNG image at (x, y) from either a bytes buffer or a file
getTextWidth text, [font] Get the width a string would take if drawn with a certain font
getTextHeight text, [font] Get the height a string would take if drawn with a certain font
pngInfo [data or filename] Get information about a PNG image
windowCreate name, width, height
windowRemove name
windowMove name, x, y
windowResize name, width, height
windowVisibility name, [visible]
windowShow name
windowHide name
windowFocus name
windowList -
windowLoop *DO NOT USE*
frameAdd *DO NOT USE*
frameRemove *DO NOT USE*
frameStep *DO NOT USE*
frameSeek *DO NOT USE*
frameCurrent *DO NOT USE*
frameCount *DO NOT USE*

WiFi

The wifi API allows you to connect to WiFi networks.

Command Parameters Description
connect [ssid], [password] Connect to a WiFi network.

By default the stored credentials are used, but you can optionally provide the SSID (and password) of the network to connect to.

disconnect - Disconnect from the WiFi network.
status - Returns True if connected and False if not connected.
wait [timeout] Wait until a connection with the WiFi network has been made or until the timeout time is reached.

Timeout is in seconds but may be provided in 10ths of seconds. If no timeout is provided the default timeout is used. Returns True if connected after waiting and False if a connection could not be made before the timeout.

ntp [only-if-needed], [server] Synchronize the Real-Time-Clock with the network. Normally the synchronisation is only started when the system clock has not yet been set since the last reset.

This can be overruled by setting the only-if-needed parameter to False. By default the "'pool.ntp.org" server pool is used.

Terminal

The term API allows you to make more advanced use of the serial console.

Command Parameters Description
goto x, y Move the cursor to (x, y)
home - Move the cursor to (1, 1)
clear - Clear the terminal
color [foreground], [backgrund], [style] Set the color used for writing to the terminal
header [clear], [text] Prints a header on the top of the screen. Optionally clears the screen.

You can include your own text to be added after the device name.

menu title, items, [selected], [text], [item-width] Shows a menu with a specified title and menu-items. The selected menu item can be set. If not set the first item will be selected by default.

Optionally a text can be provided which gets printed at the top of the menu screen. If the maximum string length of one of the menu options exceeds 32 characters a different length may be provided to make the menu options match in length. The fuction returns the location of the selected menu-item. This function is blocking.

prompt prompt, x, y, [buffer] Prompt for text to be entered by the user. The prompt will appear at (x, y) and before the prompt the prompt text will appear.

If a buffer is provided the text buffer will contain the provided value. This function is blocking.

setPowerManagement pointer to the power-management task By providing a pointer to the power-management task running in your app this function will reset the timer to 5 minutes each time the user changes his selection in the menu shown by the menu() function.

This was mainly intended as an internal function and a more refined version will probably be defined somewhere in the future...