1. Reference
  2. SDKs
  3. Node.js SDK
Improve this doc

Balena Node.js SDK

balena : object

Welcome to the Balena SDK documentation.

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

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.

Kind: global namespace

balena.interceptors : Array.<Interceptor>

The current array of interceptors to use. Interceptors intercept requests made internally and are executed in the order they appear in this array for requests, and in the reverse order for responses.

Kind: static property of balena
Summary: Array of interceptors
Access: public
Example 

balena.interceptors.push({
    responseError: function (error) {
        console.log(error);
        throw error;
    })
});

interceptors.Interceptor : object

An interceptor implements some set of the four interception hook callbacks. To continue processing, each function should return a value or a promise that successfully resolves to a value.

To halt processing, each function should throw an error or return a promise that rejects with an error.

Kind: static typedef of interceptors
Properties

Name Type Description
[request] function Callback invoked before requests are made. Called with the request options, should return (or resolve to) new request options, or throw/reject.
[response] function Callback invoked before responses are returned. Called with the response, should return (or resolve to) a new response, or throw/reject.
[requestError] function Callback invoked if an error happens before a request. Called with the error itself, caused by a preceeding request interceptor rejecting/throwing an error for the request, or a failing in preflight token validation. Should return (or resolve to) new request options, or throw/reject.
[responseError] function Callback invoked if an error happens in the response. Called with the error itself, caused by a preceeding response interceptor rejecting/throwing an error for the request, a network error, or an error response from the server. Should return (or resolve to) a new response, or throw/reject.

balena.request : Object

The balena-request instance used internally. This should not be necessary in normal usage, but can be useful if you want to make an API request directly, using the same token and hooks as the SDK.

Kind: static property of balena
Summary: Balena request instance
Access: public
Example 

balena.request.send({ url: 'http://api.balena-cloud.com/ping' });

balena.pine : Object

The balena-pine instance used internally. This should not be necessary in normal usage, but can be useful if you want to directly make pine queries to the api for some resource that isn't directly supported in the SDK.

Kind: static property of balena
Summary: Balena pine instance
Access: public
Example 

balena.pine.get({
    resource: 'release/$count',
    options: {
        $filter: { belongs_to__application: applicationId }
    }
});

balena.errors : Object

The balena-errors module used internally. This is provided primarily for convenience, and to avoid the necessity for separate balena-errors dependencies. You'll want to use this if you need to match on the specific type of error thrown by the SDK.

Kind: static property of balena
Summary: Balena errors module
Access: public
Example 

balena.models.device.get(123).catch(function (error) {
  if (error.code === balena.errors.BalenaDeviceNotFound.code) {
    ...
  } else if (error.code === balena.errors.BalenaRequestError.code) {
    ...
  }
});

balena.models : object

Kind: static namespace of balena

models.application : object

Kind: static namespace of models

application.tags : object

Kind: static namespace of application

tags.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of tags
Summary: Get all application tags for an application
Access: public
Fulfil: Object[] - application tags

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.application.tags.getAllByApplication('MyApp').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.application.tags.getAllByApplication(999999).then(function(tags) {
    console.log(tags);
});

Example 

