Ctrlk
ForumsBlogPricingContactLoginSignup

v10.2.0 (DEPRECATED)

Welcome to the balena python SDK documentation. This document aims to describe all the functions supported by the SDK, as well as showing examples of their expected usage.

Install the Balena SDK:

From Pip:

pip install balena-sdk

From Source (In case, you want to test a development branch):

https://github.com/balena-io/balena-sdk-python

Getting started:

>>> from balena import Balena
>>> balena = Balena()
>>> credentials = {'username':<your email>, 'password':<your password>}
>>> balena.auth.login(**credentials)
...

If you feel something is missing, not clear or could be improved, please don't hesitate to open an issue in GitHub, we'll be happy to help.

Table of Contents

Models

This module implements all models for balena python SDK.

Application

This class implements application model for balena python SDK.

The returned objects properties are __metadata, actor, app_name, application_type, commit, depends_on__application, device_type, id, is_accessible_by_support_until__date, should_track_latest_release, slug, user.

Function: create(name, device_type, organization, app_type)

Create an application. This function only works if you log in using credentials or Auth Token.

Args:

Returns:

Raises:

Examples:

Function: disable_device_urls(app_id)

Disable device urls for all devices that belong to an application.

Args:

Returns:

Examples:

Function: disable_rolling_updates(app_id)

Disable Rolling update on application.

Args:

Returns:

Raises:

Examples:

Function: enable_device_urls(app_id)

Enable device urls for all devices that belong to an application

Args:

Returns:

Examples:

Function: enable_rolling_updates(app_id)

Enable Rolling update on application.

Args:

Returns:

Raises:

Examples:

Function: generate_provisioning_key(app_id)

Generate a device provisioning key for a specific application.

Args:

Returns:

Examples:

Function: get(name)

Get a single application.

Args:

Returns:

Raises:

Examples:

Function: get_all()

Get all applications (including collaborator applications).

Returns:

Examples:

Function: get_all_with_device_service_details(expand_release)

Get all applications (including collaborator applications) along with associated services' essential details.

Args:

Returns:

Function: get_by_id(app_id)

Get a single application by application id.

Args:

Returns:

Raises:

Examples:

Function: get_by_owner(name, owner)

Get a single application using the appname and the handle of the owning organization.

Args:

Returns:

Raises:

Examples:

Function: get_config(app_id, version)

Download application config.json.

Args:

Returns:

Raises:

Function: get_dashboard_url(app_id)

Get Dashboard URL for a specific application.

Args:

Raises:

Returns:

Examples:

Function: get_target_release_hash(app_id)

Get the hash of the current release for a specific application.

Args:

Returns:

Examples:

Function: get_with_device_service_details(name, expand_release)

Get a single application along with its associated services' essential details.

Args:

Returns:

Raises:

Examples:

Function: grant_support_access(app_id, expiry_timestamp)

Grant support access to an application until a specified time.

Args:

Returns:

Examples:

Function: has(name)

Check if an application exists.

Args:

Returns:

Examples:

Function: has_any()

Check if the user has any applications.

Returns:

Examples:

Function: is_tracking_latest_release(app_id)

Get whether the application is up to date and is tracking the latest release for updates.

Args:

Returns:

Examples:

Function: remove(name)

Remove application. This function only works if you log in using credentials or Auth Token.

Args:

Examples:

Function: restart(name)

Restart application. This function only works if you log in using credentials or Auth Token.

Args:

Raises:

Examples:

Function: revoke_support_access(app_id)

Revoke support access to an application.

Args:

Returns:

Examples:

Function: set_to_release(app_id, full_release_hash)

Set an application to a specific commit.

Args:

Returns:

Examples:

Function: track_latest_release(app_id)

Configure a specific application to track the latest available release.

Args:

Examples:

Function: will_track_new_releases(app_id)

Get whether the application is configured to receive updates whenever a new release is available.

Args:

Returns:

Examples:

ApiKey

