Documentation

Mistake on this page? Email us

The API can be initalized with a .env file in the working directory with the following values

MBED_CLOUD_SDK_API_KEY=

and optionally

MBED_CLOUD_SDK_HOST= (defaults to https://api.us-east-1.mbedcloud.com)

OR

This API is initialized with ConnectionOptions.

Notification channels

Some methods on connected device resources (e.g. resource.getValue()) and most events (e.g. resource.on("notification")) require a notification channel to be set up before they will work.

There are two options for setting up a notification channel:

  • Use pull notifications by using startNotifications() (the default which starts automatically)
  • Register a callback server or webhook using updateWebhook()

The webhook and pull-notifications examples show how this can be done.

Hierarchy

  • EventEmitter
    • ConnectApi

Index

Constructors

constructor

Properties

autostartNotifications

autostartNotifications: boolean

Start receiving notifications on the client without calling start notifications

forceClear

forceClear: boolean

Clear any existing channels before receiving notifications

handleNotifications

handleNotifications: boolean
deprecated

webhook will work if updateWebhook is called or if startNotifications is not called

subscribe

subscribe: Subscribe

Gives you access to the subscribe interface

ASYNC_KEY

ASYNC_KEY: "async-response-id" = "async-response-id"

DELAY_BETWEEN_RETRIES

DELAY_BETWEEN_RETRIES: 1000 = 1000

MAXIMUM_NUMBER_OF_RETRIES

MAXIMUM_NUMBER_OF_RETRIES: 3 = 3

defaultMaxListeners

defaultMaxListeners: number

Accessors

deliveryMethod

deliveryMethod:

instanceId

instanceId:

Methods

addListener

  • addListener(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

addResourceSubscription

  • addResourceSubscription(deviceId: string, resourcePath: string, notifyFn?: function): Promise<void>
  • Subscribe to a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • Optional notifyFn: function

      Function to call with notification

        • Parameters

          Returns any

    Returns Promise<void>

    empty Promise

  • addResourceSubscription(deviceId: string, resourcePath: string, notifyFn?: function, callback?: CallbackFn<void>): void
  • Subscribe to a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • Optional notifyFn: function

      Function to call with notification

        • Parameters

          Returns any

    • Optional callback: CallbackFn<void>

      A function that is passed any error

    Returns void

deleteDeviceSubscriptions

  • deleteDeviceSubscriptions(deviceId: string): Promise<void>
  • Removes a device's subscriptions

    Parameters

    • deviceId: string

      Device ID

    Returns Promise<void>

    Promise containing any error

  • deleteDeviceSubscriptions(deviceId: string, callback: CallbackFn<void>): void
  • Removes a device's subscriptions

    Parameters

    • deviceId: string

      Device ID

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

deletePresubscriptions

  • deletePresubscriptions(): Promise<void>
  • Deletes pre-subscription data

    Returns Promise<void>

    Promise containing any error

  • deletePresubscriptions(callback: CallbackFn<void>): void
  • Deletes pre-subscription data

    Parameters

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

deleteResourceSubscription

  • deleteResourceSubscription(deviceId: string, resourcePath: string): Promise<void>
  • Deletes a resource's subscription

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    Returns Promise<void>

    empty Promise

  • deleteResourceSubscription(deviceId: string, resourcePath: string, callback: CallbackFn<void>): void
  • Deletes a resource's subscription

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

deleteSubscriptions

  • deleteSubscriptions(): Promise<void>
  • Removes all subscriptions for all devices.

    Warning: This could be slow for large numbers of connected devices. If possible, explicitly delete subscriptions known to have been created.

    Returns Promise<void>

    Promise containing any error

  • deleteSubscriptions(callback: CallbackFn<void>): void
  • Removes all subscriptions for all devices.

    Warning: This could be slow for large numbers of connected devices. If possible, explicitly delete subscriptions known to have been created.

    Parameters

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

deleteWebhook

  • deleteWebhook(): Promise<void>
  • Deletes the callback data

    If no webhook is registered, an exception (404) will be raised.

    Note that every registered subscription will be deleted as part of deregistering a webhook.

    Returns Promise<void>

    Promise containing any error

  • Deletes the callback data

    If no webhook is registered, an exception (404) will be raised.

    Note that every registered subscription will be deleted as part of deregistering a webhook.

    Parameters

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

emit

  • emit(event: string | symbol, ...args: any[]): boolean
  • Parameters

    • event: string | symbol
    • Rest ...args: any[]

    Returns boolean

eventNames

  • eventNames(): Array<string | symbol>
  • Returns Array<string | symbol>

executeResource

  • executeResource(deviceId: string, resourcePath: string, payload?: any, timeout?: number, mimeType?: string, accepts?: string): Promise<AsyncResponse>
  • Execute a function on a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • Optional payload: any

      The payload to be sent to the device.

    • Optional timeout: number

      async request will timeout after given number of milliseconds

    • Optional mimeType: string

      The content type of the payload

    • Optional accepts: string

      The content type of an accepted response

    Returns Promise<AsyncResponse>

    the AsyncResponse

  • executeResource(deviceId: string, resourcePath: string, payload?: any, timeout?: number, mimeType?: string, accepts?: string, callback?: CallbackFn<AsyncResponse>): void
  • Execute a function on a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • Optional payload: any

      The payload to be sent to the device.

    • Optional timeout: number

      async request will timeout after given number of milliseconds

    • Optional mimeType: string

      The content type of the payload

    • Optional accepts: string

      The content type of an accepted response

    • Optional callback: CallbackFn<AsyncResponse>

      A function that is passed any error

    Returns void

getLastApiMetadata

  • getLastApiMetadata(): Promise<ApiMetadata>
  • Get meta data for the last Pelion Device Management API call

    Returns Promise<ApiMetadata>

    Promise of meta data

  • getLastApiMetadata(callback: CallbackFn<ApiMetadata>): void
  • Get meta data for the lastPelion Device Management API call

    Parameters

    • callback: CallbackFn<ApiMetadata>

      A function that is passed the arguments (error, meta data)

    Returns void

getMaxListeners

  • getMaxListeners(): number
  • Returns number

getResource

  • getResource(deviceId: string, resourcePath: string): Promise<Resource>
  • Get a resource

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Path of the resource to get

    Returns Promise<Resource>

    Promise of device resource

  • getResource(deviceId: string, resourcePath: string, callback?: CallbackFn<Resource>): void
  • Get a resource

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Path of the resource to get

    • Optional callback: CallbackFn<Resource>

      A function that is passed the arguments (error, resource)

    Returns void

getResourceSubscription

  • getResourceSubscription(deviceId: string, resourcePath: string): Promise<boolean>
  • Gets the status of a resource's subscription

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    Returns Promise<boolean>

    Promise containing resource subscription status

  • getResourceSubscription(deviceId: string, resourcePath: string, callback: CallbackFn<boolean>): void
  • Gets the status of a resource's subscription

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • callback: CallbackFn<boolean>

      A function that is passed (error, subscribed) where subscribed is true or false

    Returns void

getResourceValue

  • getResourceValue(deviceId: string, resourcePath: string, timeout?: number, mimeType?: string, resource?: Resource, tlvParser?: TlvParser): Promise<ResourceValue>
  • Gets the value of a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • Optional timeout: number

      async request will timeout after given number of milliseconds

    • Optional mimeType: string

      The requested mime type format of the value

    • Optional resource: Resource
    • Optional tlvParser: TlvParser

    Returns Promise<ResourceValue>

    Promise of resource value

  • getResourceValue(deviceId: string, resourcePath: string, timeout?: number, mimeType?: string, resource?: Resource, tlvParser?: TlvParser, callback?: CallbackFn<ResourceValue>): void
  • Gets the value of a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • Optional timeout: number

      async request will timeout after given number of milliseconds

    • Optional mimeType: string

      The requested mime type format of the value

    • Optional resource: Resource
    • Optional tlvParser: TlvParser
    • Optional callback: CallbackFn<ResourceValue>

      A function that is passed the arguments (error, value)

    Returns void

getWebhook

  • getWebhook(): Promise<Webhook>
  • Get the current callback URL if it exists

    Returns Promise<Webhook>

    Promise containing the webhook data

  • Get the current callback URL if it exists

    Parameters

    • callback: CallbackFn<Webhook>

      A function that is passed the arguments (error, webhook)

    Returns void

listConnectedDevices

listDeviceSubscriptions

  • listDeviceSubscriptions(deviceId: string): Promise<string>
  • List a device's subscriptions

    Parameters

    • deviceId: string

      Device ID

    Returns Promise<string>

    Promise containing the subscriptions

  • listDeviceSubscriptions(deviceId: string, callback: CallbackFn<string>): void
  • List a device's subscriptions

    Parameters

    • deviceId: string

      Device ID

    • callback: CallbackFn<string>

      A function that is passed (error, subscriptions)

    Returns void

listMetrics

listPresubscriptions

  • Gets a list of pre-subscription data

    Returns Promise<Array<PresubscriptionObject>>

    Promise containing pre-subscriptions

  • Gets a list of pre-subscription data

    Parameters

    Returns void

listResources

  • listResources(deviceId: string): Promise<Array<Resource>>
  • List device's resources

    Parameters

    • deviceId: string

      Device ID

    Returns Promise<Array<Resource>>

    Promise of device resources

  • listResources(deviceId: string, callback: CallbackFn<Array<Resource>>): void
  • List device's resources

    Parameters

    • deviceId: string

      Device ID

    • callback: CallbackFn<Array<Resource>>

      A function that is passed the arguments (error, resources)

    Returns void

listenerCount

  • listenerCount(type: string | symbol): number
  • Parameters

    • type: string | symbol

    Returns number

listeners

  • listeners(event: string | symbol): Function[]
  • Parameters

    • event: string | symbol

    Returns Function[]

notify

  • notify(data: NotificationObject): void
  • Allows a notification to be injected into the notifications system

    Parameters

    • data: NotificationObject

      The notification data to inject

    Returns void

off

  • off(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

on

  • on(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

once

  • once(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

prependListener

  • prependListener(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

prependOnceListener

  • prependOnceListener(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

rawListeners

  • rawListeners(event: string | symbol): Function[]
  • Parameters

    • event: string | symbol

    Returns Function[]

removeAllListeners

  • removeAllListeners(event?: string | symbol): this
  • Parameters

    • Optional event: string | symbol

    Returns this

removeListener

  • removeListener(event: string | symbol, listener: function): this
  • Parameters

    • event: string | symbol
    • listener: function
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

setMaxListeners

  • setMaxListeners(n: number): this
  • Parameters

    • n: number

    Returns this

setResourceValue

  • setResourceValue(deviceId: string, resourcePath: string, value: string | number, timeout?: number, mimeType?: string): Promise<AsyncResponse>
  • Sets the value of a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • value: string | number

      The value of the resource

    • Optional timeout: number

      async request will timeout after given number of milliseconds

    • Optional mimeType: string

      The mime type format of the value

    Returns Promise<AsyncResponse>

    the AsyncResponse

  • setResourceValue(deviceId: string, resourcePath: string, value: string | number, timeout?: number, mimeType?: string, callback?: CallbackFn<AsyncResponse>): void
  • Sets the value of a resource

    Note: This method requires a notification channel to be set up

    Parameters

    • deviceId: string

      Device ID

    • resourcePath: string

      Resource path

    • value: string | number

      The value of the resource

    • Optional timeout: number

      async request will timeout after given number of milliseconds

    • Optional mimeType: string

      The mime type format of the value

    • Optional callback: CallbackFn<AsyncResponse>

      A function that is passed any error

    Returns void

startNotifications

  • Begins pull notifications

    If an external callback is not setup (using update_webhook), then calling this function is mandatory.

    Parameters

    Returns Promise<void>

    Promise containing any error

  • Begins pull notifications

    If an external callback is not setup (using update_webhook), then calling this function is mandatory.

    Parameters

    Returns void

stopNotifications

  • stopNotifications(): Promise<void>
  • Stops pull notifications

    Returns Promise<void>

    Promise containing any error

  • stopNotifications(callback: CallbackFn<void>): void
  • Stops pull notifications

    Parameters

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

updatePresubscriptions

  • Update pre-subscription data

    Parameters

    • subscriptions: Array<PresubscriptionObject>

      The pre-subscription data array. If you send an empty array, the pre-subscription data will be removed

    Returns Promise<void>

    Promise containing any error

  • Update pre-subscription data

    Parameters

    • subscriptions: Array<PresubscriptionObject>

      The pre-subscription data array. If you send an empty array, the pre-subscription data will be removed

    • callback: CallbackFn<void>

      A function that is passed any error

    Returns void

updateWebhook

  • updateWebhook(url: string, headers?: object, forceClear?: boolean): Promise<void>
  • Register new webhook for incoming subscriptions.

    If a webhook is already set, this will do an overwrite.

    Parameters

    • url: string

      The URL to which the notifications must be sent

    • Optional headers: object

      Any headers (key/value) that must be sent with the request

      • [key: string]: string
    • Optional forceClear: boolean

      Whether to clear any existing notification channel

    Returns Promise<void>

    Promise containing any error

  • updateWebhook(url: string, headers?: object, forceClear?: boolean, callback?: CallbackFn<void>): void
  • Register new webhook for incoming subscriptions.

    If a webhook is already set, this will do an overwrite.

    Parameters

    • url: string

      The URL to which the notifications must be sent

    • Optional headers: object

      Any headers (key/value) that must be sent with the request

      • [key: string]: string
    • Optional forceClear: boolean

      @deprecated please use force clear on initalisation instead

    • Optional callback: CallbackFn<void>

      A function that is passed any error

    Returns void

listenerCount

  • listenerCount(emitter: EventEmitter, event: string | symbol): number
  • deprecated

    since v4.0.0

    Parameters

    • emitter: EventEmitter
    • event: string | symbol

    Returns number