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

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

Latest version **1.0.5** (published 2025-09-10) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @particle/device-control-ble-setup-library
pnpm add @particle/device-control-ble-setup-library
yarn add @particle/device-control-ble-setup-library
bun add @particle/device-control-ble-setup-library
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2025-09-10 |
| First published | 2022-05-09 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 7 |
| Unpacked size | 38.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Particle Industries, inc |
| Maintainers | particlebot, no1089, carlos.hdez, guohui, keeramis5, monkbroc, mstan, sergeuz, avtolstoy, mlauer, wraithan, azenk, bwalach, rickkas7, mrlambchop_particle, hugo.montero, mphsi, pedrosordo, cole-abbeduto-particle, sbrust, eugene_particle, mohitparticle, karlag |

## Links

- npm: https://www.npmjs.com/package/@particle/device-control-ble-setup-library
- npm.io page: https://npm.io/package/@particle/device-control-ble-setup-library

## Dependencies (7)

- [aes-js](https://npm.io/package/aes-js.md) ^3.1.2
- [buffer](https://npm.io/package/buffer.md) ^6.0.3
- [events](https://npm.io/package/events.md) ^3.3.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [@particle/device-control-ble](https://npm.io/package/@particle/device-control-ble.md) ^0.2.6
- [@particle/device-os-protobuf](https://npm.io/package/@particle/device-os-protobuf.md) ^2.6.2
- [fastestsmallesttextencoderdecoder](https://npm.io/package/fastestsmallesttextencoderdecoder.md) ^1.0.22

## Recent versions

- 1.0.5 (latest) — 2025-09-10
- 1.0.4 — 2025-09-09
- 1.0.3 — 2025-09-09
- 1.0.2 — 2022-08-09
- 1.0.1 — 2022-06-08
- 1.0.0 — 2022-05-10
- 1.0.0-rc.2 — 2022-05-09
- 1.0.0-rc.1 — 2022-05-09
- 1.0.0-rc.0 — 2022-05-09

## README

# `@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)_

---
_Source: https://npm.io/package/@particle/device-control-ble-setup-library · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._