This class implements user API key model for balena python SDK.

Function: create_api_key(name, description)

This function registers a new api key for the current user with the name given.

Args:

Returns:

Examples:

Function: get_all()

This function gets all API keys.

Returns:

Examples:

Function: revoke(id)

This function revokes an API key.

Args:

Examples:

Function: update(id, api_key_info)

This function updates details of an API key.

Args:

Examples:

Config

This class implements configuration model for balena python SDK.

Attributes:

Function: get_all()

Get all configuration.

Returns:

Examples:

Function: get_device_types()

Get device types configuration.

Returns:

Examples:

ConfigVariable

This class is a wrapper for config variable models.

ApplicationConfigVariable

This class implements application config variable model for balena python SDK.

Function: create(app_id, config_var_name, value)

Create an application config variable.

Args:

Returns:

Examples:

Function: get_all(app_id)

Get all application config variables belong to an application.

Args:

Returns:

Examples:

Function: remove(var_id)

Remove a application config environment variable.

Args:

Examples:

Function: update(var_id, value)

Update an application config variable.

Args:

Examples:

DeviceConfigVariable

This class implements device config variable model for balena python SDK.

Function: create(uuid, config_var_name, value)

Create a device config variable.

Args:

Returns:

Examples:

Function: get_all(uuid)

Get all device config variables belong to a device.

Args:

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all device config variables by application.

Args:

Returns:

Examples:

Function: remove(var_id)

Remove a device config environment variable.

Args:

Examples:

Function: update(var_id, value)

Update a device config variable.

Args:

Examples:

Device

This class implements device model for balena python SDK.

Due to API changes, the returned Device object schema has changed. Here are the formats of the old and new returned objects.

The old returned object's properties: __metadata, actor, application, build, commit, created_at, custom_latitude, custom_longitude, device, device_type, download_progress, id, ip_address, is_connected_to_vpn, is_online, is_web_accessible, last_connectivity_event, last_vpn_event, latitude, local_id, location, lock_expiry_date, logs_channel, longitude, name, note, os_variant, os_version, provisioning_progress, provisioning_state, public_address, service_instance, status, supervisor_release, supervisor_version, support_expiry_date, user, uuid, vpn_address.

The new returned object's properties (since python SDK v2.0.0): __metadata, actor, belongs_to__application, belongs_to__user, created_at, custom_latitude, custom_longitude, device_type, download_progress, id, ip_address, is_accessible_by_support_until__date, is_connected_to_vpn, is_locked_until__date, is_managed_by__device, is_managed_by__service_instance, is_on__commit, is_online, is_web_accessible, last_connectivity_event, last_vpn_event, latitude, local_id, location, logs_channel, longitude, name, note, os_variant, os_version, provisioning_progress, provisioning_state, public_address, should_be_managed_by__supervisor_release, should_be_running__build, status, supervisor_version, uuid, vpn_address.

Function: disable_device_url(uuid)

Disable device url for a device.

Args:

Raises:

Examples:

Function: disable_local_mode(uuid)

Disable local mode.

Args:

Returns:

Examples:

Function: disable_lock_override(uuid)

Disable lock override.

Args:

Raises:

Function: enable_device_url(uuid)

Enable device url for a device.

Args:

Raises:

Examples:

Function: enable_local_mode(uuid)

Enable local mode.

Args:

Returns:

Examples:

Raises:

Function: enable_lock_override(uuid)

Enable lock override.

Args:

Raises:

Function: generate_device_key(uuid)

Generate a device key.

Args:

Raises:

Examples:

Function: generate_uuid()

Generate a random device UUID.

Returns:

Examples:

Function: get(uuid)

Get a single device by device uuid.

Args:

Returns:

Raises:

Examples:

Function: get_all()

Get all devices.

Returns:

Examples:

Function: get_all_by_application(name)

Get devices by application name.

Args:

Returns:

Examples:

Function: get_all_by_application_id(appid)

Get devices by application name.

Args:

