Device Module

Version 0.1.0-alpha.4

A module for managing device settings.

Firebolt APIs are maintained in the rdkcentral/firebolt-manage-sdk.git GitHub repository.

You can see this API in the device.json OpenRPC JSON-Schema document.

• Overview

• OpenRPC

• Usage

• Methods

  • developerMode
  • listen
  • name
  • once
  • postalCode
  • provide
  • provision
  • Additional Methods

• Events

  • Additional Events

• Provider Interfaces

  • DeviceSettingsProvider

• Schemas

To use the Device module, you can import it into your project from the Firebolt SDK:

import { Device } from '@firebolt-js/manage-sdk'

Whether or not developer mode is enabled.

To get the value, call the method with no parameters:

function developerMode(): Promise<boolean>

Promise resolution:

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.developerMode()
    .then(developerMode => {
        console.log(developerMode)
    })

Value of developerMode:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.developerMode",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

To set the value, pass in the new value as the only parameter:

function developerMode(value: boolean): Promise<void>

Parameters:

Promise resolution:

Examples

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.developerMode(true)
    .then(response => {
        // property value has been set
    })

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.setDeveloperMode",
  "params": {
    "value": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function developerMode(subscriber: (developerMode: boolean) => void): Promise<boolean>

Parameters:

Promise resolution:

Callback parameters:

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.developerMode(developerMode => {
  // property value was changed
  console.log(developerMode)
}).then(listenerId => {
  // you can clear this listener w/ Device.clear(listenerId)
})

value of developerMode:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.onDeveloperModeChanged",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

Listen for events from this module.

To listen to a specific event pass the event name as the first parameter:

Device.listen(event: string, (data: any) => void): Promise<bigint>

Parameters:

Promise resolution:

Callback parameters:

To listen to all events from this module pass only a callback, without specifying an event name:

Device.listen((event: string, data: any) => void): Promise<bigint>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

The user-assigned name of this device.

To get the value, call the method with no parameters:

function name(): Promise<string>

Promise resolution:

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.name()
    .then(name => {
        console.log(name)
    })

Value of name:

"Living Room"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.name",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Living Room"
}

To set the value, pass in the new value as the only parameter:

function name(value: string): Promise<void>

Parameters:

Promise resolution:

Examples

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.name("Living Room")
    .then(response => {
        // property value has been set
    })

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.setName",
  "params": {
    "value": "Living Room"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function name(subscriber: (name: string) => void): Promise<boolean>

Parameters:

Promise resolution:

Callback parameters:

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.name(name => {
  // property value was changed
  console.log(name)
}).then(listenerId => {
  // you can clear this listener w/ Device.clear(listenerId)
})

value of name:

"Living Room"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.onNameChanged",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Living Room"
}

Listen for only one occurance of an event from this module. The callback will be cleared after one event.

To listen to a specific event pass the event name as the first parameter:

Device.once(event: string, (data: any) => void): Promise<bigint>

Parameters:

Promise resolution:

Callback parameters:

To listen to all events from this module pass only a callback, without specifying an event name:

Device.once((event: string, data: any) => void): Promise<bigint>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

The user-asigned postal code of this device.

To get the value, call the method with no parameters:

function postalCode(): Promise<string>

Promise resolution:

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.postalCode()
    .then(code => {
        console.log(code)
    })

Value of code:

"19103"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.postalCode",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "19103"
}

To set the value, pass in the new value as the only parameter:

function postalCode(value: string): Promise<void>

Parameters:

Promise resolution:

Examples

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.postalCode("19103")
    .then(response => {
        // property value has been set
    })

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.setPostalCode",
  "params": {
    "value": "19103"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function postalCode(subscriber: (code: string) => void): Promise<boolean>

Parameters:

Promise resolution:

Callback parameters:

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.postalCode(code => {
  // property value was changed
  console.log(code)
}).then(listenerId => {
  // you can clear this listener w/ Device.clear(listenerId)
})

value of code:

"19103"

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.onPostalCodeChanged",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "19103"
}

Register to provide a capability from this module.

See Provider Interfaces, for more info.

function provide(provider: object | class): Promise<void>

Parameters:

Promise resolution:

void

Used by a distributor to push provision info to firebolt.

function provision(accountId: string, deviceId: string): Promise<void>

Parameters:

Promise resolution:

void

Examples

Default Example

JavaScript:

import { Device } from '@firebolt-js/manage-sdk'

Device.provision("12345678910", "987654321111")
    .then(result => {
        console.log(result)
    })

Value of result:

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "device.provision",
  "params": {
    "accountId": "12345678910",
    "deviceId": "987654321111"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

The following methods are documented as part of a related set of method APIs.

For more information, follow the links under the “Documentation” column.

The following events are documented as part of a related set of method APIs.

For more information, follow the links under the “Documentation” column.

Providers are interfaces that your app can implement in order to provide certain capabilties back to the platform.

To register a provider, use the provide() method.

Every provider interface method has the following signature:

(parameters: object | void, session: ProviderSession) => {}

ProviderSession has the following interface:

interface ProviderSession {
    correlationId(): string        // Returns the correlation id of the current provider session
}

The provider interface for the xrn:firebolt:capability:settings:device capability.

interface DeviceSettingsProvider {
	name(parameters?: object, session?: ProviderSession): Promise<string>
	postalCode(parameters?: object, session?: ProviderSession): Promise<string>
}

Usage:

Device.provide('xrn:firebolt:capability:settings:device', provider: DeviceSettingsProvider | object)

Request the user-assigned name of this device from the device settings provider.

function name(parameters?: object, session?: ProviderSession): Promise<string>

Provider methods always have two arguments:

Promise resolution:

Request the user-asigned postal code of this device from the device settings provider.

function postalCode(parameters?: object, session?: ProviderSession): Promise<string>

Provider methods always have two arguments:

Promise resolution:

Register your app to provide the xrn:firebolt:capability:settings:device capability.

import { Device } from '@firebolt-js/manage-sdk'

class MyDeviceSettingsProvider {

    async name(parameters, session) {
        return await Promise.resolve("Living Room")
    }

    async postalCode(parameters, session) {
        return await Promise.resolve("19103")
    }

}

Device.provide('xrn:firebolt:capability:settings:device', new MyDeviceSettingsProvider())

{
    "id": 1,
    "method": "onRequestName",
    "params": {
        "listen": true
    }
}

{
    "id": 2,
    "method": "onRequestPostalCode",
    "params": {
        "listen": true
    }
}

{
    "id": 1,
    "result": {
        "listening": true,
        "event": "Device.onRequestName"
    }            
 
}

{
    "id": 2,
    "result": {
        "listening": true,
        "event": "Device.onRequestPostalCode"
    }            
 
}

{
    "id": 1,
    "result": {
        "correlationId": "123",
        "parameters": null
    }
}

{
    "id": 3,
    "method": "nameResponse",
    "params": {
        "response": {
            "correlationId": "123",
            "result": "Living Room"
        }
    }
}

{
    "id": 3,
    "result": true
}

{
    "id": 2,
    "result": {
        "correlationId": "123",
        "parameters": null
    }
}

{
    "id": 4,
    "method": "postalCodeResponse",
    "params": {
        "response": {
            "correlationId": "123",
            "result": "19103"
        }
    }
}

{
    "id": 4,
    "result": true
}