SecondScreen Module

Version 0.9.0

Overview

Methods for communicating with second screen devices

OpenRPC

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

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

Table of Contents

 

Usage

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

import { SecondScreen } from '@firebolt-js/sdk'

Methods

device

Get the broadcasted id for the device

function device(type?: string): Promise<string>

Parameters:

Param Type Required Summary
type string false The type of second screen protocol, e.g. “dial”

Promise resolution:

Type Description
string the device id

Examples

Default Example

JavaScript:

import { SecondScreen } from '@firebolt-js/sdk'

SecondScreen.device(null)
    .then(deviceId => {
        console.log(deviceId)
    })

Value of deviceId:

"device-id"
JSON-RPC:

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "device-id"
}

friendlyName

Get the broadcasted friendly name for the device

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

function friendlyName(): Promise<string>

Promise resolution:

Type Description
string the device friendly-name

Examples

Default Example

JavaScript:

import { SecondScreen } from '@firebolt-js/sdk'

SecondScreen.friendlyName()
    .then(friendlyName => {
        console.log(friendlyName)
    })

Value of friendlyName:

"Living Room"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "secondscreen.friendlyName",
  "params": {}
}

Response:

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

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

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

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for friendlyName changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with SecondScreen.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
friendlyName string Yes the device friendly-name

Examples

Default Example

JavaScript:

import { SecondScreen } from '@firebolt-js/sdk'

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

value of friendlyName:

"Living Room"
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "secondscreen.onFriendlyNameChanged",
  "params": {
    "listen": true
  }
}

Response:

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

listen

Listen for events from this module.

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

SecondScreen.listen(event: string, (data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. SecondScreen.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

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

SecondScreen.listen((event: string, data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. SecondScreen.clear(id)

See Listening for events for more information and examples.

once

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:

SecondScreen.once(event: string, (data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. SecondScreen.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

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

SecondScreen.once((event: string, data: any) => void): Promise<number>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
number Listener ID to clear the callback method and stop receiving the event, e.g. SecondScreen.clear(id)

See Listening for events for more information and examples.

protocols

Get the supported second screen discovery protocols

function protocols(): Promise<BooleanMap>

Promise resolution:

Type Description
BooleanMap the supported protocols

Examples

Default Example

JavaScript:

import { SecondScreen } from '@firebolt-js/sdk'

SecondScreen.protocols()
    .then(protocols => {
        console.log(protocols)
    })

Value of protocols:

{
  "dial1.7": true
}
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "secondscreen.protocols",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "dial1.7": true
  }
}

Events

closeRequest

Listen to the closeRequest event

See also: listen(), once(), clear().

Event value:

Type Description
SecondScreenEvent An a message notification from a second screen device

Examples

Default Example:

JavaScript:

import { SecondScreen } from '@firebolt-js/sdk'

SecondScreen.listen('closeRequest', closeRequestEvent => {
  console.log(closeRequestEvent)
})

Value of closeRequestEvent

{
  "type": "dial",
  "version": "1.7"
}
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "secondscreen.onCloseRequest",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "dial",
    "version": "1.7"
  }
}

launchRequest

Listen to the launchRequest event

See also: listen(), once(), clear().

Event value:

Type Description
SecondScreenEvent An a message notification from a second screen device

Examples

Default Example:

JavaScript:

import { SecondScreen } from '@firebolt-js/sdk'

SecondScreen.listen('launchRequest', launchRequestEvent => {
  console.log(launchRequestEvent)
})

Value of launchRequestEvent

{
  "type": "dial",
  "version": "1.7",
  "data": "{\"code\":\"AQDPQZiQcb3KQ7gY7yy5tHTMbbkGHR9Zjp-KL53H3eKBZIeAt7O9UKYPu6B21l2UZVmIqkFXDXBmXvK4g2e3EgZtjMNmKPsTltgnRl95DImtOXjSpWtTjSaOkW4w1kZKUTwLKdwVWTzBVH8ERHorvLU6vCGOVHxXt65LNwdl5HKRweShVC1V9QsyvRnQS61ov0UclmrH_xZML2Bt-Q-rZFjey5MjwupIb4x4f53XUJMhjHpDHoIUKrjpdPDQvK2a\",\"friendlyName\":\"Operator_TX061AEI\",\"UDN\":\"608fef11-2800-482a-962b-23a6690c93c1\"}"
}
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "secondscreen.onLaunchRequest",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "dial",
    "version": "1.7",
    "data": "{\"code\":\"AQDPQZiQcb3KQ7gY7yy5tHTMbbkGHR9Zjp-KL53H3eKBZIeAt7O9UKYPu6B21l2UZVmIqkFXDXBmXvK4g2e3EgZtjMNmKPsTltgnRl95DImtOXjSpWtTjSaOkW4w1kZKUTwLKdwVWTzBVH8ERHorvLU6vCGOVHxXt65LNwdl5HKRweShVC1V9QsyvRnQS61ov0UclmrH_xZML2Bt-Q-rZFjey5MjwupIb4x4f53XUJMhjHpDHoIUKrjpdPDQvK2a\",\"friendlyName\":\"Operator_TX061AEI\",\"UDN\":\"608fef11-2800-482a-962b-23a6690c93c1\"}"
  }
}

Additional events

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

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

JavaScript RPC Payload Documentation
friendlyNameChanged onFriendlyNameChanged string friendlyName
 
Go To Top