@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