Returns the application running on the device. The app is a map that contains the following:

• app_id: The id of the app as per the balenaCloud API.
• commit: Application commit that is running.
• image_id: The docker image of the current application build.
• container_id: ID of the docker container of the running app.
• env: A key-value store of the app's environment variables.

This is only supported on single-container devices, and will return an error on devices running multiple containers.

Request a device identification by blinking the device's LED for 15 seconds.

Example

iex> V1.blink()
:ok

Used internally to check whether the supervisor is running correctly, according to some heuristics that help determine whether the internal components, application updates and reporting to the balenaCloud API are functioning.

Responds with an true response if the supervisor is healthy, or false if something is not working correctly.

This endpoint allows reading some configuration values for the host OS, previously set with host_config/1. Currently it supports proxy and hostname configuration.

This endpoint allows setting some configuration values for the host OS. Currently it supports proxy and hostname configuration.

For proxy configuration, balenaOS 2.0.7 and higher provides a transparent proxy redirector (redsocks) that makes all connections be routed to a SOCKS or HTTP proxy. This endpoint allows user applications to modify these proxy settings at runtime.

See PATCH /v1/device/host-config.

Clears the user application's /data folder.

Example

iex> V1.purge(1)
:ok

Reboots the device. This will first try to stop applications, and fail if there is an update lock.

Example

iex> V1.reboot()
:ok

Reboots the device. This will first try to stop applications, and fail if there is an update lock. An optional "force" parameter in the body overrides the lock when true (and the lock can also be overridden from the dashboard).

Example

iex> V1.reboot(true)
:ok

Invalidates the current BALENA_SUPERVISOR_API_KEY and generates a new one. Responds with the new API key, but the application will be restarted on the next update cycle to update the API key environment variable.

Example

iex> V1.regenerate_api_key()
{:ok, "d7bf0ab2665bb3ddb0da043727974daa46d6cfcb8c92fd068a852969576145"}

Restarts a user application container

Example

iex> V1.restart(1)
:ok

Dangerous. Shuts down the device. This will first try to stop applications, and fail if there is an update lock.

Example

iex> V1.shutdown()
:ok

Dangerous. Shuts down the device. This will first try to stop applications, and fail if there is an update lock. An optional "force" parameter in the body overrides the lock when true (and the lock can also be overridden from the dashboard).

Example

iex> V1.shutdown(true)
:ok

Starts a user application container, usually after it has been stopped with stop_app/2.

This is only supported on single-container devices, and will return :error on devices running multiple containers.

When successful, responds with :ok and the id of the started container.

Returns the current device state, as reported to the balenaCloud API and with some extra fields added to allow control over pending/locked updates.

The state is a map that contains some or all of the following:

• api_port: Port on which the supervisor is listening.
• commit: Hash of the current commit of the application that is running.
• ip_address: Space-separated list of IP addresses of the device.
• status: Status of the device regarding the app, as a string, i.e. "Stopping", "Starting", "Downloading", "Installing", "Idle".
• download_progress: Amount of the application image that has been downloaded, expressed as a percentage. If the update has already been downloaded, this will be null.
• os_version: Version of the host OS running on the device.
• supervisor_version: Version of the supervisor running on the device.
• update_pending: This one is not reported to the balenaCloud API. It's a boolean that will be true if the supervisor has detected there is a pending update.
• update_downloaded: Not reported to the balenaCloud API either. Boolean that will be true if a pending update has already been downloaded.
• update_failed: Not reported to the balenaCloud API. Boolean that will be true if the supervisor has tried to apply a pending update but failed (i.e. if the app was locked, there was a network failure or anything else went wrong).

Other attributes may be added in the future, and some may be missing or null if they haven't been set yet.

Example

  iex> V1.state()
  {:ok,
    %{
      "api_port" => 48484,
      "commit" => "localrelease",
      "download_progress" => nil,
      "ip_address" => "192.168.56.101",
      "os_version" => "balenaOS 2.44.0+rev1",
      "status" => "Idle",
      "supervisor_version" => "10.3.7",
      "update_downloaded" => false,
      "update_failed" => false,
      "update_pending" => false
    }}

Temporarily stops a user application container. A reboot or supervisor restart will cause the container to start again. The container is not removed with this endpoint.

This is only supported on single-container devices, and will fail on devices running multiple containers.

Returns an ok tuple with the ID of the stopped container.

Temporarily stops a user application container. A reboot or supervisor restart will cause the container to start again. The container is not removed with this endpoint.

This is only supported on single-container devices, and will fail on devices running multiple containers.

Returns an ok tuple with the ID of the stopped container.

Trigger an update check on the supervisor.

Example

iex> V1.update()
:ok

Trigger an update check on the supervisor. Optionally, forces an update when updates are locked.

Example

iex> V1.update(true)
:ok