Returns:

Examples:

Function: get_application_name(uuid)

Get application name by device uuid.

Args:

Returns:

Raises:

Function: get_by_name(name)

Get devices by device name.

Args:

Returns:

Examples:

Function: get_dashboard_url(uuid)

Get balena Dashboard URL for a specific device.

Args:

Examples:

Function: get_device_slug(device_type_name)

Get device slug.

Args:

Returns:

Raises:

Examples:

Function: get_device_url(uuid)

Get a device url for a device.

Args:

Raises:

Examples:

Function: get_display_name(device_type_slug)

Get display name for a device.

Args:

Returns:

Raises:

Examples:

Function: get_local_ip_address(uuid)

Get the local IP addresses of a device.

Args:

Returns:

Raises:

Function: get_local_mode_support(uuid)

Returns whether local mode is supported along with a message describing the reason why local mode is not supported.

Args:

Returns:

Examples:

Function: get_mac_address(uuid)

Get the MAC addresses of a device.

Args:

Returns:

Raises:

Function: get_manifest_by_application(app_name)

Get a device manifest by application name.

Args:

Returns:

Function: get_manifest_by_slug(slug)

Get a device manifest by slug.

Args:

Returns:

Raises:

Function: get_metrics(uuid)

Get the metrics related information for a device.

Args:

Returns:

Raises:

Function: get_name(uuid)

Get device name by device uuid.

Args:

Returns:

Raises:

Function: get_os_update_status(uuid)

Args:

Returns:

Examples:

Function: get_status(uuid)

Get the status of a device.

Args:

Raises:

Returns:

Examples:

Function: get_supervisor_state(uuid)

Get the supervisor state on a device

Args:

Returns:

Examples:

Function: get_supervisor_target_state(uuid)

Get the supervisor target state on a device

Args:

Returns:

Examples:

Function: get_supported_device_types()

Get device slug.

Returns:

Function: get_with_service_details(uuid, expand_release)

Get a single device along with its associated services' essential details.

Args:

Returns:

Raises:

Examples:

Function: grant_support_access(uuid, expiry_timestamp)

Grant support access to a device until a specified time.

Args:

Returns:

Examples:

Function: has(uuid)

Check if a device exists.

Args:

Returns:

Function: has_device_url(uuid)

Check if a device is web accessible with device urls

Args:

Raises:

Examples:

Function: has_lock_override(uuid)

Check if a device has the lock override enabled.

Args:

Returns:

Raises:

Function: identify(uuid)

Identify device. This function only works if you log in using credentials or Auth Token.

Args:

Examples:

Function: is_in_local_mode(uuid)

Check if local mode is enabled on the device.

Args:

Returns:

Examples:

Function: is_online(uuid)

Check if a device is online.

Args:

Returns:

Raises:

Function: is_tracking_application_release(uuid)

Get whether the device is configured to track the current application release.

Args:

Returns:

Raises:

Function: move(uuid, app_name)

Move a device to another application.

Args:

Raises:

Examples:

Function: note(uuid, note)

Note a device.

Args:

Raises:

Examples:

Function: register(app_id, uuid)

Register a new device with a balena application. This function only works if you log in using credentials or Auth Token.

Args:

Returns:

Examples:

Function: remove(uuid)

Remove a device. This function only works if you log in using credentials or Auth Token.

Args:

Function: rename(uuid, new_name)

Rename a device.

Args:

Raises:

Examples:

Function: restart(uuid)

Restart a user application container on device. This function only works if you log in using credentials or Auth Token.

Args:

Raises:

Examples:

Function: revoke_support_access(uuid)

Revoke support access to a device.

Args:

Returns:

Examples:

Function: set_custom_location(uuid, location)

Set a custom location for a device.

Args:

Raises:

Examples:

Function: set_to_release(uuid, commit_id)

Set device to a specific release. Set an empty commit_id will restore rolling releases to the device.

Args:

Returns:

Examples:

