About HTTP API

the open http api lets you fully control your busy bar using your own scripts, applications, or services in any programming language the http api is available over usb, wi fi, and the internet on this page, you’ll learn about the http api capabilities%section% docid\ h4whpextnlyjsr9plxsar authentication%section% docid\ h4whpextnlyjsr9plxsar http api reference%section% docid\ h4whpextnlyjsr9plxsar try the api from the http api reference%section% docid\ h4whpextnlyjsr9plxsar display an image and text using a python script%section% docid\ h4whpextnlyjsr9plxsar busylib libraries%section% docid\ h4whpextnlyjsr9plxsar capabilities timer control — control the busy and custom modes display control — render text and images on both displays, adjust brightness audio control — upload and play audio files, adjust volume real time updates — get display frames and busy bar state changes over websocket input simulation — emulate button presses and scroll wheel events file management — upload, organize, and delete files stored on the busy bar firmware updates — update firmware from a local file or over the internet wi fi and bluetooth — scan and connect the busy bar to wi fi networks, enable ble advertising, remove ble pairings, and check connection status busy account — link or unlink the busy bar with your account, get account info matter integration — connect the busy bar to your smart home system config — set the busy bar name, system time, time zone, and more system info — get busy bar status, power, and firmware details how it works the http api follows a client server architecture the busy bar acts as an http server , listening for incoming requests from an http client when the busy bar receives a request, it processes it and generates a response the http client can be any application capable of sending http requests, such as a smart home system, a script, a desktop or mobile application, or even a web browser for the simplest test, connect busy bar to your computer via usb and enter 10 0 4 20/api/status/firmware the browser will send an http request to your busy bar and display its response an http request url consists of base url , which depends on how busy bar is connected endpoint , which identifies the type of request to busy bar all available endpoints are listed in the http api reference base url the base url for http api requests depends on how your busy bar is connected connection method base url authentication usb http //10 0 4 20/api not required wi fi (lan) http //xx xx xx xx/api required internet https //api busy app/busybar required \ for wi fi connections \ to find your busy bar's ip address, go to \ settings → wi fi → \[your wi fi ap name] → view ip address \ authentication wi fi (lan) and internet connections require authentication for details, see authentication%section% docid\ h4whpextnlyjsr9plxsar wi fi access \ enable wi fi access to control busy bar over wi fi \ wi fi (lan) connections to busy bar are \ disabled by default for security reasons \ to enable wi fi access to busy bar connect your busy bar to a computer via usb open the busy bar local web interface in a web browser http //10 0 4 20 http //10 0 4 20 on the network tab, in the http api section, turn on http api access click set password and enable , and set a password from now on, your busy bar will ask for this password every time you log in to the web interface via wi fi you’ll also need to include this password in all http requests for authentication authentication authentication is how the device verifies that an incoming http api request was actually sent by its owner or someone the owner trusts without authentication, busy bar returns a 403 forbidden error in response to the request the authentication method depends on how you connect to busy bar via usb, wi fi, or the internet via usb a usb connection is considered a secure communication channel, so authentication is not used over usb you can send any http api requests to the device at its ip address 10 0 4 20 without authentication via wi fi (lan) http api requests over wi fi are authenticated using a password that is set in the local web interface wi fi access must be enabled first learn how to enable wi fi access docid\ h4whpextnlyjsr9plxsar include this password in the x api token header for every http request sent to the busy bar over wi fi here are a few examples curl x get \\ "http //\[busy bar ip address]/api/status" \\ h "accept application/json" \\ h "x api token \<your password>"const response = await fetch("http //\[busy bar ip address]/api/status", { headers { "accept" "application/json", "x api token" "\<your password>", }, }); import requests response = requests get( "http //\[busy bar ip address]/api/status", headers={ "accept" "application/json", "x api token" "\<your password>", }, ) via internet when connecting over the internet, requests are authenticated through an api token you can generate and manage tokens in your busy account learn how to manage api tokens docid 3auwybgy9fgu b8dnfm4h include your api token in the authorization header using the bearer authentication scheme for every http request sent to the busy bar over the internet here are a few examples curl x get \\ "https //api busy app/busybar/status" \\ h "accept application/json" \\ h "authorization bearer \<your api token>"const response = await fetch("https //api busy app/busybar/status", { headers { "accept" "application/json", "authorization" "bearer \<your api token>", }, }); import requests response = requests get( "https //api busy app/busybar/status", headers={ "accept" "application/json", "authorization" "bearer \<your api token>", }, ) http api reference http api reference https //api busy app/busybar/docs is an interactive page where you can browse all http api endpoints — view all supported api requests view the api schemas that describe the json objects used by the http api download the openapi yml file , which contains the http api specification in the openapi format test any api request expand the desired endpoint, click try it out , edit the request parameters or body if necessary, and then click execute how to open the http api reference you can open the http api reference in one of two ways \ option 1 \ from the busy bar local web interface open the following url in your web browser http //10 0 4 20/docs (when connected over usb) http //\<busy bar ip address>/docs (when connected over wi fi) alternatively, open the network tab in the local web interface and, in the http api section, click either over usb or over wi fi this opens the http api reference hosted directly on the busy bar it documents the version of the http api implemented in the device’s firmware when you test api requests from the reference page, they are sent directly to the busy bar over wi fi or usb \ option 2 \ public http api reference open the following url in your web browser https //api busy app/busybar/docs https //api busy app/busybar/docs in the page header, select your busy bar firmware version to view the corresponding http api reference when you test api requests from the public reference page, the requests are sent to your busy bar over the internet through our cloud service try the api from the http api reference you can send requests to your busy bar right from the http api reference in the example below, you’ll show text on the front screen and an image on the back screen \ step 1 \ authenticate (if needed) to try api requests, you may need to authenticate first, depending on how you access the http api reference over usb ( http //10 0 4 20/docs ) — no authentication needed, just send requests over wi fi ( http //\<busy bar ip address>/docs ) — click authorize and enter the password you set when enabling wi fi access docid\ h4whpextnlyjsr9plxsar over the internet ( api busy app/busybar/docs ) — click authorize and enter an api token docid 3auwybgy9fgu b8dnfm4h generated in your busy account when creating the token, select busy bar under access scope \ step 2 \ upload an image for the back screen \ for the back screen \ the file must be no larger than 255 kb you can download our example image try the endpoint that uploads an image in the assets group, expand \ post \ api/assets/upload and click try it out in the request body , click choose file and select your file click execute to upload the file to your busy bar the image is now in your busy bar’s memory to show it, continue to step 3 \ step 3 \ display text and an image on the busy bar screens scroll down to the \ post \ /busybar/display/draw endpoint expand the endpoint and click try it out (optional) edit the request body for example, change the text parameter to show a different text click execute your busy bar will show the text on the front screen and the uploaded image on the back screen display an image and text using a python script now let’s try controlling busy bar with your own code the python script below uses the http api to upload a small image and display it on the front screen together with a text message \ step 1 \ create the script file copy and paste the contents of this block into a file named test py and save it click here to expand the block with the script code #!/usr/bin/env python3 import argparse import requests app name = "hello demo" image file = "smile png" def make headers(auth type str, token str | none) → dict """build http headers for the selected authentication method """ headers = { "accept" "application/json", } if auth type == "usb" \# usb connection does not require authentication pass elif auth type == "wifi" if not token raise valueerror(" token is required when using auth wifi") headers\["x api token"] = token elif auth type == "cloud" if not token raise valueerror(" token is required when using auth cloud") headers\["authorization"] = f"bearer {token}" else raise valueerror(f"unknown authentication type {auth type}") return headers def upload image(base url str, auth type str, token str | none) url = ( f"{base url}/assets/upload" f"?application name={app name}" f"\&file={image file}" ) with open(image file, "rb") as f response = requests post( url, headers={ make headers(auth type, token), "content type" "application/octet stream", }, data=f, ) response raise for status() print("image uploaded ") def draw(base url str, auth type str, token str | none) url = f"{base url}/display/draw" payload = { "application name" app name, "elements" \[ { "id" "logo", "type" "image", "display" "front", "path" image file, "x" 0, "y" 0, }, { "id" "text", "type" "text", "display" "front", "text" "hello world!", "font" "extra large", "color" "#00ff00ff", "width" 54, "align" "top left", "scroll rate" 800, "scroll start delay" 1000, "scroll repeat delay" 2500, "x" 18, "y" 1, }, ], } response = requests post( url, headers={ make headers(auth type, token), "content type" "application/json", }, json=payload, ) response raise for status() print("display updated ") def main() parser = argparse argumentparser( description="display an image and text on busy bar " ) parser add argument( "base url", help=( "base url, including the api path prefix " "(e g http //10 0 4 20/api or https //api busy app/busybar)" ), ) parser add argument( " auth", choices=\["usb", "wifi", "cloud"], default="usb", help="authentication method (default usb)", ) parser add argument( " token", help="wi fi password or cloud api token", ) args = parser parse args() base url = args base url rstrip("/") upload image(base url, args auth, args token) draw(base url, args auth, args token) print("done ") if name == " main " main() \ step 2 \ download the image file save a 16x16 px png image named smile png in the same folder as test py you can download our example image ( ) \ step 3 \ set up the python environment the script requires \ python 3 10 or newer \ if python is not installed, download it from python org https //www python org/downloads/ open a terminal in the folder with the script and run python3 m venv venv source venv/bin/activate python3 m pip install requests this creates an isolated python virtual environment and installs the requests library that the script depends on \ step 4 \ run the script run the command for your connection type for wi fi, use the password you set when enabling wi fi access docid\ h4whpextnlyjsr9plxsar for an internet connection, use an api token docid 3auwybgy9fgu b8dnfm4h from your busy account usb python3 test py http //10 0 4 20/api wi fi (lan) for wi fi, use the password you set when enabling wi fi access docid\ h4whpextnlyjsr9plxsar python3 test py http //\<busy bar ip address>/api auth wifi token "\<your password>" internet for an internet connection, use an api token docid 3auwybgy9fgu b8dnfm4h from your busy account when creating the token, select busy bar under access scope python3 test py https //api busy app/busybar auth cloud token \<your api token> if everything works, the terminal will print image uploaded , display updated , and done , and your busy bar will show the image and the "hello world!" text on the front screen busylib libraries busylib is the official open source library for building applications that interact with busy bar it provides ready to use python and typescript apis that abstract the underlying http api advantages simplifies development by handling http request construction and response processing developers can work with a simple, high level api without worrying about the underlying http protocol implements websocket communication for receiving real time events from the busy bar and for screen streaming supports both synchronous and asynchronous interaction with busy bar, making it suitable for both simple applications and concurrent workflows get busylib we maintain busylib for python and typescript typescript library https //go busy app/typescript library python library https //pypi org/project/busylib/ \ community net library \ there’s also a net client for the busy bar http api, built and maintained by the community busybar net https //busybar dotnet homotechsual dev/