Device

Device

Class for interacting with a Device returned from a plugin.

Constructor

new Device(device, plugin, baseURLopt)

Description:

  • Instantiate a device.

Source:
Parameters:
Name Type Attributes Description
device object

Device object as received from the API

Properties
Name Type Attributes Description
id string

URL safe device identified, this can often be hashed or encoded and should be considered opaque.
raw_id string <nullable>

When possible, if the id is of some encoded or hashed type, this is the underlying value and can be shown to users.
name string

Human friendly name of the device.
plugin object

Plugin serviced by this device.
baseURL string <optional>

Protocol, domain, and port for the service.

Methods

can(method)

Description:

  • Will throw an exception if a plugin cannot perform the provided RPC command

Source:
Parameters:
Name Type Description
method string

The JSON RPC method to check.

canDoOne(methods)

Description:

  • Will throw an exception if the plugin cannot performa at least one of the provided JSON RPC commandss

Source:
Parameters:
Name Type Description
methods Array.<string>

The JSON RPC methods to check.

(async) cancel(timeoutopt, nullable) → {object}

Description:

  • Will attempt to cancel any active long-running operation

Source:
Example
const {status} = await device.cancel()
Parameters:
Name Type Attributes Description
timeout Number <optional>
<nullable>

If provided, will attempt to wait at least this long (in seconds) for the operation to be cancelled before returning a response. By default this endpoint will request a cancellation and return immediately, however if you'd like to block, waiting for the device to be ready before attempting another operation you may supply this timeout.
Returns:

Cancellation status

Type
object

(async) captureAsBase64(captureOptopt) → {string}

Description:

  • Take full capture from the specified device and return a base64 encoded string of the image that can be used with a Data URL (Async/Await version)

Source:
Example
// Add the base64 string as a Data URL to an img tag and append to
// the document's body
const base64 = await device.captureAsBase64()
const img = document.createElement('img')
img.src = 'data:image/jpeg;base64,' + base64
document.body.appendChild(img)
Parameters:
Name Type Attributes Description
captureOpt CaptureOptions <optional>

Additional options for capturing a frame.
Returns:

Base64 Encoded image

Type
string

(async) captureAsBlob(captureOptopt) → {object}

Description:

  • Take full capture from the specified device and return a Blob that can be used with a FileReader (Async/Await version)

Source:
Example
// Load the blob into FileReader and append to the document's body
const blob = await device.captureAsBlob()
const reader = new FileReader()
reader.onload = event => {
  const img = document.createElement('img')
  img.src = event.target.result
  document.body.appendChild(img)
}
reader.readAsDataURL(blob)
Parameters:
Name Type Attributes Description
captureOpt CaptureOptions <optional>

Additional options for capturing a frame.
Returns:

Blob

Type
object

(async) captureAsObjectURL(captureOptopt) → {string}

Description:

  • Take full capture from the specified device and return an ObjectURL that can be set directly on an img tag's src attribute. Note that URLs created by this method should be revoked when they are no longer needed. (Async/Await version)

Source:
Example
// Load the blob into FileReader and append to the document's body
const blob = await device.captureAsBlob()
const reader = new FileReader()
reader.onload = event => {
  const img = document.createElement('img')
  img.src = event.target.result
  document.body.appendChild(img)
}
reader.readAsDataURL(blob)
Parameters:
Name Type Attributes Description
captureOpt CaptureOptions <optional>

Additional options for capturing a frame.
Returns:
Type
string

(async) clear(backlightopt) → {object}

Description:

  • Clear a device's display. (Async/Await version)

Source:
Example
console.log(await await device.clear())
Parameters:
Name Type Attributes Description
backlight boolean <optional>

If provided and set to true, will enable backlight. If false, it will be disabled. If unspecified no action will be taken on the backlight.
Returns:

Status of the clear operation

Type
object

(async) displayObjects(objects, sceneOptopt, signalopt)

Description:

  • If any Objects are Buttons, the method will wait for one to be clicked and will then return results. The format of the Array of Objects, the response structure, and the scene options are plugin specific.