balena.models.application.tags.getAllByApplication('MyApp', function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.getAll([options]) ⇒ Promise

Kind: static method of tags
Summary: Get all application tags
Access: public
Fulfil: Object[] - application tags

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.application.tags.getAll().then(function(tags) {
    console.log(tags);
});

Example 

balena.models.application.tags.getAll(function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.set(nameOrId, tagKey, value) ⇒ Promise

Kind: static method of tags
Summary: Set an application tag
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
tagKey String tag key
value String \ undefined tag value

Example 

balena.models.application.tags.set('7cf02a6', 'EDITOR', 'vim');

Example 

balena.models.application.tags.set(123, 'EDITOR', 'vim');

Example 

balena.models.application.tags.set('7cf02a6', 'EDITOR', 'vim', function(error) {
    if (error) throw error;
});

tags.remove(nameOrId, tagKey) ⇒ Promise

Kind: static method of tags
Summary: Remove an application tag
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
tagKey String tag key

Example 

balena.models.application.tags.remove('7cf02a6', 'EDITOR');

Example 

balena.models.application.tags.remove('7cf02a6', 'EDITOR', function(error) {
    if (error) throw error;
});

application.configVar : object

Kind: static namespace of application

configVar.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of configVar
Summary: Get all config variables for an application
Access: public
Fulfil: Object[] - application config variables

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.application.configVar.getAllByApplication('MyApp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.configVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.configVar.getAllByApplication('MyApp', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

configVar.get(nameOrId, key) ⇒ Promise

Kind: static method of configVar
Summary: Get the value of a specific config variable
Access: public
Fulfil: String|undefined - the config variable value (or undefined)

Param Type Description
nameOrId String \ Number application name (string) or id (number)
key String config variable name

Example 

balena.models.application.configVar.get('MyApp', 'BALENA_VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.configVar.get(999999, 'BALENA_VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.configVar.get('MyApp', 'BALENA_VAR', function(error, value) {
    if (error) throw error;
    console.log(value)
});

configVar.set(nameOrId, key, value) ⇒ Promise

Kind: static method of configVar
Summary: Set the value of a specific config variable
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
key String config variable name
value String config variable value

Example 

balena.models.application.configVar.set('MyApp', 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.configVar.set(999999, 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.configVar.set('MyApp', 'BALENA_VAR', 'newvalue', function(error) {
    if (error) throw error;
    ...
});

configVar.remove(nameOrId, key) ⇒ Promise

Kind: static method of configVar
Summary: Clear the value of a specific config variable
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
key String config variable name

Example 

balena.models.application.configVar.remove('MyApp', 'BALENA_VAR').then(function() {
    ...
});

Example 

balena.models.application.configVar.remove(999999, 'BALENA_VAR').then(function() {
    ...
});

Example 

balena.models.application.configVar.remove('MyApp', 'BALENA_VAR', function(error) {
    if (error) throw error;
    ...
});

application.envVar : object

Kind: static namespace of application

envVar.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of envVar
Summary: Get all environment variables for an application
Access: public
Fulfil: Object[] - application environment variables

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.application.envVar.getAllByApplication('MyApp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.envVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.envVar.getAllByApplication('MyApp', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

envVar.get(nameOrId, key) ⇒ Promise

Kind: static method of envVar
Summary: Get the value of a specific environment variable
Access: public
Fulfil: String|undefined - the environment variable value (or undefined)

Param Type Description
nameOrId String \ Number application name (string) or id (number)
key String environment variable name

Example 

balena.models.application.envVar.get('MyApp', 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.envVar.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.envVar.get('MyApp', 'VAR', function(error, value) {
    if (error) throw error;
    console.log(value)
});

envVar.set(nameOrId, key, value) ⇒ Promise

Kind: static method of envVar
Summary: Set the value of a specific environment variable
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
key String environment variable name
value String environment variable value

Example 

balena.models.application.envVar.set('MyApp', 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.envVar.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.envVar.set('MyApp', 'VAR', 'newvalue', function(error) {
    if (error) throw error;
    ...
});

envVar.remove(nameOrId, key) ⇒ Promise

Kind: static method of envVar
Summary: Clear the value of a specific environment variable
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
key String environment variable name

Example 

balena.models.application.envVar.remove('MyApp', 'VAR').then(function() {
    ...
});

Example 

balena.models.application.envVar.remove(999999, 'VAR').then(function() {
    ...
});

Example 

balena.models.application.envVar.remove('MyApp', 'VAR', function(error) {
    if (error) throw error;
    ...
});

application.getAll([options]) ⇒ Promise

Kind: static method of application
Summary: Get all applications
Access: public
Fulfil: Object[] - applications

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.application.getAll().then(function(applications) {
    console.log(applications);
});

Example 

balena.models.application.getAll(function(error, applications) {
    if (error) throw error;
    console.log(applications);
});

application.getAllWithDeviceServiceDetails([options]) ⇒ Promise

This method does not map exactly to the underlying model: it runs a larger prebuilt query, and reformats it into an easy to use and understand format. If you want more control, or to see the raw model directly, use application.getAll(options) instead.

Kind: static method of application
Summary: Get applications and their devices, along with each device's associated services' essential details
Access: public
Fulfil: Object[] - applications

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.application.getAllWithDeviceServiceDetails().then(function(applications) {
    console.log(applications);
})

Example 

balena.models.application.getAllWithDeviceServiceDetails(function(error, applications) {
    if (error) throw error;
    console.log(applications);
});

application.get(nameOrId, [options]) ⇒ Promise

Kind: static method of application
Summary: Get a single application
Access: public
Fulfil: Object - application

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.application.get('MyApp').then(function(application) {
    console.log(application);
});

Example 

balena.models.application.get(123).then(function(application) {
    console.log(application);
});

Example 

balena.models.application.get('MyApp', function(error, application) {
    if (error) throw error;
    console.log(application);
});

application.getWithDeviceServiceDetails(nameOrId, [options]) ⇒ Promise

This method does not map exactly to the underlying model: it runs a larger prebuilt query, and reformats it into an easy to use and understand format. If you want more control, or to see the raw model directly, use application.get(uuidOrId, options) instead.

Kind: static method of application
Summary: Get a single application and its devices, along with each device's associated services' essential details
Access: public
Fulfil: Object - application

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.application.getWithDeviceServiceDetails('7cf02a6').then(function(device) {
    console.log(device);
})

Example 

balena.models.application.getWithDeviceServiceDetails(123).then(function(device) {
    console.log(device);
})

Example 

balena.models.application.getWithDeviceServiceDetails('7cf02a6', function(error, device) {
    if (error) throw error;
    console.log(device);
});

application.getAppByOwner(appName, owner, [options]) ⇒ Promise

Kind: static method of application
Summary: Get a single application using the appname and owner's username
Access: public
Fulfil: Object - application

Param Type Default Description
appName String application name
owner String The owner's username
[options] Object {} extra pine options to use

Example 

balena.models.application.getAppByOwner('MyApp', 'MyUser').then(function(application) {
    console.log(application);
});

application.has(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Check if an application exists
Access: public
Fulfil: Boolean - has application

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.has('MyApp').then(function(hasApp) {
    console.log(hasApp);
});

Example 

balena.models.application.has(123).then(function(hasApp) {
    console.log(hasApp);
});

Example 

balena.models.application.has('MyApp', function(error, hasApp) {
    if (error) throw error;
    console.log(hasApp);
});

application.hasAny() ⇒ Promise

Kind: static method of application
Summary: Check if the user has any applications
Access: public
Fulfil: Boolean - has any applications
Example 

balena.models.application.hasAny().then(function(hasAny) {
    console.log('Has any?', hasAny);
});

Example 

balena.models.application.hasAny(function(error, hasAny) {
    if (error) throw error;
    console.log('Has any?', hasAny);
});

application.create(options) ⇒ Promise

Kind: static method of application
Summary: Create an application
Access: public
Fulfil: Object - application

Param Type Description
options Object application creation parameters
options.name String application name
[options.applicationType] String application type slug e.g. microservices-starter
options.deviceType String device type slug
[options.parent] Number \ String parent application name or id

Example 

balena.models.application.create({ name: 'My App', applicationType: 'essentials', deviceType: 'raspberry-pi').then(function(application) {
    console.log(application);
});

Example 

balena.models.application.create({ name: 'My App', applicationType: 'microservices', deviceType: 'raspberry-pi', parent: 'ParentApp' }).then(function(application) {
    console.log(application);
});

Example 

balena.models.application.create({ name: 'My App', applicationType: 'microservices-starter', deviceType: 'raspberry-pi' }, function(error, application) {
    if (error) throw error;
    console.log(application);
});

application.remove(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Remove application
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.remove('MyApp');

Example 

balena.models.application.remove(123);

Example 

balena.models.application.remove('MyApp', function(error) {
    if (error) throw error;
});

application.restart(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Restart application
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.restart('MyApp');

Example 

balena.models.application.restart(123);

Example 

balena.models.application.restart('MyApp', function(error) {
    if (error) throw error;
});

application.generateApiKey(nameOrId) ⇒ Promise

Deprecated

Generally you shouldn't use this method: if you're provisioning a recent BalenaOS version (2.4.0+) then generateProvisioningKey should work just as well, but be more secure.

Kind: static method of application
Summary: Generate an API key for a specific application
Access: public
Fulfil: String - api key

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.generateApiKey('MyApp').then(function(apiKey) {
    console.log(apiKey);
});

Example 

balena.models.application.generateApiKey(123).then(function(apiKey) {
    console.log(apiKey);
});

Example 

balena.models.application.generateApiKey('MyApp', function(error, apiKey) {
    if (error) throw error;
    console.log(apiKey);
});

application.generateProvisioningKey(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Generate a device provisioning key for a specific application
Access: public
Fulfil: String - device provisioning key

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.generateProvisioningKey('MyApp').then(function(key) {
    console.log(key);
});

Example 

balena.models.application.generateProvisioningKey(123).then(function(key) {
    console.log(key);
});

Example 

balena.models.application.generateProvisioningKey('MyApp', function(error, key) {
    if (error) throw error;
    console.log(key);
});

application.purge(appId) ⇒ Promise

Kind: static method of application
Summary: Purge devices by application id
Access: public

Param Type Description
appId Number application id

Example 

balena.models.application.purge(123);

Example 

balena.models.application.purge(123, function(error) {
    if (error) throw error;
});

application.shutdown(appId, [options]) ⇒ Promise

Kind: static method of application
Summary: Shutdown devices by application id
Access: public

Param Type Default Description
appId Number application id
[options] Object options
[options.force] Boolean false override update lock

Example 

balena.models.application.shutdown(123);

Example 

balena.models.application.shutdown(123, function(error) {
    if (error) throw error;
});

application.reboot(appId, [options]) ⇒ Promise

Kind: static method of application
Summary: Reboot devices by application id
Access: public

Param Type Default Description
appId Number application id
[options] Object options
[options.force] Boolean false override update lock

Example 

balena.models.application.reboot(123);

Example 

balena.models.application.reboot(123, function(error) {
    if (error) throw error;
});

application.willTrackNewReleases(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Get whether the application is configured to receive updates whenever a new release is available
Access: public
Fulfil: Boolean - is tracking the latest release

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.willTrackNewReleases('MyApp').then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.application.willTrackNewReleases(123).then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.application.willTrackNewReleases('MyApp', function(error, isEnabled) {
    console.log(isEnabled);
});

application.isTrackingLatestRelease(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Get whether the application is up to date and is tracking the latest release for updates
Access: public
Fulfil: Boolean - is tracking the latest release

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.isTrackingLatestRelease('MyApp').then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.application.isTrackingLatestRelease(123).then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.application.isTrackingLatestRelease('MyApp', function(error, isEnabled) {
    console.log(isEnabled);
});

application.pinToRelease(nameOrId, fullReleaseHash) ⇒ Promise

Configures the application to run a particular release and not get updated when the latest release changes.

Kind: static method of application
Summary: Set a specific application to run a particular release
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
fullReleaseHash String the hash of a successful release (string)

Example 

balena.models.application.pinToRelease('MyApp', 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

Example 

balena.models.application.pinToRelease(123, 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

Example 

balena.models.application.pinToRelease('MyApp', 'f7caf4ff80114deeaefb7ab4447ad9c661c50847', function(error) {
    if (error) throw error;
    ...
});

application.getTargetReleaseHash(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Get the hash of the current release for a specific application
Access: public
Fulfil: String - The release hash of the current release

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.getTargetReleaseHash('MyApp').then(function(release) {
    console.log(release);
});

Example 

balena.models.application.getTargetReleaseHash(123).then(function(release) {
    console.log(release);
});

Example 

balena.models.application.getTargetReleaseHash('MyApp', function(release) {
    console.log(release);
});

application.trackLatestRelease(nameOrId) ⇒ Promise

The application's current release will be updated with each new successfully built release.

Kind: static method of application
Summary: Configure a specific application to track the latest available release
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.trackLatestRelease('MyApp').then(function() {
    ...
});

Example 

balena.models.application.trackLatestRelease(123).then(function() {
    ...
});

Example 

balena.models.application.trackLatestRelease('MyApp', function(error) {
    if (error) throw error;
    ...
});

application.enableDeviceUrls(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Enable device urls for all devices that belong to an application
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.enableDeviceUrls('MyApp');

Example 

balena.models.application.enableDeviceUrls(123);

Example 

balena.models.device.enableDeviceUrls('MyApp', function(error) {
    if (error) throw error;
});

application.disableDeviceUrls(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Disable device urls for all devices that belong to an application
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.disableDeviceUrls('MyApp');

Example 

balena.models.application.disableDeviceUrls(123);

Example 

balena.models.device.disableDeviceUrls('MyApp', function(error) {
    if (error) throw error;
});

application.grantSupportAccess(nameOrId, expiryTimestamp) ⇒ Promise

Kind: static method of application
Summary: Grant support access to an application until a specified time
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)
expiryTimestamp Number a timestamp in ms for when the support access will expire

Example 

balena.models.application.grantSupportAccess('MyApp', Date.now() + 3600 * 1000);

Example 

balena.models.application.grantSupportAccess(123, Date.now() + 3600 * 1000);

Example 

balena.models.application.grantSupportAccess('MyApp', Date.now() + 3600 * 1000, function(error) {
    if (error) throw error;
});

application.revokeSupportAccess(nameOrId) ⇒ Promise

Kind: static method of application
Summary: Revoke support access to an application
Access: public

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.application.revokeSupportAccess('MyApp');

Example 

balena.models.application.revokeSupportAccess(123);

Example 

balena.models.application.revokeSupportAccess('MyApp', function(error) {
    if (error) throw error;
});

models.device : object

Kind: static namespace of models

device.tags : object

Kind: static namespace of device

tags.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of tags
Summary: Get all device tags for an application
Access: public
Fulfil: Object[] - device tags

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.tags.getAllByApplication('MyApp').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAllByApplication(999999).then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAllByApplication('MyApp', function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of tags
Summary: Get all device tags for a device
Access: public
Fulfil: Object[] - device tags

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.tags.getAllByDevice('7cf02a6').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAllByDevice(123).then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAllByDevice('7cf02a6', function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.getAll([options]) ⇒ Promise

Kind: static method of tags
Summary: Get all device tags
Access: public
Fulfil: Object[] - device tags

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.device.tags.getAll().then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAll(function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.set(uuidOrId, tagKey, value) ⇒ Promise

Kind: static method of tags
Summary: Set a device tag
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
tagKey String tag key
value String \ undefined tag value

Example 

balena.models.device.tags.set('7cf02a6', 'EDITOR', 'vim');

Example 

balena.models.device.tags.set(123, 'EDITOR', 'vim');

Example 

balena.models.device.tags.set('7cf02a6', 'EDITOR', 'vim', function(error) {
    if (error) throw error;
});

tags.remove(uuidOrId, tagKey) ⇒ Promise

Kind: static method of tags
Summary: Remove a device tag
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
tagKey String tag key

Example 

balena.models.device.tags.remove('7cf02a6', 'EDITOR');

Example 

balena.models.device.tags.remove('7cf02a6', 'EDITOR', function(error) {
    if (error) throw error;
});

device.configVar : object

Kind: static namespace of device

configVar.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of configVar
Summary: Get all config variables for a device
Access: public
Fulfil: Object[] - device config variables

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.configVar.getAllByDevice('7cf02a6').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.configVar.getAllByDevice(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.configVar.getAllByDevice('7cf02a6', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

configVar.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of configVar
Summary: Get all device config variables by application
Access: public
Fulfil: Object[] - device config variables

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.configVar.getAllByApplication('MyApp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.configVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.configVar.getAllByApplication('MyApp', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

configVar.get(uuidOrId, key) ⇒ Promise

Kind: static method of configVar
Summary: Get the value of a specific config variable
Access: public
Fulfil: String|undefined - the config variable value (or undefined)

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
key String config variable name

Example 

balena.models.device.configVar.get('7cf02a6', 'BALENA_VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.configVar.get(999999, 'BALENA_VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.configVar.get('7cf02a6', 'BALENA_VAR', function(error, value) {
    if (error) throw error;
    console.log(value)
});

configVar.set(uuidOrId, key, value) ⇒ Promise

Kind: static method of configVar
Summary: Set the value of a specific config variable
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
key String config variable name
value String config variable value

Example 

balena.models.device.configVar.set('7cf02a6', 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.device.configVar.set(999999, 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.device.configVar.set('7cf02a6', 'BALENA_VAR', 'newvalue', function(error) {
    if (error) throw error;
    ...
});

configVar.remove(uuidOrId, key) ⇒ Promise

Kind: static method of configVar
Summary: Clear the value of a specific config variable
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
key String config variable name

Example 

balena.models.device.configVar.remove('7cf02a6', 'BALENA_VAR').then(function() {
    ...
});

Example 

balena.models.device.configVar.remove(999999, 'BALENA_VAR').then(function() {
    ...
});

Example 

balena.models.device.configVar.remove('7cf02a6', 'BALENA_VAR', function(error) {
    if (error) throw error;
    ...
});

device.envVar : object

Kind: static namespace of device

envVar.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of envVar
Summary: Get all environment variables for a device
Access: public
Fulfil: Object[] - device environment variables

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.envVar.getAllByDevice('7cf02a6').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.envVar.getAllByDevice(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.envVar.getAllByDevice('7cf02a6', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

envVar.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of envVar
Summary: Get all device environment variables by application
Access: public
Fulfil: Object[] - device environment variables

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.envVar.getAllByApplication('MyApp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.envVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.envVar.getAllByApplication('MyApp', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

envVar.get(uuidOrId, key) ⇒ Promise

Kind: static method of envVar
Summary: Get the value of a specific environment variable
Access: public
Fulfil: String|undefined - the environment variable value (or undefined)

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
key String environment variable name

Example 

balena.models.device.envVar.get('7cf02a6', 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.envVar.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.envVar.get('7cf02a6', 'VAR', function(error, value) {
    if (error) throw error;
    console.log(value)
});

envVar.set(uuidOrId, key, value) ⇒ Promise

Kind: static method of envVar
Summary: Set the value of a specific environment variable
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
key String environment variable name
value String environment variable value

Example 

balena.models.device.envVar.set('7cf02a6', 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.device.envVar.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.device.envVar.set('7cf02a6', 'VAR', 'newvalue', function(error) {
    if (error) throw error;
    ...
});

envVar.remove(uuidOrId, key) ⇒ Promise

Kind: static method of envVar
Summary: Clear the value of a specific environment variable
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
key String environment variable name

Example 

balena.models.device.envVar.remove('7cf02a6', 'VAR').then(function() {
    ...
});

Example 

balena.models.device.envVar.remove(999999, 'VAR').then(function() {
    ...
});

Example 

balena.models.device.envVar.remove('7cf02a6', 'VAR', function(error) {
    if (error) throw error;
    ...
});

device.serviceVar : object

Kind: static namespace of device

serviceVar.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of serviceVar
Summary: Get all service variable overrides for a device
Access: public
Fulfil: Object[] - service variables

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.serviceVar.getAllByDevice('7cf02a6').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.serviceVar.getAllByDevice(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.serviceVar.getAllByDevice('7cf02a6', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

serviceVar.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of serviceVar
Summary: Get all device service variable overrides by application
Access: public
Fulfil: Object[] - service variables

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.serviceVar.getAllByApplication('MyApp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.serviceVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.serviceVar.getAllByApplication('MyApp', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

serviceVar.get(uuidOrId, id, key) ⇒ Promise

Kind: static method of serviceVar
Summary: Get the overriden value of a service variable on a device
Access: public
Fulfil: String|undefined - the variable value (or undefined)

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
id Number service id
key String variable name

Example 

balena.models.device.serviceVar.get('7cf02a6', 123, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.serviceVar.get(999999, 123, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.serviceVar.get('7cf02a6', 123, 'VAR', function(error, value) {
    if (error) throw error;
    console.log(value)
});

serviceVar.set(uuidOrId, id, key, value) ⇒ Promise

Kind: static method of serviceVar
Summary: Set the overriden value of a service variable on a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
id Number service id
key String variable name
value String variable value

Example 

balena.models.device.serviceVar.set('7cf02a6', 123, 'VAR', 'override').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.set(999999, 123, 'VAR', 'override').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.set('7cf02a6', 123, 'VAR', 'override', function(error) {
    if (error) throw error;
    ...
});

serviceVar.remove(uuidOrId, id, key) ⇒ Promise

Kind: static method of serviceVar
Summary: Clear the overridden value of a service variable on a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
id Number service id
key String variable name

Example 

balena.models.device.serviceVar.remove('7cf02a6', 123, 'VAR').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.remove(999999, 123, 'VAR').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.remove('7cf02a6', 123, 'VAR', function(error) {
    if (error) throw error;
    ...
});

device.getDashboardUrl(uuid) ⇒ String

Kind: static method of device
Summary: Get Dashboard URL for a specific device
Returns: String - - Dashboard URL for the specific device
Throws:

  • Exception if the uuid is empty
Param Type Description
uuid String Device uuid

Example 

dashboardDeviceUrl = balena.models.device.getDashboardUrl('a44b544b8cc24d11b036c659dfeaccd8')

device.getAll([options]) ⇒ Promise

Kind: static method of device
Summary: Get all devices
Access: public
Fulfil: Object[] - devices

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.device.getAll().then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAll(function(error, devices) {
    if (error) throw error;
    console.log(devices);
});

device.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of device
Summary: Get all devices by application
Access: public
Fulfil: Object[] - devices

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.getAllByApplication('MyApp').then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByApplication(123).then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByApplication('MyApp', function(error, devices) {
    if (error) throw error;
    console.log(devices);
});

device.getAllByParentDevice(parentUuidOrId, [options]) ⇒ Promise

Kind: static method of device
Summary: Get all devices by parent device
Access: public
Fulfil: Object[] - devices

Param Type Default Description
parentUuidOrId String \ Number parent device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.getAllByParentDevice('7cf02a6').then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByParentDevice(123).then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByParentDevice('7cf02a6', function(error, devices) {
    if (error) throw error;
    console.log(devices);
});

device.get(uuidOrId, [options]) ⇒ Promise

Kind: static method of device
Summary: Get a single device
Access: public
Fulfil: Object - device

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.get('7cf02a6').then(function(device) {
    console.log(device);
})

Example 

balena.models.device.get(123).then(function(device) {
    console.log(device);
})

Example 

balena.models.device.get('7cf02a6', function(error, device) {
    if (error) throw error;
    console.log(device);
});

device.getWithServiceDetails(uuidOrId, [options]) ⇒ Promise

This method does not map exactly to the underlying model: it runs a larger prebuilt query, and reformats it into an easy to use and understand format. If you want more control, or to see the raw model directly, use device.get(uuidOrId, options) instead.

Kind: static method of device
Summary: Get a single device along with its associated services' essential details
Access: public
Fulfil: Object - device with service details

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.device.getWithServiceDetails('7cf02a6').then(function(device) {
    console.log(device);
})

Example 

balena.models.device.getWithServiceDetails(123).then(function(device) {
    console.log(device);
})

Example 

balena.models.device.getWithServiceDetails('7cf02a6', function(error, device) {
    if (error) throw error;
    console.log(device);
});

device.getByName(name) ⇒ Promise

Kind: static method of device
Summary: Get devices by name
Access: public
Fulfil: Object[] - devices

Param Type Description
name String device name

Example 

balena.models.device.getByName('MyDevice').then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getByName('MyDevice', function(error, devices) {
    if (error) throw error;
    console.log(devices);
});

device.getName(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Get the name of a device
Access: public
Fulfil: String - device name

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.getName('7cf02a6').then(function(deviceName) {
    console.log(deviceName);
});

Example 

balena.models.device.getName(123).then(function(deviceName) {
    console.log(deviceName);
});

Example 

balena.models.device.getName('7cf02a6', function(error, deviceName) {
    if (error) throw error;
    console.log(deviceName);
});

device.getApplicationName(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Get application name
Access: public
Fulfil: String - application name

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.getApplicationName('7cf02a6').then(function(applicationName) {
    console.log(applicationName);
});

Example 

balena.models.device.getApplicationName(123).then(function(applicationName) {
    console.log(applicationName);
});

Example 

balena.models.device.getApplicationName('7cf02a6', function(error, applicationName) {
    if (error) throw error;
    console.log(applicationName);
});

device.getApplicationInfo(uuidOrId) ⇒ Promise

Deprecated

This is not supported on multicontainer devices, and will be removed in a future major release

Kind: static method of device
Summary: Get application container information
Access: public
Fulfil: Object - application info

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.getApplicationInfo('7cf02a6').then(function(appInfo) {
    console.log(appInfo);
});

Example 

balena.models.device.getApplicationInfo(123).then(function(appInfo) {
    console.log(appInfo);
});

Example 

balena.models.device.getApplicationInfo('7cf02a6', function(error, appInfo) {
    if (error) throw error;
    console.log(appInfo);
});

device.has(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Check if a device exists
Access: public
Fulfil: Boolean - has device

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.has('7cf02a6').then(function(hasDevice) {
    console.log(hasDevice);
});

Example 

balena.models.device.has(123).then(function(hasDevice) {
    console.log(hasDevice);
});

Example 

balena.models.device.has('7cf02a6', function(error, hasDevice) {
    if (error) throw error;
    console.log(hasDevice);
});

device.isOnline(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Check if a device is online
Access: public
Fulfil: Boolean - is device online

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.isOnline('7cf02a6').then(function(isOnline) {
    console.log('Is device online?', isOnline);
});

Example 

balena.models.device.isOnline(123).then(function(isOnline) {
    console.log('Is device online?', isOnline);
});

Example 

balena.models.device.isOnline('7cf02a6', function(error, isOnline) {
    if (error) throw error;
    console.log('Is device online?', isOnline);
});

device.getLocalIPAddresses(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Get the local IP addresses of a device
Access: public
Fulfil: String[] - local ip addresses
Reject: Error Will reject if the device is offline

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.getLocalIPAddresses('7cf02a6').then(function(localIPAddresses) {
    localIPAddresses.forEach(function(localIP) {
        console.log(localIP);
    });
});

Example 

balena.models.device.getLocalIPAddresses(123).then(function(localIPAddresses) {
    localIPAddresses.forEach(function(localIP) {
        console.log(localIP);
    });
});

Example 

balena.models.device.getLocalIPAddresses('7cf02a6', function(error, localIPAddresses) {
    if (error) throw error;

    localIPAddresses.forEach(function(localIP) {
        console.log(localIP);
    });
});

device.remove(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Remove device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.remove('7cf02a6');

Example 

balena.models.device.remove(123);

Example 

balena.models.device.remove('7cf02a6', function(error) {
    if (error) throw error;
});

device.identify(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Identify device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.identify('7cf02a6');

Example 

balena.models.device.identify(123);

Example 

balena.models.device.identify('7cf02a6', function(error) {
    if (error) throw error;
});

device.rename(uuidOrId, newName) ⇒ Promise

Kind: static method of device
Summary: Rename device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
newName String the device new name

Example 

balena.models.device.rename('7cf02a6', 'NewName');

Example 

balena.models.device.rename(123, 'NewName');

Example 

balena.models.device.rename('7cf02a6', 'NewName', function(error) {
    if (error) throw error;
});

device.note(uuidOrId, note) ⇒ Promise

Kind: static method of device
Summary: Note a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
note String the note

Example 

balena.models.device.note('7cf02a6', 'My useful note');

Example 

balena.models.device.note(123, 'My useful note');

Example 

balena.models.device.note('7cf02a6', 'My useful note', function(error) {
    if (error) throw error;
});

device.setCustomLocation(uuidOrId, location) ⇒ Promise

Kind: static method of device
Summary: Set a custom location for a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
location Object the location ({ latitude: 123, longitude: 456 })

Example 

balena.models.device.setCustomLocation('7cf02a6', { latitude: 123, longitude: 456 });

Example 

balena.models.device.setCustomLocation(123, { latitude: 123, longitude: 456 });

Example 

balena.models.device.setCustomLocation('7cf02a6', { latitude: 123, longitude: 456 }, function(error) {
    if (error) throw error;
});

device.unsetCustomLocation(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Clear the custom location of a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.unsetCustomLocation('7cf02a6');

Example 

balena.models.device.unsetCustomLocation(123);

Example 

balena.models.device.unsetLocation('7cf02a6', function(error) {
    if (error) throw error;
});

device.move(uuidOrId, applicationNameOrId) ⇒ Promise

Kind: static method of device
Summary: Move a device to another application
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
applicationNameOrId String \ Number application name (string) or id (number)

Example 

balena.models.device.move('7cf02a6', 'MyApp');

Example 

balena.models.device.move(123, 'MyApp');

Example 

balena.models.device.move(123, 456);

Example 

balena.models.device.move('7cf02a6', 'MyApp', function(error) {
    if (error) throw error;
});

device.startApplication(uuidOrId) ⇒ Promise

Deprecated

This is not supported on multicontainer devices, and will be removed in a future major release

Kind: static method of device
Summary: Start application on device
Access: public
Fulfil: String - application container id

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.startApplication('7cf02a6').then(function(containerId) {
    console.log(containerId);
});

Example 

balena.models.device.startApplication(123).then(function(containerId) {
    console.log(containerId);
});

Example 

balena.models.device.startApplication('7cf02a6', function(error, containerId) {
    if (error) throw error;
    console.log(containerId);
});

device.stopApplication(uuidOrId) ⇒ Promise

Deprecated

This is not supported on multicontainer devices, and will be removed in a future major release

Kind: static method of device
Summary: Stop application on device
Access: public
Fulfil: String - application container id

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.stopApplication('7cf02a6').then(function(containerId) {
    console.log(containerId);
});

Example 

balena.models.device.stopApplication(123).then(function(containerId) {
    console.log(containerId);
});

Example 

balena.models.device.stopApplication('7cf02a6', function(error, containerId) {
    if (error) throw error;
    console.log(containerId);
});

device.restartApplication(uuidOrId) ⇒ Promise

This function restarts the Docker container running the application on the device, but doesn't reboot the device itself.

Kind: static method of device
Summary: Restart application on device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.restartApplication('7cf02a6');

Example 

balena.models.device.restartApplication(123);

Example 

balena.models.device.restartApplication('7cf02a6', function(error) {
    if (error) throw error;
});

device.startService(uuidOrId, imageId) ⇒ Promise

Kind: static method of device
Summary: Start a service on a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
imageId Number id of the image to start

Example 

balena.models.device.startService('7cf02a6', 123).then(function() {
    ...
});

Example 

balena.models.device.startService(1, 123).then(function() {
    ...
});

Example 

balena.models.device.startService('7cf02a6', 123, function(error) {
    if (error) throw error;
    ...
});

device.stopService(uuidOrId, imageId) ⇒ Promise

Kind: static method of device
Summary: Stop a service on a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
imageId Number id of the image to stop

Example 

balena.models.device.stopService('7cf02a6', 123).then(function() {
    ...
});

Example 

balena.models.device.stopService(1, 123).then(function() {
    ...
});

Example 

balena.models.device.stopService('7cf02a6', 123, function(error) {
    if (error) throw error;
    ...
});

device.restartService(uuidOrId, imageId) ⇒ Promise

Kind: static method of device
Summary: Restart a service on a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
imageId Number id of the image to restart

Example 

balena.models.device.restartService('7cf02a6', 123).then(function() {
    ...
});

Example 

balena.models.device.restartService(1, 123).then(function() {
    ...
});

Example 

balena.models.device.restartService('7cf02a6', 123, function(error) {
    if (error) throw error;
    ...
});

device.reboot(uuidOrId, [options]) ⇒ Promise

Kind: static method of device
Summary: Reboot device
Access: public

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object options
[options.force] Boolean false override update lock

Example 

balena.models.device.reboot('7cf02a6');

Example 

balena.models.device.reboot(123);

Example 

balena.models.device.reboot('7cf02a6', function(error) {
    if (error) throw error;
});

device.shutdown(uuidOrId, [options]) ⇒ Promise

Kind: static method of device
Summary: Shutdown device
Access: public

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object options
[options.force] Boolean false override update lock

Example 

balena.models.device.shutdown('7cf02a6');

Example 

balena.models.device.shutdown(123);

Example 

balena.models.device.shutdown('7cf02a6', function(error) {
    if (error) throw error;
});

device.purge(uuidOrId) ⇒ Promise

This function clears the user application's /data directory.

Kind: static method of device
Summary: Purge device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.purge('7cf02a6');

Example 

balena.models.device.purge(123);

Example 

balena.models.device.purge('7cf02a6', function(error) {
    if (error) throw error;
});

device.update(uuidOrId, [options]) ⇒ Promise

Kind: static method of device
Summary: Trigger an update check on the supervisor
Access: public

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object options
[options.force] Boolean false override update lock

Example 

balena.models.device.update('7cf02a6', {
    force: true
});

Example 

balena.models.device.update(123, {
    force: true
});

Example 

balena.models.device.update('7cf02a6', {
    force: true
}, function(error) {
    if (error) throw error;
});

device.getDisplayName(deviceTypeSlug) ⇒ Promise

Kind: static method of device
Summary: Get display name for a device
Access: public
Fulfil: String - device display name
See: module:balena.models.device.getSupportedDeviceTypes for a list of supported devices

Param Type Description
deviceTypeSlug String device type slug

Example 

balena.models.device.getDisplayName('raspberry-pi').then(function(deviceTypeName) {
    console.log(deviceTypeName);
    // Raspberry Pi
});

Example 

balena.models.device.getDisplayName('raspberry-pi', function(error, deviceTypeName) {
    if (error) throw error;
    console.log(deviceTypeName);
    // Raspberry Pi
});

device.getDeviceSlug(deviceTypeName) ⇒ Promise

Kind: static method of device
Summary: Get device slug
Access: public
Fulfil: String - device slug name
See: module:balena.models.device.getSupportedDeviceTypes for a list of supported devices

Param Type Description
deviceTypeName String device type name

Example 

balena.models.device.getDeviceSlug('Raspberry Pi').then(function(deviceTypeSlug) {
    console.log(deviceTypeSlug);
    // raspberry-pi
});

Example 

balena.models.device.getDeviceSlug('Raspberry Pi', function(error, deviceTypeSlug) {
    if (error) throw error;
    console.log(deviceTypeSlug);
    // raspberry-pi
});

device.getSupportedDeviceTypes() ⇒ Promise

Kind: static method of device
Summary: Get supported device types
Access: public
Fulfil: String[] - supported device types
Example 

balena.models.device.getSupportedDeviceTypes().then(function(supportedDeviceTypes) {
    supportedDeviceTypes.forEach(function(supportedDeviceType) {
        console.log('Balena supports:', supportedDeviceType);
    });
});

Example 

balena.models.device.getSupportedDeviceTypes(function(error, supportedDeviceTypes) {
    if (error) throw error;

    supportedDeviceTypes.forEach(function(supportedDeviceType) {
        console.log('Balena supports:', supportedDeviceType);
    });
});

device.getManifestBySlug(slug) ⇒ Promise

Kind: static method of device
Summary: Get a device manifest by slug
Access: public
Fulfil: Object - device manifest

Param Type Description
slug String device slug

Example 

balena.models.device.getManifestBySlug('raspberry-pi').then(function(manifest) {
    console.log(manifest);
});

Example 

balena.models.device.getManifestBySlug('raspberry-pi', function(error, manifest) {
    if (error) throw error;
    console.log(manifest);
});

device.getManifestByApplication(nameOrId) ⇒ Promise

Kind: static method of device
Summary: Get a device manifest by application name
Access: public
Fulfil: Object - device manifest

Param Type Description
nameOrId String \ Number application name (string) or id (number)

Example 

balena.models.device.getManifestByApplication('MyApp').then(function(manifest) {
    console.log(manifest);
});

Example 

balena.models.device.getManifestByApplication(123).then(function(manifest) {
    console.log(manifest);
});

Example 

balena.models.device.getManifestByApplication('MyApp', function(error, manifest) {
    if (error) throw error;
    console.log(manifest);
});

device.generateUniqueKey() ⇒ String

Kind: static method of device
Summary: Generate a random key, useful for both uuid and api key.
Returns: String - A generated key
Access: public
Example 

randomKey = balena.models.device.generateUniqueKey();
// randomKey is a randomly generated key that can be used as either a uuid or an api key
console.log(randomKey);

device.register(applicationNameOrId, [uuid]) ⇒ Promise

Kind: static method of device
Summary: Register a new device with a Balena application.
Access: public
Fulfil: Object Device registration info ({ id: "...", uuid: "...", api_key: "..." })

Param Type Description
applicationNameOrId String \ Number application name (string) or id (number)
[uuid] String device uuid

Example 

var uuid = balena.models.device.generateUniqueKey();
balena.models.device.register('MyApp', uuid).then(function(registrationInfo) {
    console.log(registrationInfo);
});

Example 

var uuid = balena.models.device.generateUniqueKey();
balena.models.device.register(123, uuid).then(function(registrationInfo) {
    console.log(registrationInfo);
});

Example 

var uuid = balena.models.device.generateUniqueKey();
balena.models.device.register('MyApp', uuid, function(error, registrationInfo) {
    if (error) throw error;
    console.log(registrationInfo);
});

device.generateDeviceKey(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Generate a device key
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.generateDeviceKey('7cf02a6').then(function(deviceApiKey) {
    console.log(deviceApiKey);
});

Example 

balena.models.device.generateDeviceKey(123).then(function(deviceApiKey) {
    console.log(deviceApiKey);
});

Example 

balena.models.device.generateDeviceKey('7cf02a6', function(error, deviceApiKey) {
    if (error) throw error;
    console.log(deviceApiKey);
});

device.hasDeviceUrl(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Check if a device is web accessible with device utls
Access: public
Fulfil: Boolean - has device url

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.hasDeviceUrl('7cf02a6').then(function(hasDeviceUrl) {
    if (hasDeviceUrl) {
        console.log('The device has device URL enabled');
    }
});

Example 

balena.models.device.hasDeviceUrl(123).then(function(hasDeviceUrl) {
    if (hasDeviceUrl) {
        console.log('The device has device URL enabled');
    }
});

Example 

balena.models.device.hasDeviceUrl('7cf02a6', function(error, hasDeviceUrl) {
    if (error) throw error;

    if (hasDeviceUrl) {
        console.log('The device has device URL enabled');
    }
});

device.getDeviceUrl(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Get a device url
Access: public
Fulfil: String - device url

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.getDeviceUrl('7cf02a6').then(function(url) {
    console.log(url);
});

Example 

balena.models.device.getDeviceUrl(123).then(function(url) {
    console.log(url);
});

Example 

balena.models.device.getDeviceUrl('7cf02a6', function(error, url) {
    if (error) throw error;
    console.log(url);
});

device.enableDeviceUrl(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Enable device url for a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.enableDeviceUrl('7cf02a6');

Example 

balena.models.device.enableDeviceUrl(123);

Example 

balena.models.device.enableDeviceUrl('7cf02a6', function(error) {
    if (error) throw error;
});

device.disableDeviceUrl(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Disable device url for a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.disableDeviceUrl('7cf02a6');

Example 

balena.models.device.disableDeviceUrl(123);

Example 

balena.models.device.disableDeviceUrl('7cf02a6', function(error) {
    if (error) throw error;
});

device.ping(uuidOrId) ⇒ Promise

This is useful to signal that the supervisor is alive and responding.

Kind: static method of device
Summary: Ping a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.ping('7cf02a6');

Example 

balena.models.device.ping(123);

Example 

balena.models.device.ping('7cf02a6', function(error) {
    if (error) throw error;
});

device.getStatus(device) ⇒ Promise

Kind: static method of device
Summary: Get the status of a device
Access: public
Fulfil: String - device status

Param Type Description
device Object A device object

Example 

balena.models.device.getStatus(device).then(function(status) {
    console.log(status);
});

Example 

balena.models.device.getStatus(device, function(error, status) {
    if (error) throw error;
    console.log(status);
});

device.grantSupportAccess(uuidOrId, expiryTimestamp) ⇒ Promise

Kind: static method of device
Summary: Grant support access to a device until a specified time
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
expiryTimestamp Number a timestamp in ms for when the support access will expire

Example 

balena.models.device.grantSupportAccess('7cf02a6', Date.now() + 3600 * 1000);

Example 

balena.models.device.grantSupportAccess(123, Date.now() + 3600 * 1000);

Example 

balena.models.device.grantSupportAccess('7cf02a6', Date.now() + 3600 * 1000, function(error) {
    if (error) throw error;
});

device.revokeSupportAccess(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Revoke support access to a device
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.revokeSupportAccess('7cf02a6');

Example 

balena.models.device.revokeSupportAccess(123);

Example 

balena.models.device.revokeSupportAccess('7cf02a6', function(error) {
    if (error) throw error;
});

device.lastOnline(device) ⇒ String

If the device has never been online this method returns the string Connecting....

Kind: static method of device
Summary: Get a string showing when a device was last set as online
Access: public

Param Type Description
device Object A device object

Example 

balena.models.device.get('7cf02a6').then(function(device) {
    balena.models.device.lastOnline(device);
})

device.isTrackingApplicationRelease(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Get whether the device is configured to track the current application release
Access: public
Fulfil: Boolean - is tracking the current application release

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.isTrackingApplicationRelease('7cf02a6').then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.device.isTrackingApplicationRelease('7cf02a6', function(error, isEnabled) {
    console.log(isEnabled);
});

device.getTargetReleaseHash(uuidOrId) ⇒ Promise

Kind: static method of device
Summary: Get the hash of the currently tracked release for a specific device
Access: public
Fulfil: String - The release hash of the currently tracked release

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.getTargetReleaseHash('7cf02a6').then(function(release) {
    console.log(release);
});

Example 

balena.models.device.getTargetReleaseHash('7cf02a6', function(release) {
    console.log(release);
});

device.pinToRelease(uuidOrId, fullReleaseHashOrId) ⇒ Promise

Configures the device to run a particular release and not get updated when the current application release changes.

Kind: static method of device
Summary: Set a specific device to run a particular release
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)
fullReleaseHashOrId String \ Number the hash of a successful release (string) or id (number)

Example 

balena.models.device.pinToRelease('7cf02a6', 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

Example 

balena.models.device.pinToRelease(123, 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

Example 

balena.models.device.pinToRelease('7cf02a6', 'f7caf4ff80114deeaefb7ab4447ad9c661c50847', function(error) {
    if (error) throw error;
    ...
});

device.trackApplicationRelease(uuidOrId) ⇒ Promise

The device's current release will be updated with each new successfully built release.

Kind: static method of device
Summary: Configure a specific device to track the current application release
Access: public

Param Type Description
uuidOrId String \ Number device uuid (string) or id (number)

Example 

balena.models.device.trackApplicationRelease('7cf02a6').then(function() {
    ...
});

Example 

balena.models.device.trackApplicationRelease('7cf02a6', function(error) {
    if (error) throw error;
    ...
});

models.apiKey : object

Kind: static namespace of models

apiKey.create(name, [description]) ⇒ Promise

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

Kind: static method of apiKey
Summary: Creates a new user API key
Access: public
Fulfil: String - API key

Param Type Default Description
name String the API key name
[description] String the API key description

Example 

balena.models.apiKey.create(apiKeyName).then(function(apiKey) {
    console.log(apiKey);
});

Example 

balena.models.apiKey.create(apiKeyName, apiKeyDescription).then(function(apiKey) {
    console.log(apiKey);
});

Example 

balena.models.apiKey.create(apiKeyName, function(error, apiKey) {
    if (error) throw error;
    console.log(apiKey);
});

apiKey.getAll([options]) ⇒ Promise

Kind: static method of apiKey
Summary: Get all API keys
Access: public
Fulfil: Object[] - apiKeys

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.apiKey.getAll().then(function(apiKeys) {
    console.log(apiKeys);
});

Example 

balena.models.apiKey.getAll(function(error, apiKeys) {
    if (error) throw error;
    console.log(apiKeys);
});

apiKey.update(id, apiKeyInfo) ⇒ Promise

Kind: static method of apiKey
Summary: Update the details of an API key
Access: public

Param Type Description
id Number API key id
apiKeyInfo Object an object with the updated name or description

Example 

balena.models.apiKey.update(123, { name: 'updatedName' });

Example 

balena.models.apiKey.update(123, { description: 'updated description' });

Example 

balena.models.apiKey.update(123, { name: 'updatedName', description: 'updated description' });

Example 

balena.models.apiKey.update(123, { name: 'updatedName', description: 'updated description' }, function(error, apiKeys) {
    if (error) throw error;
    console.log(apiKeys);
});

apiKey.revoke(id) ⇒ Promise

Kind: static method of apiKey
Summary: Revoke an API key
Access: public

Param Type Description
id Number API key id

Example 

balena.models.apiKey.revoke(123);

Example 

balena.models.apiKey.revoke(123, function(error) {
    if (error) throw error;
});

models.key : object

Kind: static namespace of models

key.getAll([options]) ⇒ Promise

Kind: static method of key
Summary: Get all ssh keys
Access: public
Fulfil: Object[] - ssh keys

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.key.getAll().then(function(keys) {
    console.log(keys);
});

Example 

balena.models.key.getAll(function(error, keys) {
    if (error) throw error;
    console.log(keys);
});

key.get(id) ⇒ Promise

Kind: static method of key
Summary: Get a single ssh key
Access: public
Fulfil: Object - ssh key

Param Type Description
id String \ Number key id

Example 

balena.models.key.get(51).then(function(key) {
    console.log(key);
});

Example 

balena.models.key.get(51, function(error, key) {
    if (error) throw error;
    console.log(key);
});

key.remove(id) ⇒ Promise

Kind: static method of key
Summary: Remove ssh key
Access: public

Param Type Description
id String \ Number key id

Example 

balena.models.key.remove(51);

Example 

balena.models.key.remove(51, function(error) {
    if (error) throw error;
});

key.create(title, key) ⇒ Promise

Kind: static method of key
Summary: Create a ssh key
Access: public
Fulfil: Object - ssh key

Param Type Description
title String key title
key String the public ssh key

Example 

balena.models.key.create('Main', 'ssh-rsa AAAAB....').then(function(key) {
    console.log(key);
});

Example 

balena.models.key.create('Main', 'ssh-rsa AAAAB....', function(error, key) {
    if (error) throw error;
    console.log(key);
});

models.os : object

Kind: static namespace of models

os.getDownloadSize(deviceType, [version]) ⇒ Promise

Note! Currently only the raw (uncompressed) size is reported.

Kind: static method of os
Summary: Get OS download size estimate
Access: public
Fulfil: Number - OS image download size, in bytes.

Param Type Description
deviceType String device type slug
[version] String semver-compatible version or 'latest', defaults to 'latest'. The version must be the exact version number.

Example 

balena.models.os.getDownloadSize('raspberry-pi').then(function(size) {
    console.log('The OS download size for raspberry-pi', size);
});

balena.models.os.getDownloadSize('raspberry-pi', function(error, size) {
    if (error) throw error;
    console.log('The OS download size for raspberry-pi', size);
});

os.getSupportedVersions(deviceType) ⇒ Promise

Kind: static method of os
Summary: Get OS supported versions
Access: public
Fulfil: Object - the versions information, of the following structure:

  • versions - an array of strings, containing exact version numbers supported by the current environment
  • recommended - the recommended version, i.e. the most recent version that is not pre-release, can be null
  • latest - the most recent version, including pre-releases
  • default - recommended (if available) or latest otherwise
Param Type Description
deviceType String device type slug

Example 

balena.models.os.getSupportedVersions('raspberry-pi').then(function(osVersions) {
    console.log('Supported OS versions for raspberry-pi', osVersions);
});

balena.models.os.getSupportedVersions('raspberry-pi', function(error, osVersions) {
    if (error) throw error;
    console.log('Supported OS versions for raspberry-pi', osVersions);
});

os.getMaxSatisfyingVersion(deviceType, versionOrRange) ⇒ Promise

Kind: static method of os
Summary: Get the max OS version satisfying the given range
Access: public
Fulfil: String|null - the version number, or null if no matching versions are found

Param Type Description
deviceType String device type slug
versionOrRange String can be one of the exact version number, in which case it is returned if the version is supported, or null is returned otherwise, a semver-compatible range specification, in which case the most recent satisfying version is returned if it exists, or null is returned, 'latest' in which case the most recent version is returned, including pre-releases, 'recommended' in which case the recommended version is returned, i.e. the most recent version excluding pre-releases, which can be null if only pre-release versions are available, * 'default' in which case the recommended version is returned if available, or latest is returned otherwise. Defaults to 'latest'.

Example 

balena.models.os.getSupportedVersions('raspberry-pi').then(function(osVersions) {
    console.log('Supported OS versions for raspberry-pi', osVersions);
});

balena.models.os.getSupportedVersions('raspberry-pi', function(error, osVersions) {
    if (error) throw error;
    console.log('Supported OS versions for raspberry-pi', osVersions);
});

os.getLastModified(deviceType, [version]) ⇒ Promise

Kind: static method of os
Summary: Get the OS image last modified date
Access: public
Fulfil: Date - last modified date

Param Type Description
deviceType String device type slug
[version] String semver-compatible version or 'latest', defaults to 'latest'. Unsupported (unpublished) version will result in rejection. The version must be the exact version number. To resolve the semver-compatible range use balena.model.os.getMaxSatisfyingVersion.

Example 

balena.models.os.getLastModified('raspberry-pi').then(function(date) {
    console.log('The raspberry-pi image was last modified in ' + date);
});

balena.models.os.getLastModified('raspberrypi3', '2.0.0').then(function(date) {
    console.log('The raspberry-pi image was last modified in ' + date);
});

balena.models.os.getLastModified('raspberry-pi', function(error, date) {
    if (error) throw error;
    console.log('The raspberry-pi image was last modified in ' + date);
});

os.download(deviceType, [version]) ⇒ Promise

Kind: static method of os
Summary: Download an OS image
Access: public
Fulfil: ReadableStream - download stream

Param Type Description
deviceType String device type slug
[version] String semver-compatible version or 'latest', defaults to 'latest' Unsupported (unpublished) version will result in rejection. The version must be the exact version number. To resolve the semver-compatible range use balena.model.os.getMaxSatisfyingVersion.

Example 

balena.models.os.download('raspberry-pi').then(function(stream) {
    stream.pipe(fs.createWriteStream('foo/bar/image.img'));
});

balena.models.os.download('raspberry-pi', function(error, stream) {
    if (error) throw error;
    stream.pipe(fs.createWriteStream('foo/bar/image.img'));
});

os.getConfig(nameOrId, options) ⇒ Promise

Builds the config.json for a device in the given application, with the given options.

Note that an OS version is required. For versions < 2.7.8, config generation is only supported when using a session token, not an API key.

Kind: static method of os
Summary: Get an applications config.json
Access: public
Fulfil: Object - application configuration as a JSON object.

Param Type Default Description
nameOrId String \ Number application name (string) or id (number).
options Object OS configuration options to use.
options.version String Required: the OS version of the image.
[options.network] String 'ethernet' The network type that the device will use, one of 'ethernet' or 'wifi'.
[options.appUpdatePollInterval] Number How often the OS checks for updates, in minutes.
[options.wifiKey] String The key for the wifi network the device will connect to.
[options.wifiSsid] String The ssid for the wifi network the device will connect to.
[options.ip] String static ip address.
[options.gateway] String static ip gateway.
[options.netmask] String static ip netmask.

Example 

balena.models.os.getConfig('MyApp', { version: ''2.12.7+rev1.prod'' }).then(function(config) {
    fs.writeFile('foo/bar/config.json', JSON.stringify(config));
});

balena.models.os.getConfig(123, { version: ''2.12.7+rev1.prod'' }).then(function(config) {
    fs.writeFile('foo/bar/config.json', JSON.stringify(config));
});

balena.models.os.getConfig('MyApp', { version: ''2.12.7+rev1.prod'' }, function(error, config) {
    if (error) throw error;
    fs.writeFile('foo/bar/config.json', JSON.stringify(config));
});

models.config : object

Kind: static namespace of models

config.getAll() ⇒ Promise

Kind: static method of config
Summary: Get all configuration
Access: public
Fulfil: Object - configuration
Example 

balena.models.config.getAll().then(function(config) {
    console.log(config);
});

Example 

balena.models.config.getAll(function(error, config) {
    if (error) throw error;
    console.log(config);
});

config.getDeviceTypes() ⇒ Promise

Kind: static method of config
Summary: Get device types
Access: public
Fulfil: Object[] - device types
Example 

balena.models.config.getDeviceTypes().then(function(deviceTypes) {
    console.log(deviceTypes);
});

Example 

balena.models.config.getDeviceTypes(function(error, deviceTypes) {
    if (error) throw error;
    console.log(deviceTypes);
})

config.getDeviceOptions(deviceType) ⇒ Promise

Kind: static method of config
Summary: Get configuration/initialization options for a device type
Access: public
Fulfil: Object[] - configuration options

Param Type Description
deviceType String device type slug

Example 

balena.models.config.getDeviceOptions('raspberry-pi').then(function(options) {
    console.log(options);
});

Example 

balena.models.config.getDeviceOptions('raspberry-pi', function(error, options) {
    if (error) throw error;
    console.log(options);
});

models.release : object

Kind: static namespace of models

release.tags : object

Kind: static namespace of release

tags.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of tags
Summary: Get all release tags for an application
Access: public
Fulfil: Object[] - release tags

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.release.tags.getAllByApplication('MyApp').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAllByApplication(999999).then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAllByApplication('MyApp', function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.getAllByRelease(id, [options]) ⇒ Promise

Kind: static method of tags
Summary: Get all release tags for a release
Access: public
Fulfil: Object[] - release tags

Param Type Default Description
id Number release id
[options] Object {} extra pine options to use

Example 

balena.models.release.tags.getAllByRelease(123).then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAllByRelease(123, function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.getAll([options]) ⇒ Promise

Kind: static method of tags
Summary: Get all release tags
Access: public
Fulfil: Object[] - release tags

Param Type Default Description
[options] Object {} extra pine options to use

Example 

balena.models.release.tags.getAll().then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAll(function(error, tags) {
    if (error) throw error;
    console.log(tags)
});

tags.set(releaseId, tagKey, value) ⇒ Promise

Kind: static method of tags
Summary: Set a release tag
Access: public

Param Type Description
releaseId Number release id
tagKey String tag key
value String \ undefined tag value

Example 

balena.models.release.tags.set(123, 'EDITOR', 'vim');

Example 

balena.models.release.tags.set(123, 'EDITOR', 'vim', function(error) {
    if (error) throw error;
});

tags.remove(releaseId, tagKey) ⇒ Promise

Kind: static method of tags
Summary: Remove a release tag
Access: public

Param Type Description
releaseId Number release id
tagKey String tag key

Example 

balena.models.release.tags.remove(123, 'EDITOR');

Example 

balena.models.release.tags.remove(123, 'EDITOR', function(error) {
    if (error) throw error;
});

release.get(id, [options]) ⇒ Promise

Kind: static method of release
Summary: Get a specific release
Access: public
Fulfil: Object - release

Param Type Default Description
id Number release id
[options] Object {} extra pine options to use

Example 

balena.models.release.get(123).then(function(release) {
        console.log(release);
});

Example 

balena.models.release.get(123, function(error, release) {
        if (error) throw error;
        console.log(release);
});

release.getWithImageDetails(id, [options]) ⇒ Promise

This method does not map exactly to the underlying model: it runs a larger prebuilt query, and reformats it into an easy to use and understand format. If you want significantly more control, or to see the raw model directly, use release.get(id, options) instead.

Kind: static method of release
Summary: Get a specific release with the details of the images built
Access: public
Fulfil: Object - release with image details

Param Type Default Description
id Number release id
[options] Object {} a map of extra pine options
[options.release] Boolean {} extra pine options for releases
[options.image] Object {} extra pine options for images

Example 

balena.models.release.getWithImageDetails(123).then(function(release) {
        console.log(release);
});

Example 

balena.models.release.getWithImageDetails(123, { image: { $select: 'build_log' } })
.then(function(release) {
        console.log(release.images[0].build_log);
});

Example 

balena.models.release.getWithImageDetails(123, function(error, release) {
        if (error) throw error;
        console.log(release);
});

release.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of release
Summary: Get all releases from an application
Access: public
Fulfil: Object[] - releases

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.release.getAllByApplication('MyApp').then(function(releases) {
        console.log(releases);
});

Example 

balena.models.release.getAllByApplication(123).then(function(releases) {
        console.log(releases);
});

Example 

balena.models.release.getAllByApplication('MyApp', function(error, releases) {
        if (error) throw error;
        console.log(releases);
});

release.getLatestByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of release
Summary: Get the latest successful release for an application
Access: public
Fulfil: Object|undefined - release

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.release.getLatestByApplication('MyApp').then(function(releases) {
        console.log(releases);
});

Example 

balena.models.release.getLatestByApplication(123).then(function(releases) {
        console.log(releases);
});

Example 

balena.models.release.getLatestByApplication('MyApp', function(error, releases) {
        if (error) throw error;
        console.log(releases);
});

models.service : object

Kind: static namespace of models

service.var : object

Kind: static namespace of service

var.getAllByService(id, [options]) ⇒ Promise

Kind: static method of var
Summary: Get all variables for a service
Access: public
Fulfil: Object[] - service variables

Param Type Default Description
id Number service id
[options] Object {} extra pine options to use

Example 

balena.models.service.var.getAllByService(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.service.var.getAllByService(999999, function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

var.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of var
Summary: Get all service variables by application
Access: public
Fulfil: Object[] - service variables

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.service.var.getAllByApplication('MyApp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.service.var.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.service.var.getAllByApplication('MyApp', function(error, vars) {
    if (error) throw error;
    console.log(vars)
});

var.get(id, key) ⇒ Promise

Kind: static method of var
Summary: Get the value of a specific service variable
Access: public
Fulfil: String|undefined - the variable value (or undefined)

Param Type Description
id Number service id
key String variable name

Example 

balena.models.service.var.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.service.var.get(999999, 'VAR', function(error, value) {
    if (error) throw error;
    console.log(value)
});

var.set(id, key, value) ⇒ Promise

Kind: static method of var
Summary: Set the value of a specific service variable
Access: public

Param Type Description
id Number service id
key String variable name
value String variable value

Example 

balena.models.service.var.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.service.var.set(999999, 'VAR', 'newvalue', function(error) {
    if (error) throw error;
    ...
});

var.remove(id, key) ⇒ Promise

Kind: static method of var
Summary: Clear the value of a specific service variable
Access: public

Param Type Description
id Number service id
key String variable name

Example 

balena.models.service.var.remove(999999, 'VAR').then(function() {
    ...
});

Example 

balena.models.service.var.remove(999999, 'VAR', function(error) {
    if (error) throw error;
    ...
});

service.getAllByApplication(nameOrId, [options]) ⇒ Promise

Kind: static method of service
Summary: Get all services from an application
Access: public
Fulfil: Object[] - services

Param Type Default Description
nameOrId String \ Number application name (string) or id (number)
[options] Object {} extra pine options to use

Example 

balena.models.service.getAllByApplication('MyApp').then(function(services) {
        console.log(services);
});

Example 

balena.models.service.getAllByApplication(123).then(function(services) {
        console.log(services);
});

Example 

balena.models.service.getAllByApplication('MyApp', function(error, services) {
        if (error) throw error;
        console.log(services);
});

models.image : object

Kind: static namespace of models

image.get(id, [options]) ⇒ Promise

Kind: static method of image
Summary: Get a specific image
Access: public
Fulfil: Object - image

Param Type Default Description
id Number image id
[options] Object {} extra pine options to use

Example 

balena.models.image.get(123).then(function(image) {
        console.log(image);
});

Example 

balena.models.image.get(123, function(error, image) {
        if (error) throw error;
        console.log(image);
});

image.getLogs(id) ⇒ Promise

Kind: static method of image
Summary: Get the logs for an image
Access: public
Fulfil: string - logs

Param Type Description
id Number image id

Example 

balena.models.image.getLogs(123).then(function(logs) {
        console.log(logs);
});

Example 

balena.models.image.getLogs(123, function(error, logs) {
        if (error) throw error;
        console.log(logs);
});

models.billing : object

Note! The billing methods are available on Balena.io exclusively.

Kind: static namespace of models

billing.getAccount() ⇒ Promise

Kind: static method of billing
Summary: Get the user's billing account
Access: public
Fulfil: Object - billing account
Example 

balena.models.billing.getAccount().then(function(billingAccount) {
    console.log(billingAccount);
});

Example 

balena.models.billing.getAccount(function(error, billingAccount) {
    if (error) throw error;
    console.log(billingAccount);
});

billing.getPlan() ⇒ Promise

Kind: static method of billing
Summary: Get the current billing plan
Access: public
Fulfil: Object - billing plan
Example 

balena.models.billing.getPlan().then(function(billingPlan) {
    console.log(billingPlan);
});

Example 

balena.models.billing.getPlan(function(error, billingPlan) {
    if (error) throw error;
    console.log(billingPlan);
});

billing.getBillingInfo() ⇒ Promise

Kind: static method of billing
Summary: Get the current billing information
Access: public
Fulfil: Object - billing information
Example 

balena.models.billing.getBillingInfo().then(function(billingInfo) {
    console.log(billingInfo);
});

Example 

balena.models.billing.getBillingInfo(function(error, billingInfo) {
    if (error) throw error;
    console.log(billingInfo);
});

billing.updateBillingInfo() ⇒ Promise

Kind: static method of billing
Summary: Update the current billing information
Access: public
Fulfil: Object - billing information

Type Description
Object an object containing a billing info token_id

Example 

balena.models.billing.updateBillingInfo({ token_id: 'xxxxxxx' }).then(function(billingInfo) {
    console.log(billingInfo);
});

Example 

balena.models.billing.updateBillingInfo({ token_id: 'xxxxxxx' }, function(error, billingInfo) {
    if (error) throw error;
    console.log(billingInfo);
});

billing.getInvoices() ⇒ Promise

Kind: static method of billing
Summary: Get the available invoices
Access: public
Fulfil: Object - invoices
Example 

balena.models.billing.getInvoices().then(function(invoices) {
    console.log(invoices);
});

Example 

balena.models.billing.getInvoices(function(error, invoices) {
    if (error) throw error;
    console.log(invoices);
});

billing.downloadInvoice() ⇒ Promise

Kind: static method of billing
Summary: Download a specific invoice
Access: public
Fulfil: Blob|ReadableStream - blob on the browser, download stream on node

Type Description
String an invoice number

Example 

# Browser
balena.models.billing.downloadInvoice('0000').then(function(blob) {
    console.log(blob);
});
# Node
balena.models.billing.downloadInvoice('0000').then(function(stream) {
    stream.pipe(fs.createWriteStream('foo/bar/invoice-0000.pdf'));
});

balena.auth : object

Kind: static namespace of balena

auth.twoFactor : object

Kind: static namespace of auth

twoFactor.isEnabled() ⇒ Promise

Kind: static method of twoFactor
Summary: Check if two factor authentication is enabled
Access: public
Fulfil: Boolean - whether 2fa is enabled
Example 

balena.auth.twoFactor.isEnabled().then(function(isEnabled) {
    if (isEnabled) {
        console.log('2FA is enabled for this account');
    }
});

Example 

balena.auth.twoFactor.isEnabled(function(error, isEnabled) {
    if (error) throw error;

    if (isEnabled) {
        console.log('2FA is enabled for this account');
    }
});

twoFactor.isPassed() ⇒ Promise

Kind: static method of twoFactor
Summary: Check if two factor authentication challenge was passed
Access: public
Fulfil: Boolean - whether 2fa challenge was passed
Example 

balena.auth.twoFactor.isPassed().then(function(isPassed) {
    if (isPassed) {
        console.log('2FA challenge passed');
    }
});

Example 

balena.auth.twoFactor.isPassed(function(error, isPassed) {
    if (error) throw error;

    if (isPassed) {
        console.log('2FA challenge passed');
    }
});

twoFactor.challenge(code) ⇒ Promise

Kind: static method of twoFactor
Summary: Challenge two factor authentication
Access: public

Param Type Description
code String code

Example 

balena.auth.twoFactor.challenge('1234');

Example 

balena.auth.twoFactor.challenge('1234', function(error) {
    if (error) throw error;
});

auth.whoami() ⇒ Promise

This will only work if you used module:balena.auth.login to log in.

Kind: static method of auth
Summary: Return current logged in username
Access: public
Fulfil: (String|undefined) - username, if it exists
Example 

balena.auth.whoami().then(function(username) {
    if (!username) {
        console.log('I\'m not logged in!');
    } else {
        console.log('My username is:', username);
    }
});

Example 

balena.auth.whoami(function(error, username) {
    if (error) throw error;

    if (!username) {
        console.log('I\'m not logged in!');
    } else {
        console.log('My username is:', username);
    }
});

auth.authenticate(credentials) ⇒ Promise

You should use module:balena.auth.login when possible, as it takes care of saving the token and email as well.

Notice that if credentials contains extra keys, they'll be discarted by the server automatically.

Kind: static method of auth
Summary: Authenticate with the server
Access: protected
Fulfil: String - session token

Param Type Description
credentials Object in the form of email, password
credentials.email String the email
credentials.password String the password

Example 

balena.auth.authenticate(credentials).then(function(token) {
    console.log('My token is:', token);
});

Example 

balena.auth.authenticate(credentials, function(error, token) {
    if (error) throw error;
    console.log('My token is:', token);
});

auth.login(credentials) ⇒ Promise

If the login is successful, the token is persisted between sessions.

Kind: static method of auth
Summary: Login
Access: public

Param Type Description
credentials Object in the form of email, password
credentials.email String the email
credentials.password String the password

Example 

balena.auth.login(credentials);

Example 

balena.auth.login(credentials, function(error) {
    if (error) throw error;
});

auth.loginWithToken(authToken) ⇒ Promise

Login to balena with a session token or api key instead of with credentials.

Kind: static method of auth
Summary: Login with a token or api key
Access: public

Param Type Description
authToken String the auth token

Example 

balena.auth.loginWithToken(authToken);

Example 

balena.auth.loginWithToken(authToken, function(error) {
    if (error) throw error;
});

auth.isLoggedIn() ⇒ Promise

Kind: static method of auth
Summary: Check if you're logged in
Access: public
Fulfil: Boolean - is logged in
Example 

balena.auth.isLoggedIn().then(function(isLoggedIn) {
    if (isLoggedIn) {
        console.log('I\'m in!');
    } else {
        console.log('Too bad!');
    }
});

Example 

balena.auth.isLoggedIn(function(error, isLoggedIn) {
    if (error) throw error;

    if (isLoggedIn) {
        console.log('I\'m in!');
    } else {
        console.log('Too bad!');
    }
});

auth.getToken() ⇒ Promise

This will only work if you used module:balena.auth.login to log in.

Kind: static method of auth
Summary: Get current logged in user's raw API key or session token
Access: public
Fulfil: String - raw API key or session token
Example 

balena.auth.getToken().then(function(token) {
    console.log(token);
});

Example 

balena.auth.getToken(function(error, token) {
    if (error) throw error;
    console.log(token);
});

auth.getUserId() ⇒ Promise

This will only work if you used module:balena.auth.login to log in.

Kind: static method of auth
Summary: Get current logged in user's id
Access: public
Fulfil: Number - user id
Example 

balena.auth.getUserId().then(function(userId) {
    console.log(userId);
});

Example 

balena.auth.getUserId(function(error, userId) {
    if (error) throw error;
    console.log(userId);
});

auth.getEmail() ⇒ Promise

This will only work if you used module:balena.auth.login to log in.

Kind: static method of auth
Summary: Get current logged in user's email
Access: public
Fulfil: String - user email
Example 

balena.auth.getEmail().then(function(email) {
    console.log(email);
});

Example 

balena.auth.getEmail(function(error, email) {
    if (error) throw error;
    console.log(email);
});

auth.logout() ⇒ Promise

Kind: static method of auth
Summary: Logout
Access: public
Example 

balena.auth.logout();

Example 

balena.auth.logout(function(error) {
    if (error) throw error;
});

auth.register([credentials]) ⇒ Promise

Kind: static method of auth
Summary: Register a user account
Access: public
Fulfil: String - session token

Param Type Default Description
[credentials] Object {} in the form of username, password and email
credentials.email String the email
credentials.password String the password

Example 

balena.auth.register({
    email: 'johndoe@gmail.com',
    password: 'secret'
}).then(function(token) {
    console.log(token);
});

Example 

balena.auth.register({
    email: 'johndoe@gmail.com',
    password: 'secret'
}, function(error, token) {
    if (error) throw error;
    console.log(token);
});

balena.logs : object

Kind: static namespace of balena

logs.subscribe(uuidOrId, [options]) ⇒ Promise

Connects to the stream of devices logs, returning a LogSubscription, which can be used to listen for logs as they appear, line by line.

Kind: static method of logs
Summary: Subscribe to device logs
Access: public
Fulfil: LogSubscription
Todo

  • [ ] We should consider making this a readable stream.
Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object options
[options.count] Number \ 'all' 0 number of historical messages to include (or 'all')

Example 

balena.logs.subscribe('7cf02a6').then(function(logs) {
    logs.on('line', function(line) {
        console.log(line);
    });
});

Example 

balena.logs.subscribe(123).then(function(logs) {
    logs.on('line', function(line) {
        console.log(line);
    });
});

Example 

balena.logs.subscribe('7cf02a6', function(error, logs) {
    if (error) throw error;

    logs.on('line', function(line) {
        console.log(line);
    });
});

logs.history(uuidOrId, [options]) ⇒ Promise

Get an array of the latest log messages for a given device.

Kind: static method of logs
Summary: Get device logs history
Access: public
Fulfil: Object[] - history lines

Param Type Default Description
uuidOrId String \ Number device uuid (string) or id (number)
[options] Object options
[options.count] Number \ 'all' 1000 number of log messages to return (or 'all')

Example 

balena.logs.history('7cf02a6').then(function(lines) {
    lines.forEach(function(line) {
        console.log(line);
    });
});

Example 

balena.logs.history(123).then(function(lines) {
    lines.forEach(function(line) {
        console.log(line);
    });
});

Example 

balena.logs.history('7cf02a6', { count: 20 }, function(error, lines) {
    if (error) throw error;

    lines.forEach(function(line) {
        console.log(line);
    });
});

logs.LogSubscription : EventEmitter

The log subscription emits events as log data arrives. You can get a LogSubscription for a given device by calling balena.logs.subscribe(deviceId)

Kind: static typedef of logs

LogSubscription.unsubscribe()

Disconnect from the logs feed and stop receiving any future events on this emitter.

Kind: static method of LogSubscription
Summary: Unsubscribe from device logs
Access: public
Example 

logs.unsubscribe();

"line"

Kind: event emitted by LogSubscription
Summary: Event fired when a new line of log output is available
Example 

logs.on('line', function(line) {
    console.log(line);
});

"error"

Kind: event emitted by LogSubscription
Summary: Event fired when an error has occured reading the device logs
Example 

logs.on('error', function(error) {
    console.error(error);
});

balena.settings : object

Kind: static namespace of balena

settings.get([key]) ⇒ Promise

Kind: static method of settings
Summary: Get a single setting. Only implemented in Node.js
Access: public
Fulfil: * - setting value

Param Type Description
[key] String setting key

Example 

balena.settings.get('apiUrl').then(function(apiUrl) {
    console.log(apiUrl);
});

Example 

balena.settings.get('apiUrl', function(error, apiUrl) {
    if (error) throw error;
    console.log(apiUrl);
});

settings.getAll() ⇒ Promise

Kind: static method of settings
Summary: Get all settings Only implemented in Node.js
Access: public
Fulfil: Object - settings
Example 

balena.settings.getAll().then(function(settings) {
    console.log(settings);
});

Example 

balena.settings.getAll(function(error, settings) {
    if (error) throw error;
    console.log(settings);
});

balena.setSharedOptions()

Set options that are used by calls to balena.fromSharedOptions(). The options accepted are the same as those used in the main SDK factory function. If you use this method, it should be called as soon as possible during app startup and before any calls to fromSharedOptions() are made.

Kind: static method of balena
Summary: Set shared default options
Access: public
Params: Object opts - The shared default options
Example 

balena.setSharedOptions({
    apiUrl: 'https://api.balena-cloud.com/',
    imageMakerUrl: 'https://img.balena-cloud.com/',
    isBrowser: true,
});

balena.fromSharedOptions()

Create an SDK instance using shared default options set using the setSharedOptions() method. If options have not been set using this method, then this method will use the same defaults as the main SDK factory function.

Kind: static method of balena
Summary: Create an SDK instance using shared default options
Access: public
Params: Object opts - The shared default options
Example 

const sdk = balena.fromSharedOptions();