@particle/device-control-ble-setup-library

Library that provides interfaces to execute the ble setup of a device

Installation

npm install @particle/device-control-ble-setup-library --save

note: you'll need to be signed into an npm account that is a member of the @particle org (docs)

API

StreamWithCallback

A class to write data to a stream. Extends the EventEmitter class.

Kind: global class

• StreamWithCallback
  • new StreamWithCallback(callback)
  • .write(data)

new StreamWithCallback(callback)

Constructor

| Param | Type | Description | | --- | --- | --- | | callback | StreamWithCallback~callback | The callback used to write data. |

streamWithCallback.write(data)

Writes data using a callback.

Kind: instance method of StreamWithCallback

| Param | Type | Description | | --- | --- | --- | | data | Uint8Array | The data to write. |

BLEDevice

A class that implements the BLEDevice interface.

Kind: global class

• BLEDevice
  • new BLEDevice(device, uuids, env)
  • .name : string
  • .connect(mobileSecret)
  • .disconnect()
  • .findCharacteristics(UUIDs)
  • .getVersion() ⇒ Promise.<number>
  • .checkProtocolVersion()
  • .openControlRequestChannel(mobileSecret)
  • .closeControlRequestChannel()
  • .scanNetworks() ⇒ Promise.<void>
  • .joinNewNetwork(network, password) ⇒ Promise.<void>
  • .onDisconnect(listener)

new BLEDevice(device, uuids, env)

Constructor.

| Param | Type | Description | | --- | --- | --- | | device | Device | Device instance which can be retrieved only by calling bleManager.startDeviceScan(). | | uuids | UUIDs | | | env | Object | |

bleDevice.name : string

The name of the device.

Kind: instance property of BLEDevice

bleDevice.connect(mobileSecret)

Connects to a device using its mobile secret. It first estalishes a connection, and then tries to find the device characteristic based on the UUIDs provided. It then tries to check the protocol version to finally open a control request channel using the mobile secret.

Kind: instance method of BLEDevice

| Param | Type | Description | | --- | --- | --- | | mobileSecret | string | A string of the mobile secret. |

bleDevice.disconnect()

Disconnects from a device closing the control request channel, removing the characteristics and cancelling the device connection.

Kind: instance method of BLEDevice

bleDevice.findCharacteristics(UUIDs)

Finds the characteristics of a mobile's connection service.

Kind: instance method of BLEDevice

| Param | Type | | --- | --- | | UUIDs | UUIDs |

bleDevice.getVersion() ⇒ Promise.<number>

Gets the current protocol version from the read characteristics of the connection.

Kind: instance method of BLEDevice
Returns: Promise.<number> - Promise with a number coming from a decoded base64 input.

bleDevice.checkProtocolVersion()

Checks for the protocol version. If the protocol is different that 2, it throws an error instance of type InvalidProtocolVersionError.

Kind: instance method of BLEDevice

bleDevice.openControlRequestChannel(mobileSecret)

Opens a new control request channel using the mobile's secret.

Kind: instance method of BLEDevice

| Param | Type | | --- | --- | | mobileSecret | string |

bleDevice.closeControlRequestChannel()

Closes a control requested channel.

Kind: instance method of BLEDevice

bleDevice.scanNetworks() ⇒ Promise.<void>

Scans for nearby networks. Filters invalid names and returns unique SSIDs.

Kind: instance method of BLEDevice
Returns: Promise.<void> - Returns a successful promise with the scanned networks.

bleDevice.joinNewNetwork(network, password) ⇒ Promise.<void>

Joins a scanned network.

Kind: instance method of BLEDevice
Returns: Promise.<void> - Returns a successful promise if network was joinable.

| Param | Type | Description | | --- | --- | --- | | network | INetwork | Network interface with information like the SSID and channel. | | password | string | Password to join the network. |

bleDevice.onDisconnect(listener)

Listener function triggered when disconnection happens.

Kind: instance method of BLEDevice

| Param | Type | Description | | --- | --- | --- | | listener | callback | Listener callback that gets executed when disconnecting. |

DeviceRequests

A class for capturing device requests

Kind: global class

• DeviceRequests
  • new DeviceRequests(requestChannel)
  • .request(RequestClass, ReplyClass, type, requestData) ⇒ Promise.<ReplyType>
  • .scanNetworks() ⇒ Promise.<Array.<INetwork>>
  • .joinNewNetwork(network, password)

new DeviceRequests(requestChannel)

Constructor

| Param | Type | | --- | --- | | requestChannel | * |

deviceRequests.request(RequestClass, ReplyClass, type, requestData) ⇒ Promise.<ReplyType>

Send a connection request.

Kind: instance method of DeviceRequests
Returns: Promise.<ReplyType> - Promise

| Param | Type | | --- | --- | | RequestClass | ProtobufMessage.<ReplyType> | | ReplyClass | ProtobufMessage.<ReplyType> | | type | number | | requestData | RequestType |

deviceRequests.scanNetworks() ⇒ Promise.<Array.<INetwork>>

Scans the nearby networks.

Kind: instance method of DeviceRequests
Returns: Promise.<Array.<INetwork>> - Promise containing the network information

deviceRequests.joinNewNetwork(network, password)

Sends a request to join a new network.

Kind: instance method of DeviceRequests

| Param | Type | Description | | --- | --- | --- | | network | INetwork | INetwork interface | | password | string | |

atob(input) ⇒ string

Decode base64 string into a string

Kind: global function
Returns: string - Decoded string

| Param | Type | Description | | --- | --- | --- | | input | string | Base64 encoded input |

atoi(input) ⇒ number

Decode base64 string into a number

Kind: global function
Returns: number - Decoded number

| Param | Type | Description | | --- | --- | --- | | input | string | Base64 encoded input |

Device : Object

A Device interface

Kind: global typedef

UUIDs : Object

A UUID interface

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | serviceUUID | string | The UUID of the service. | | versionCharacteristicUUID | string | The version characteristic UUID of the service. | | rxCharacteristicUUID | string | The receiver characteristic UUID of the service. | | txCharacteristicUUID | string | The transmitter UUID of the service. |

ProtobufMessage : Object

A ProtobufMessage interface

Kind: global typedef
Properties

| Name | Type | | --- | --- | | create | function |

NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in tests