|
|
| Line 1: |
Line 1: |
| − | This page describes each of the officially supported APIs of the badge.team platform firmware.
| + | Moved to https://docs.badge.team/api-reference/ |
| − | 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.
| |
| − | | |
| − | {| class="wikitable"
| |
| − | ! 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.''
| |
| − | | |
| − | {| class="wikitable"
| |
| − | ! 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.
| |
| − | {| class="wikitable"
| |
| − | ! 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.
| |
| − | | |
| − | {| class="wikitable"
| |
| − | ! 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...
| |
| − | |}
| |