Source:
Parameters:
Name Type Attributes Description
objects Array.<Object>

An array of drawable objects to display.
sceneOpt Object <optional>

Options for configuring the scene.

Properties
Name Type Attributes Description
clear boolean <optional>

If true, the display will be cleared before adding the Objects.
backlight Object <optional>

If true, the backlight will be enabled before adding the Objects.
signal AbortSignal <optional>

An AbortSignal obtained from an AbortController allowing the request to be aborted. If the request is aborted or the HTTP connection is closed for any reason before a user has interacted with the display, the device state will be reset and the screen will be cleared.

(async) frameAsBase64(millisopt, captureOptopt) → {string}

Description:

  • This method will startup the live feed if necessary and wait for it to initialize before returning a frame. Subsequent calls will return the next available frame. You must manually stop the live feed if you are using this method.

    The frame returned will be a base64 encoded string of the image that can be used with a Data URL

    If implementing a real-time preview, it is highly recommended to use the stream endpoint which will stream a Motion JPEG.

Source:
See:
  • streamUrl
  • stopFeed
Example
// Add the base64 string as a Data URL to an img tag and append to
// the document's body
const base64 = await device.frameAsBase64()
const img = document.createElement('img')
img.src = 'data:image/jpeg;base64,' + base64
document.body.appendChild(img)
Parameters:
Name Type Attributes Default Description
millis number <optional>
 500

Milliseconds to wait if feed is not ready
captureOpt CaptureOptions <optional>

Additional options for capturing a frame.
Returns:

Base64 Encoded image

Type
string

(async) frameAsBlob(captureOptopt, millisopt) → {object}

Description:

  • This method will startup the live feed if necessary and wait for it to initialize before returning a frame. Subsequent calls will return the next available frame. You must manually stop the live feed if you are using this method.

    The frame returned will be a Blob that can be used with a FileReader

    If implementing a real-time preview, it is highly recommended to use the stream endpoint which will stream a Motion JPEG.

Source:
See:
  • streamUrl
  • stopFeed
Example
// Load the blob into FileReader and append to the document's body
const blob = await device.frameAsBlob()
const reader = new FileReader()
reader.onload = event => {
  const img = document.createElement('img')
  img.src = event.target.result
  document.body.appendChild(img)
}
reader.readAsDataURL(blob)
Parameters:
Name Type Attributes Default Description
captureOpt CaptureOptions <optional>

Additional options for capturing a frame.
millis number <optional>
 500

Milliseconds to wait if feed is not ready
Returns:

Blob

Type
object

(async) info() → {object}

Description:

  • Returns detailed information about a device.

Source:
Example
const info = await device.info()
Returns:

Device info

Type
object

(async) reset(depthopt, nullable) → {object}

Description:

  • Used to restart a device or reset its state

Source:
Example
const {status} = await device.reset()
Parameters:
Name Type Attributes Default Description
depth Number <optional>
<nullable>
 0

Some devices have several abstractions layers that can be reset separately. For example, the entire device might be rebooted or an outstanding operation could be cancelled.
Returns:

Reset status

Type
object

(async) stopFeed() → {object}

Description:

  • Stop the live feed if it is running. (Async/Await version)

Source:
Example
// Plugin is now running it's live feed in a background thread
const blob = await device.frameAsBlob()
// Live feed is now stopping
console.log(await device.stopFeed())
Returns:

Status of the stop operation

Type
object

streamUrl(streamOptopt) → {string}

Description:

  • the URL returned from this endpoint can be attached to an img tag's src attribute. The device's live stream will be started and begin streaming to the img tag as a Motion JPEG stream. If the src is changed, the img removed from the DOM, or client disconnected for any reason, the live feed will automatically be stopped.

Source:
Example
const img = document.createElement('img')
img.src = device.streamUrl()
document.body.appendChild(img)
Parameters:
Name Type Attributes Description
streamOpt StreamOptions <optional>

Additional options for streaming.
Returns:

stream endpoint URL

Type
string