Function: set_to_release_by_id(uuid, release_id)

Set device to a specific release by release id (please notice that release id is not the commit hash on balena dashboard). Remove release_id will restore rolling releases to the device.

Args:

Returns:

Examples:

Function: start_os_update(uuid, target_os_version)

Start an OS update on a device.

Args:

Returns:

Raises:

Examples:

Function: track_application_release(uuid)

Configure a specific device to track the current application release.

Args:

Raises:

Function: unset_custom_location(uuid)

clear custom location for a device.

Args:

Raises:

Examples:

DeviceOs

This class implements device os model for balena python SDK.

Function: download(raw)

Download an OS image. This function only works if you log in using credentials or Auth Token.

Args:

Returns:

Notes:

Examples:

Function: download_unconfigured_image(device_type, version, raw)

Download an unconfigured OS image.

Args:

Returns:

Notes:

Examples:

Function: get_config(app_id, options)

Get an application config.json.

Args:

Returns:

Function: get_device_os_semver_with_variant(os_version, os_variant)

Get current device os semver with variant.

Args:

Examples:

Function: get_supported_versions(device_type)

Get OS supported versions.

Args:

Returns:

Function: is_architecture_compatible_with(os_architecture, application_architecture)

Returns whether the specified OS architecture is compatible with the target architecture.

Args:

Returns:

Function: parse_params()

Validate parameters for downloading device OS image.

Args:

Returns:

Raises:

EnvironmentVariable

This class is a wrapper for environment variable models.

ApplicationEnvVariable

This class implements application environment variable model for balena python SDK.

Attributes:

Function: create(app_id, env_var_name, value)

Create an environment variable for application.

Args:

Returns:

Examples:

Function: get_all(app_id)

Get all environment variables by application.

Args:

Returns:

Examples:

Function: is_system_variable(variable)

Check if a variable is system specific.

Args:

Returns:

Examples:

Function: remove(var_id)

Remove application environment variable.

Args:

Examples:

Function: update(var_id, value)

Update an environment variable value for application.

Args:

Examples:

ServiceEnvVariable

This class implements service environment variable model for balena python SDK.

Function: create(app_id, service_name, env_var_name, value)

Create a service environment variable for application.

Args:

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all service environment variables by application.

Args:

Returns:

Examples:

Function: remove(var_id)

Remove service environment variable.

Args:

Examples:

Function: update(var_id, value)

Update a service environment variable value for application.

Args:

Examples:

DeviceEnvVariable

This class implements device environment variable model for balena python SDK.

Function: create(uuid, env_var_name, value)

Create a device environment variable.

Args:

Returns:

Examples:

Function: get_all(uuid)

Get all device environment variables.

Args:

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all device environment variables for an application.

Args:

Returns:

Examples:

Function: remove(var_id)

Remove a device environment variable.

Args:

Examples:

Function: update(var_id, value)

Update a device environment variable.

Args:

Examples:

DeviceServiceEnvVariable

This class implements device service variable model for balena python SDK.

Function: create(uuid, service_name, env_var_name, value)

Create a device service environment variable.

Args:

Returns:

Examples:

Function: get_all(uuid)

Get all device service environment variables belong to a device.

Args:

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all device service environment variables belong to an application.

Args:

Returns:

Examples:

Function: remove(var_id)

Remove a device service environment variable.

Args:

Examples:

Function: update(var_id, value)

Update a device service environment variable.

Args:

Examples:

Image

This class implements image model for balena python SDK.

Function: get(id)

Get a specific image.

Args:

Returns:

Raises:

Function: get_log(id)

Get the build log from an image.

Args:

Returns:

Raises:

Organization

This class implements organization model for balena python SDK.

Function: create(name, handle)

Creates a new organization.

Args:

Returns:

Examples:

Function: get(org_id)

Get a single organization by id.

Args:

Returns:

Raises:

Examples:

Function: get_all()

Get all organizations.

Returns:

Examples:

Function: get_by_handle(handle)

