npm package: @particle/device-control-ble-setup-library
Description: Library that provides interfaces to execute the ble setup of a device
Author: Particle Industries, inc
Latest version: 1.0.5

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

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


## Installation

```shell
npm install @particle/device-control-ble-setup-library --save
```
<!-- private-module-note-start -->
_note: you'll need to be signed into an npm account that is a member of the `@particle` org ([docs](https://github.com/particle-iot/config/blob/main/FAQ.md#how-do-i-get-access-to-particle-modules-on-npm))_
<!-- private-module-note-end -->

## API
<!-- api-docs-start -->
<a name="StreamWithCallback"></a>

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

**Kind**: global class  

* [StreamWithCallback](#StreamWithCallback)
    * [new StreamWithCallback(callback)](#new_StreamWithCallback_new)
    * [.write(data)](#StreamWithCallback+write)


* * *

<a name="new_StreamWithCallback_new"></a>

#### new StreamWithCallback(callback)
Constructor


| Param | Type | Description |
| --- | --- | --- |
| callback | <code>StreamWithCallback~callback</code> | The callback used to write data. |


* * *

<a name="StreamWithCallback+write"></a>

#### streamWithCallback.write(data)
Writes data using a callback.

**Kind**: instance method of [<code>StreamWithCallback</code>](#StreamWithCallback)  

| Param | Type | Description |
| --- | --- | --- |
| data | <code>Uint8Array</code> | The data to write. |


* * *

<a name="BLEDevice"></a>

### BLEDevice
A class that implements the BLEDevice interface.

**Kind**: global class  

* [BLEDevice](#BLEDevice)
    * [new BLEDevice(device, uuids, env)](#new_BLEDevice_new)
    * [.name](#BLEDevice+name) : <code>string</code>
    * [.connect(mobileSecret)](#BLEDevice+connect)
    * [.disconnect()](#BLEDevice+disconnect)
    * [.findCharacteristics(UUIDs)](#BLEDevice+findCharacteristics)
    * [.getVersion()](#BLEDevice+getVersion) ⇒ <code>Promise.&lt;number&gt;</code>
    * [.checkProtocolVersion()](#BLEDevice+checkProtocolVersion)
    * [.openControlRequestChannel(mobileSecret)](#BLEDevice+openControlRequestChannel)
    * [.closeControlRequestChannel()](#BLEDevice+closeControlRequestChannel)
    * [.scanNetworks()](#BLEDevice+scanNetworks) ⇒ <code>Promise.&lt;void&gt;</code>
    * [.joinNewNetwork(network, password)](#BLEDevice+joinNewNetwork) ⇒ <code>Promise.&lt;void&gt;</code>
    * [.onDisconnect(listener)](#BLEDevice+onDisconnect)


* * *

<a name="new_BLEDevice_new"></a>

#### new BLEDevice(device, uuids, env)
Constructor.


| Param | Type | Description |
| --- | --- | --- |
| device | [<code>Device</code>](#Device) | Device instance which can be retrieved only by calling [bleManager.startDeviceScan()](#blemanagerstartdevicescan). |
| uuids | [<code>UUIDs</code>](#UUIDs) |  |
| env | <code>Object</code> |  |


* * *

<a name="BLEDevice+name"></a>

#### bleDevice.name : <code>string</code>
The name of the device.

**Kind**: instance property of [<code>BLEDevice</code>](#BLEDevice)  

* * *

<a name="BLEDevice+connect"></a>

#### 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 [<code>BLEDevice</code>](#BLEDevice)  

| Param | Type | Description |
| --- | --- | --- |
| mobileSecret | <code>string</code> | A string of the mobile secret. |


* * *

<a name="BLEDevice+disconnect"></a>

#### bleDevice.disconnect()
Disconnects from a device closing the control request channel, removing the
characteristics and cancelling the device connection.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  

* * *

<a name="BLEDevice+findCharacteristics"></a>

#### bleDevice.findCharacteristics(UUIDs)
Finds the characteristics of a mobile's connection service.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  

| Param | Type |
| --- | --- |
| UUIDs | [<code>UUIDs</code>](#UUIDs) | 


* * *

<a name="BLEDevice+getVersion"></a>

#### bleDevice.getVersion() ⇒ <code>Promise.&lt;number&gt;</code>
Gets the current protocol version from the read characteristics of the connection.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  
**Returns**: <code>Promise.&lt;number&gt;</code> - Promise with a number coming from a decoded base64 input.  

* * *

<a name="BLEDevice+checkProtocolVersion"></a>

#### 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 [<code>BLEDevice</code>](#BLEDevice)  

* * *

<a name="BLEDevice+openControlRequestChannel"></a>

#### bleDevice.openControlRequestChannel(mobileSecret)
Opens a new control request channel using the mobile's secret.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  

| Param | Type |
| --- | --- |
| mobileSecret | <code>string</code> | 


* * *

<a name="BLEDevice+closeControlRequestChannel"></a>

#### bleDevice.closeControlRequestChannel()
Closes a control requested channel.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  

* * *

<a name="BLEDevice+scanNetworks"></a>

#### bleDevice.scanNetworks() ⇒ <code>Promise.&lt;void&gt;</code>
Scans for nearby networks. Filters invalid names and returns unique SSIDs.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  
**Returns**: <code>Promise.&lt;void&gt;</code> - Returns a successful promise with the scanned networks.  

* * *

<a name="BLEDevice+joinNewNetwork"></a>

#### bleDevice.joinNewNetwork(network, password) ⇒ <code>Promise.&lt;void&gt;</code>
Joins a scanned network.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  
**Returns**: <code>Promise.&lt;void&gt;</code> - Returns a successful promise if network was joinable.  

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


* * *

<a name="BLEDevice+onDisconnect"></a>

#### bleDevice.onDisconnect(listener)
Listener function triggered when disconnection happens.

**Kind**: instance method of [<code>BLEDevice</code>](#BLEDevice)  

| Param | Type | Description |
| --- | --- | --- |
| listener | <code>callback</code> | Listener callback that gets executed when disconnecting. |


* * *

<a name="DeviceRequests"></a>

### DeviceRequests
A class for capturing device requests

**Kind**: global class  

* [DeviceRequests](#DeviceRequests)
    * [new DeviceRequests(requestChannel)](#new_DeviceRequests_new)
    * [.request(RequestClass, ReplyClass, type, requestData)](#DeviceRequests+request) ⇒ <code>Promise.&lt;ReplyType&gt;</code>
    * [.scanNetworks()](#DeviceRequests+scanNetworks) ⇒ <code>Promise.&lt;Array.&lt;INetwork&gt;&gt;</code>
    * [.joinNewNetwork(network, password)](#DeviceRequests+joinNewNetwork)


* * *

<a name="new_DeviceRequests_new"></a>

#### new DeviceRequests(requestChannel)
Constructor


| Param | Type |
| --- | --- |
| requestChannel | <code>\*</code> | 


* * *

<a name="DeviceRequests+request"></a>

#### deviceRequests.request(RequestClass, ReplyClass, type, requestData) ⇒ <code>Promise.&lt;ReplyType&gt;</code>
Send a connection request.

**Kind**: instance method of [<code>DeviceRequests</code>](#DeviceRequests)  
**Returns**: <code>Promise.&lt;ReplyType&gt;</code> - Promise  

| Param | Type |
| --- | --- |
| RequestClass | <code>ProtobufMessage.&lt;ReplyType&gt;</code> | 
| ReplyClass | <code>ProtobufMessage.&lt;ReplyType&gt;</code> | 
| type | <code>number</code> | 
| requestData | <code>RequestType</code> | 


* * *

<a name="DeviceRequests+scanNetworks"></a>

#### deviceRequests.scanNetworks() ⇒ <code>Promise.&lt;Array.&lt;INetwork&gt;&gt;</code>
Scans the nearby networks.

**Kind**: instance method of [<code>DeviceRequests</code>](#DeviceRequests)  
**Returns**: <code>Promise.&lt;Array.&lt;INetwork&gt;&gt;</code> - Promise containing the network information  

* * *

<a name="DeviceRequests+joinNewNetwork"></a>

#### deviceRequests.joinNewNetwork(network, password)
Sends a request to join a new network.

**Kind**: instance method of [<code>DeviceRequests</code>](#DeviceRequests)  

| Param | Type | Description |
| --- | --- | --- |
| network | <code>INetwork</code> | INetwork interface |
| password | <code>string</code> |  |


* * *

<a name="atob"></a>

### atob(input) ⇒ <code>string</code>
Decode base64 string into a string

**Kind**: global function  
**Returns**: <code>string</code> - Decoded string  

| Param | Type | Description |
| --- | --- | --- |
| input | <code>string</code> | Base64 encoded input |


* * *

<a name="atoi"></a>

### atoi(input) ⇒ <code>number</code>
Decode base64 string into a number

**Kind**: global function  
**Returns**: <code>number</code> - Decoded number  

| Param | Type | Description |
| --- | --- | --- |
| input | <code>string</code> | Base64 encoded input |


* * *

<a name="Device"></a>

### Device : <code>Object</code>
A Device interface

**Kind**: global typedef  

* * *

<a name="UUIDs"></a>

### UUIDs : <code>Object</code>
A UUID interface

**Kind**: global typedef  
**Properties**

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


* * *

<a name="ProtobufMessage"></a>

### ProtobufMessage : <code>Object</code>
A ProtobufMessage interface

**Kind**: global typedef  
**Properties**

| Name | Type |
| --- | --- |
| create | <code>function</code> | 


* * *


<!-- api-docs-end -->

_NOTE: Unfortunately, docs have a nasty habit of falling out of date. When in doubt, check usage in [tests](./src/index.test.js)_