Skip to main content
Booster Docs

API Overview and Usage

The booster_agent_framework library provides developers with a series of key classes, covering the core capabilities from UI construction to robot control. This document introduces the composition and key features of the API.

Module Breakdown​

  • Agent base class: runtime configuration, lifecycle callbacks, and component manager access.
  • UI component system: component declaration, component updates, page switching, and Toast notifications.
  • Parameter system: parameter read and write, validation, and parameter change callbacks.
  • Joystick and shortcuts: key-combination descriptions and shortcut metadata lookup.
  • Robot states: access to robot modes and other runtime state values.
  • Storage management: file read and write operations under the Agent configuration directory.
  • Localization and logging: multilingual strings and logging.

API Version Notes​

API Level is the version identifier of system capabilities. Its value corresponds one-to-one with the firmware version, calculated as follows:

API Level = major version × 10000 + minor version × 100 + revision

For example, firmware 1.8.1 corresponds to API Level 1×10000 + 8×100 + 1 = 10801. During firmware evolution, some APIs are added or deprecated, and such changes are marked by the API Level.

Get the current system API Level:

get_sys_api_level() -> int

Call this method to determine which APIs are available in the runtime environment and handle compatibility accordingly.

In Booster Studio, hold Ctrl and click any Agent API to view its since (available since this API Level) and deprecated (deprecated since this API Level) information.

API Level and Booster Studio Version Mapping:

API Level

Booster Studio Version

10700

< 1.13.0

10800

>= 1.13.0

Threading Model​

The framework API uses a callback model similar to Android event callbacks. All user callbacks are executed serially on the main thread, rather than on separate worker threads. The framework waits for callbacks that need to return a result to finish; therefore, a single long-running callback can block subsequent Python callbacks, delay the response to the current request, and cause the frontend App to appear unresponsive.

Notes:

  • Callbacks should be returned as quickly as possible. Do not perform long-running IO, sleep, join, or future wait inside a callback, and do not wait for another Python callback, a subsequent App operation, or a robot state event to complete the current callback.

Recommended pattern for long-running work:

  • Run long-running tasks in your own background thread, process, or external service.
  • The callback itself should only validate parameters, record state, start the task, and return quickly. After the task completes, report the result through state publishing, component updates, Toast messages, events, or a later query.
  • If synchronous waiting is absolutely necessary, use a short and explicit timeout, and make sure it does not cause a deadlock (i.e., the awaited result must not depend on the current callback returning).