Get a single organization by handle.

Args:

Returns:

Raises:

Examples:

Function: remove(org_id)

Remove an organization.

Args:

Returns:

Examples:

Release

This class implements release model for balena python SDK.

Function: create_from_url(app_id, url, flatten_tarball)

Create a new release built from the source in the provided url.

Args:

Returns:

Raises:

Function: get(commit_or_id)

Get a specific release.

Args:

Returns:

Raises:

Function: get_all_by_application(app_id)

Get all releases from an application.

Args:

Returns:

Function: get_latest_by_application(app_id)

Get the latest successful release for an application.

Args:

Returns:

Function: get_with_image_details(commit_or_id)

Get a specific release with the details of the images built.

Args:

Returns:

Raises:

Service

This class implements service model for balena python SDK.

Function: get_all_by_application(app_id)

Get all services from an application.

Args:

Returns:

Tag

This class is a wrapper for Tag models.

DeviceTag

This class implements device tag model for balena python SDK.

Function: get_all()

Get all device tags.

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all device tags for an application.

Args:

Returns:

Examples:

Function: get_all_by_device(uuid)

Get all device tags for a device.

Args:

Returns:

Raises:

Examples:

Function: remove(uuid, tag_key)

Remove a device tag.

Args:

Raises:

Examples:

Function: set(uuid, tag_key, value)

Set a device tag (update tag value if it exists).

Args:

Returns:

Raises:

Examples:

ApplicationTag

This class implements application tag model for balena python SDK.

Function: get_all()

Get all application tags.

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all application tags for an application.

Args:

Returns:

Examples:

Function: remove(app_id, tag_key)

Remove an application tag.

Args:

Examples:

Function: set(app_id, tag_key, value)

Set an application tag (update tag value if it exists).

Args:

Returns:

Examples:

ReleaseTag

This class implements release tag model for balena python SDK.

Function: get_all()

Get all release tags.

Returns:

Examples:

Function: get_all_by_application(app_id)

Get all release tags for an application.

Args:

Returns:

Examples:

Function: get_all_by_release(commit_or_id)

Get all release tags for a release.

Args:

Returns:

Examples:

Function: remove(commit_or_id, tag_key)

Remove a release tag.

Args:

Examples:

Function: set(commit_or_id, tag_key, value)

Set a release tag (update tag value if it exists).

Args:

Returns:

Examples:

Key

This class implements ssh key model for balena python SDK.

Function: create(title, key)

Create a ssh key. This function only works if you log in using credentials or Auth Token.

Args:

Returns:

Function: get(id)

Get a single ssh key.

Args:

Returns:

Raises:

Function: get_all()

Get all ssh keys.

Returns:

Function: remove(id)

Remove a ssh key. This function only works if you log in using credentials or Auth Token.

Args:

Supervisor

This class implements supervisor model for balena python SDK.

Attributes:

Function: blink(device_uuid, app_id)

Start a blink pattern on a LED for 15 seconds. This is the same with balena.models.device.identify(). No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Raises:

Examples:

Function: force_api_endpoint(endpoint)

Force all API commands to a specific endpoint.

Args:

Raises:

Function: get_application_info(app_id, device_uuid)

Deprecated Return information about the application running on the device. This function requires supervisor v1.8 or higher. No need to set device_uuid if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: get_device_state(app_id, device_uuid)

Return the current device state, as reported to the balena API and with some extra fields added to allow control over pending/locked updates. This function requires supervisor v1.6 or higher. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: ping(device_uuid, app_id)

Check that the supervisor is alive and well. No need to set device uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: purge(app_id, device_uuid)

Clears the user application's /data folder. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: reboot(device_uuid, app_id, force)

Reboot the device. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: regenerate_supervisor_api_key(app_id, device_uuid)

Invalidate the current SUPERVISOR_API_KEY and generates a new one. The application will be restarted on the next update cycle to update the API key environment variable. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: restart(app_id, device_uuid)

Restart user application container. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: restart_service(device_uuid, image_id)

Restart a service on device.

Args:

Examples:

Function: shutdown(device_uuid, app_id, force)

Shut down the device. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: start_application(app_id, device_uuid)

Deprecated Starts a user application container, usually after it has been stopped with stop_application(). This function requires supervisor v1.8 or higher. No need to set device_uuid if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: start_service(device_uuid, image_id)

Start a service on device.

Args:

Examples:

Function: stop_application(app_id, device_uuid)

Deprecated Temporarily stops a user application container. Application container will not be removed after invoking this function and a reboot or supervisor restart will cause the container to start again. This function requires supervisor v1.8 or higher. No need to set device_uuid if command is sent to the API on device.

Args:

Returns:

Raises:

Examples:

Function: stop_service(device_uuid, image_id)

Stop a service on device.

Args:

Examples:

Function: update(device_uuid, app_id, force)

Triggers an update check on the supervisor. Optionally, forces an update when updates are locked. No need to set device_uuid and app_id if command is sent to the API on device.

Args:

Raises:

Examples:

Auth

This class implements all authentication functions for balena python SDK.

Function: authenticate()

This function authenticates provided credentials information. You should use Auth.login when possible, as it takes care of saving the Auth Token and username as well.

Args:

Returns:

Raises:

Examples:

Function: get_email()

This function retrieves current logged in user's get_email

Returns:

Raises:

Examples:

Function: get_token()

This function retrieves Auth Token.

Returns:

Raises:

Examples:

Function: get_user_id()

This function retrieves current logged in user's id.

Returns:

Raises:

Examples:

Function: is_logged_in()

This function checks if you're logged in

Returns:

Examples:

Function: log_out()

This function is used for logging out from balena.

Returns:

Examples:

Function: login()

This function is used for logging into balena using email and password.

Args:

Returns:

Raises:

Examples:

Function: login_with_token(token)

This function is used for logging into balena using Auth Token. Auth Token can be found in Preferences section on balena Dashboard.

Args:

Returns:

Raises:

Examples:

Function: register()

This function is used for registering to balena.

Args:

Returns:

Raises:

Examples:

Function: who_am_i()

This function retrieves username of logged in user.

Returns:

Raises:

Examples:

Logs

This class implements functions that allow processing logs from device.

Function: history(uuid, count)

Get device logs history.

Args:

Function: subscribe(uuid, callback, error, count)

Subscribe to device logs.

Args:

Returns:

Function: unsubscribe(uuid)

Unsubscribe from device logs for a specific device.

Args:

Function: unsubscribe_all()

Unsubscribe all subscribed devices.

Settings

This class handles settings for balena python SDK.

Attributes:

Function: get(key)

Get a setting value.

Args:

Returns:

Raises:

Examples:

Function: get_all()

Get all settings.

Returns:

Examples:

Function: has(key)

Check if a setting exists.

Args:

Returns:

Examples:

Function: remove(key)

Remove a setting.

Args:

Returns:

Examples:

Function: set(key, value)

Set value for a setting.

Args:

Examples:

TwoFactorAuth

This class implements basic 2FA functionalities for balena python SDK.

Function: challenge(code)

Challenge two-factor authentication. If your account has two-factor authentication enabled and logging in using credentials, you need to pass two-factor authentication before being allowed to use other functions.

Args:

Examples:

Function: generate_code(secret)

Generate two-factor authentication code.

Args:

Returns:

Examples:

Function: get_otpauth_secret()

Retrieve one time password authentication secret string. This function only works if you disable two-factor authentication or log in using Auth Token from dashboard.

Returns:

Examples:

Function: is_enabled()

Check if two-factor authentication is enabled.

Returns:

Examples:

Function: is_passed()

Check if two-factor authentication challenge was passed.

Returns:

Examples:

Previousv14.5.0 (DEPRECATED)NextBalena SDK deprecation policy

Last updated

Was this helpful?