simplejsble 1.2.1-dev100
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +104 -0
- package/README.md +168 -0
- package/dist/adapter.d.ts +65 -0
- package/dist/adapter.js +139 -0
- package/dist/backend.d.ts +16 -0
- package/dist/backend.js +45 -0
- package/dist/config.d.ts +36 -0
- package/dist/config.js +43 -0
- package/dist/errors.d.ts +10 -0
- package/dist/errors.js +17 -0
- package/dist/handlers.d.ts +1 -0
- package/dist/handlers.js +58 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +49 -0
- package/dist/local.d.ts +78 -0
- package/dist/local.js +182 -0
- package/dist/logging.d.ts +22 -0
- package/dist/logging.js +38 -0
- package/dist/native.d.ts +1 -0
- package/dist/native.js +15 -0
- package/dist/peripheral.d.ts +77 -0
- package/dist/peripheral.js +235 -0
- package/dist/registry.d.ts +1 -0
- package/dist/registry.js +110 -0
- package/package.json +59 -0
- package/prebuilds/darwin-arm64/simplejsble.node +0 -0
- package/prebuilds/darwin-x64/simplejsble.node +0 -0
- package/prebuilds/linux-arm64/simplejsble.node +0 -0
- package/prebuilds/linux-x64/simplejsble.node +0 -0
- package/prebuilds/win32-arm64/simplejsble.node +0 -0
- package/prebuilds/win32-x64/simplejsble.node +0 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Business Source License 1.1
|
|
2
|
+
|
|
3
|
+
## Parameters
|
|
4
|
+
|
|
5
|
+
**Licensor:** The California Open Source Company LLC
|
|
6
|
+
|
|
7
|
+
**Licensed Work:** SimpleBLE and the companion libraries, language bindings and tools that the
|
|
8
|
+
Licensor distributes under this License, in source or binary form and however obtained, including
|
|
9
|
+
from https://github.com/simpleble/simpleble, from the Licensor's other repositories, or from package
|
|
10
|
+
registries. The Licensed Work is (c) The California Open Source Company LLC. Third-party components
|
|
11
|
+
distributed with the Licensed Work remain under the licenses stated in their own files.
|
|
12
|
+
|
|
13
|
+
**Additional Use Grant:** You may make production use of the Licensed Work, provided your use is
|
|
14
|
+
Non-Commercial.
|
|
15
|
+
|
|
16
|
+
"Non-Commercial" means use that does not contribute, directly or indirectly, to financial gain.
|
|
17
|
+
Examples of Non-Commercial use are personal and hobby projects of individuals, and use by educational
|
|
18
|
+
institutions and by open-source projects that generate no revenue. Use is not Non-Commercial if it
|
|
19
|
+
involves, among other things, incorporating the Licensed Work or its derivatives into commercial
|
|
20
|
+
software products, using it in the development of services offered for a fee, or deploying it within
|
|
21
|
+
internal tools or software in a for-profit organization where it adds business value.
|
|
22
|
+
|
|
23
|
+
Non-Commercial Perpetual Use Grant: after the Change Date, you may continue to use and distribute that
|
|
24
|
+
version of the Licensed Work under the terms of this License for as long as your use remains
|
|
25
|
+
Non-Commercial, notwithstanding its conversion to the Change License.
|
|
26
|
+
|
|
27
|
+
**Change Date:** The fourth anniversary of the first publicly available distribution of a specific
|
|
28
|
+
version of SimpleBLE under this License.
|
|
29
|
+
|
|
30
|
+
**Change License:** GNU General Public License version 3.0 (GPL-3.0)
|
|
31
|
+
|
|
32
|
+
For information about alternative licensing arrangements for the Licensed Work, please
|
|
33
|
+
[email us](mailto:contact@simpleble.org) or [leave us a message on our website](https://www.simpleble.org/contact?utm_source=github&utm_medium=referral&utm_campaign=simpleble_license).
|
|
34
|
+
|
|
35
|
+
## Notice
|
|
36
|
+
|
|
37
|
+
The Business Source License (this document, or the "License") is not an Open Source license. However,
|
|
38
|
+
the Licensed Work will eventually be made available under an Open Source License, as stated in this
|
|
39
|
+
License.
|
|
40
|
+
|
|
41
|
+
License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved. "Business Source License"
|
|
42
|
+
is a trademark of MariaDB Corporation Ab.
|
|
43
|
+
|
|
44
|
+
-------------------------------------------------------------------------------
|
|
45
|
+
|
|
46
|
+
## Terms
|
|
47
|
+
|
|
48
|
+
The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and
|
|
49
|
+
make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above,
|
|
50
|
+
permitting limited production use.
|
|
51
|
+
|
|
52
|
+
Effective on the Change Date, or the fourth anniversary of the first publicly available distribution
|
|
53
|
+
of a specific version of the Licensed Work under this License, whichever comes first, the Licensor
|
|
54
|
+
hereby grants you rights under the terms of the Change License, and the rights granted in the
|
|
55
|
+
paragraph above terminate.
|
|
56
|
+
|
|
57
|
+
If your use of the Licensed Work does not comply with the requirements currently in effect as
|
|
58
|
+
described in this License, you must purchase a commercial license from the Licensor, its affiliated
|
|
59
|
+
entities, or authorized resellers, or you must refrain from using the Licensed Work.
|
|
60
|
+
|
|
61
|
+
All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are
|
|
62
|
+
subject to this License. This License applies separately for each version of the Licensed Work and
|
|
63
|
+
the Change Date may vary for each version of the Licensed Work released by Licensor.
|
|
64
|
+
|
|
65
|
+
You must conspicuously display this License on each original or modified copy of the Licensed Work.
|
|
66
|
+
If you receive the Licensed Work in original or modified form from a third party, the terms and
|
|
67
|
+
conditions set forth in this License apply to your use of that work.
|
|
68
|
+
|
|
69
|
+
Any use of the Licensed Work in violation of this License will automatically terminate your rights
|
|
70
|
+
under this License for the current and all other versions of the Licensed Work.
|
|
71
|
+
|
|
72
|
+
This License does not grant you any right in any trademark or logo of Licensor or its affiliates
|
|
73
|
+
(provided that you may use a trademark or logo of Licensor as expressly required by this License).
|
|
74
|
+
|
|
75
|
+
TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS" BASIS. LICENSOR
|
|
76
|
+
HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION)
|
|
77
|
+
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
|
|
78
|
+
|
|
79
|
+
MariaDB hereby grants you permission to use this License's text to license your works, and to refer
|
|
80
|
+
to it using the trademark "Business Source License", as long as you comply with the Covenants of
|
|
81
|
+
Licensor below.
|
|
82
|
+
|
|
83
|
+
## Covenants of Licensor
|
|
84
|
+
|
|
85
|
+
In consideration of the right to use this License's text and the "Business Source License" name and
|
|
86
|
+
trademark, Licensor covenants to MariaDB, and to all other recipients of the licensed work to be
|
|
87
|
+
provided by Licensor:
|
|
88
|
+
|
|
89
|
+
1. To specify as the Change License the GPL Version 2.0 or any later version, or a license that is
|
|
90
|
+
compatible with GPL Version 2.0 or a later version, where "compatible" means that software provided
|
|
91
|
+
under the Change License can be included in a program with software provided under GPL Version 2.0
|
|
92
|
+
or a later version. Licensor may specify additional Change Licenses without limitation.
|
|
93
|
+
|
|
94
|
+
2. To either: (a) specify an additional grant of rights to use that does not impose any additional
|
|
95
|
+
restriction on the right granted in this License, as the Additional Use Grant; or (b) insert the
|
|
96
|
+
text "None".
|
|
97
|
+
|
|
98
|
+
3. To specify a Change Date.
|
|
99
|
+
|
|
100
|
+
4. Not to modify this License in any other way.
|
|
101
|
+
|
|
102
|
+
-------------------------------------------------------------------------------
|
|
103
|
+
|
|
104
|
+
Licensing FAQ and a plain-language summary: https://docs.simpleble.org/licensing
|
package/README.md
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/simpleble/simpleble/main/docs/public/simpleBLE-logo-dark.png#gh-light-mode-only" alt="SimpleBLE" width="360">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/simpleble/simpleble/main/docs/public/simpleBLE-logo.png#gh-dark-mode-only" alt="SimpleBLE" width="360">
|
|
4
|
+
</p>
|
|
5
|
+
|
|
6
|
+
# SimpleJSBLE
|
|
7
|
+
|
|
8
|
+
SimpleJSBLE brings [SimpleBLE](https://github.com/simpleble/simpleble) to Node.js
|
|
9
|
+
and Electron on Windows, macOS, and Linux. Discover and connect Bluetooth
|
|
10
|
+
peripherals, read and write GATT values, subscribe to notifications, and host
|
|
11
|
+
local GATT services through one API, with TypeScript types included.
|
|
12
|
+
|
|
13
|
+
## Get started
|
|
14
|
+
|
|
15
|
+
Use Node.js 22 or newer:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install simplejsble
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The package includes the native addon for every supported platform, so nothing
|
|
22
|
+
is compiled or downloaded during installation.
|
|
23
|
+
|
|
24
|
+
Scan for five seconds and print what was found:
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
import { Adapter } from 'simplejsble';
|
|
28
|
+
|
|
29
|
+
const [adapter] = await Adapter.getAdapters();
|
|
30
|
+
|
|
31
|
+
adapter.on('scanFound', peripheral => {
|
|
32
|
+
console.log(peripheral.identifier(), peripheral.address(), peripheral.rssi());
|
|
33
|
+
});
|
|
34
|
+
await adapter.scanFor(5000);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Scanning and events
|
|
38
|
+
|
|
39
|
+
Adapters and peripherals are `EventEmitter`s. An adapter emits `scanStart`,
|
|
40
|
+
`scanStop`, `scanFound`, `scanUpdated`, `powerOn`, and `powerOff`; a peripheral
|
|
41
|
+
emits `connected` and `disconnected`. Events arrive on the JavaScript thread in
|
|
42
|
+
the order they happened.
|
|
43
|
+
|
|
44
|
+
Use `scanStart()` and `scanStop()` when your application controls scan timing,
|
|
45
|
+
and `scanGetResults()` for the peripherals seen by the last scan. An adapter
|
|
46
|
+
always gives you the same `Peripheral` object for the same device, whether it
|
|
47
|
+
came from an event or from a list.
|
|
48
|
+
|
|
49
|
+
Calls that talk to the Bluetooth stack return promises and run in the order
|
|
50
|
+
they were made. Data the library already holds, such as a peripheral's
|
|
51
|
+
`identifier()`, `rssi()`, or `manufacturerData()`, is returned directly. An
|
|
52
|
+
active scan or connection keeps Node.js running until it ends.
|
|
53
|
+
|
|
54
|
+
## Connect and use GATT
|
|
55
|
+
|
|
56
|
+
Read the battery level of a peripheral and follow its notifications:
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
const BATTERY_SERVICE = '0000180f-0000-1000-8000-00805f9b34fb';
|
|
60
|
+
const BATTERY_LEVEL = '00002a19-0000-1000-8000-00805f9b34fb';
|
|
61
|
+
|
|
62
|
+
const peripheral = adapter.scanGetResults().find(p => p.identifier() === 'My Sensor');
|
|
63
|
+
|
|
64
|
+
peripheral.on('disconnected', () => console.log('Disconnected'));
|
|
65
|
+
await peripheral.connect();
|
|
66
|
+
|
|
67
|
+
const level = await peripheral.read(BATTERY_SERVICE, BATTERY_LEVEL);
|
|
68
|
+
console.log(`Battery: ${level[0]}%`);
|
|
69
|
+
|
|
70
|
+
await peripheral.notify(BATTERY_SERVICE, BATTERY_LEVEL, value => console.log(`Battery: ${value[0]}%`));
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`services()` lists the services, characteristics, capabilities, and descriptors
|
|
74
|
+
of a connected peripheral. `read`, `writeRequest`, and `writeCommand` access
|
|
75
|
+
characteristic values; `readDescriptor` and `writeDescriptor` access
|
|
76
|
+
descriptors. `notify` and `indicate` call your function with each value as a
|
|
77
|
+
`Buffer`, and `unsubscribe` stops them. Failures are `SimpleBLEError`s with
|
|
78
|
+
SimpleBLE's error code in `error.code`.
|
|
79
|
+
|
|
80
|
+
## Host a GATT service
|
|
81
|
+
|
|
82
|
+
Create a local peripheral from an adapter, add services and characteristics,
|
|
83
|
+
then start advertising:
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
const host = adapter.createLocalPeripheral();
|
|
87
|
+
host.addAdvertisedService(BATTERY_SERVICE);
|
|
88
|
+
|
|
89
|
+
const service = host.addService(BATTERY_SERVICE);
|
|
90
|
+
const battery = service.addCharacteristic(BATTERY_LEVEL, ['read', 'notify']);
|
|
91
|
+
await battery.setValue(Buffer.from([100]));
|
|
92
|
+
|
|
93
|
+
host.on('clientConnected', address => console.log(`${address} connected`));
|
|
94
|
+
await host.start();
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`setValue` updates the stored value and publishes it to subscribers. Characteristics
|
|
98
|
+
emit `write`, `subscribed`, and `unsubscribed`, and `setReadHandler` computes a
|
|
99
|
+
value for each read. Configure services before `start()`; call `stop()` before
|
|
100
|
+
changing them.
|
|
101
|
+
|
|
102
|
+
## Use a Dongl
|
|
103
|
+
|
|
104
|
+
A [Dongl](https://docs.simpleble.org/dongl) is a USB Bluetooth adapter made for
|
|
105
|
+
SimpleBLE. Its backend is on by default; use the adapters of the Dongl backend:
|
|
106
|
+
|
|
107
|
+
```js
|
|
108
|
+
import { Backend } from 'simplejsble';
|
|
109
|
+
|
|
110
|
+
const dongl = await Backend.getDongl();
|
|
111
|
+
const [adapter] = await dongl.adapters();
|
|
112
|
+
|
|
113
|
+
// ...
|
|
114
|
+
|
|
115
|
+
await adapter.close();
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`close()` stops the adapter's scan, disconnects its peripherals, and frees the
|
|
119
|
+
Dongl for other programs. Adapters also support `await using`.
|
|
120
|
+
|
|
121
|
+
`Config` holds the Dongl, BlueZ, and WinRT backend settings; set them before the
|
|
122
|
+
first call that reaches a backend. Pairing through a Dongl happens without the
|
|
123
|
+
operating system: set `setPasskeyRequestHandler`, `setPasskeyDisplayHandler`, or
|
|
124
|
+
`setNumericComparisonHandler` on the peripheral before `connect()`.
|
|
125
|
+
|
|
126
|
+
## Electron
|
|
127
|
+
|
|
128
|
+
Use SimpleJSBLE from the main process and pass plain data to renderers over
|
|
129
|
+
IPC. When packaging, unpack `*.node` files from the ASAR archive. Packaged macOS
|
|
130
|
+
apps need an `NSBluetoothAlwaysUsageDescription` entry in their `Info.plist`.
|
|
131
|
+
|
|
132
|
+
## Platforms
|
|
133
|
+
|
|
134
|
+
| Platform | Architectures | Requirements |
|
|
135
|
+
| --- | --- | --- |
|
|
136
|
+
| macOS 13.0 or newer | x64, arm64 | Bluetooth permission for the app that runs Node.js |
|
|
137
|
+
| Windows 10 or newer | x64, arm64 | |
|
|
138
|
+
| Linux with glibc 2.28 or newer | x64, arm64 | BlueZ and the D-Bus library |
|
|
139
|
+
|
|
140
|
+
See the [usage guide](https://docs.simpleble.org/simplejsble/usage) for
|
|
141
|
+
Bluetooth permissions and platform details.
|
|
142
|
+
|
|
143
|
+
## Versions
|
|
144
|
+
|
|
145
|
+
SimpleJSBLE follows SimpleBLE's release versions. Stable releases are published
|
|
146
|
+
under the `latest` tag, and development builds of the main branch under `dev`:
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
npm install simplejsble@dev
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Documentation and support
|
|
153
|
+
|
|
154
|
+
- Read the [SimpleJSBLE usage guide](https://docs.simpleble.org/simplejsble/usage).
|
|
155
|
+
- Browse the [examples](https://github.com/simpleble/simpleble/tree/main/examples/simplejsble).
|
|
156
|
+
- Join the [Discord community](https://discord.gg/N9HqNEcvP3).
|
|
157
|
+
- Contribute in [simpleble/simpleble](https://github.com/simpleble/simpleble/tree/main/simplejsble); see the [development and publishing guide](https://github.com/simpleble/simpleble/blob/main/docs/extras/simplejsble-publishing.md).
|
|
158
|
+
- Visit [simpleble.org](https://simpleble.org/) for commercial licensing and professional services.
|
|
159
|
+
|
|
160
|
+
## License
|
|
161
|
+
|
|
162
|
+
SimpleJSBLE follows the [SimpleBLE license](https://github.com/simpleble/simpleble/blob/main/LICENSE.md),
|
|
163
|
+
the Business Source License 1.1 (BUSL-1.1). See the included [LICENSE](LICENSE.md)
|
|
164
|
+
for the complete terms.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
**SimpleBLE** is a project powered by [The California Open Source Company](https://californiaopensource.com/).
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { EventEmitter } from 'node:events';
|
|
2
|
+
import { LocalPeripheral } from './local';
|
|
3
|
+
import { Peripheral } from './peripheral';
|
|
4
|
+
export interface AdapterEvents {
|
|
5
|
+
scanStart: [];
|
|
6
|
+
scanStop: [];
|
|
7
|
+
scanFound: [peripheral: Peripheral];
|
|
8
|
+
scanUpdated: [peripheral: Peripheral];
|
|
9
|
+
powerOn: [];
|
|
10
|
+
powerOff: [];
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* A Bluetooth adapter.
|
|
14
|
+
*
|
|
15
|
+
* There is one Adapter object per native adapter object. Most backends keep a
|
|
16
|
+
* single native object per adapter, so every enumeration returns the same
|
|
17
|
+
* Adapter. On Windows each enumeration creates a new native object, and
|
|
18
|
+
* listeners on one Adapter only hear about calls made through it.
|
|
19
|
+
*
|
|
20
|
+
* Events are delivered on the JavaScript thread in the order they happened.
|
|
21
|
+
* While an adapter has listeners it stays alive, even if nothing else
|
|
22
|
+
* references it. close() releases it and its peripherals right away.
|
|
23
|
+
*/
|
|
24
|
+
export declare class Adapter extends EventEmitter<AdapterEvents> {
|
|
25
|
+
#private;
|
|
26
|
+
private constructor();
|
|
27
|
+
/** Every adapter of every available backend. */
|
|
28
|
+
static getAdapters(): Promise<Adapter[]>;
|
|
29
|
+
/** Whether Bluetooth is enabled on any adapter. */
|
|
30
|
+
static bluetoothEnabled(): Promise<boolean>;
|
|
31
|
+
identifier(): string;
|
|
32
|
+
address(): string;
|
|
33
|
+
isPowered(): Promise<boolean>;
|
|
34
|
+
powerOn(): Promise<void>;
|
|
35
|
+
powerOff(): Promise<void>;
|
|
36
|
+
scanStart(): Promise<void>;
|
|
37
|
+
scanStop(): Promise<void>;
|
|
38
|
+
/** Scans for `timeoutMs` milliseconds, then stops. Other calls on this adapter wait for it. */
|
|
39
|
+
scanFor(timeoutMs: number): Promise<void>;
|
|
40
|
+
scanIsActive(): Promise<boolean>;
|
|
41
|
+
/** The peripherals seen by the current or last scan. */
|
|
42
|
+
scanGetResults(): Peripheral[];
|
|
43
|
+
getPairedPeripherals(): Promise<Peripheral[]>;
|
|
44
|
+
getConnectedPeripherals(): Promise<Peripheral[]>;
|
|
45
|
+
/**
|
|
46
|
+
* The peripherals CoreBluetooth already knows on macOS, by the identifiers
|
|
47
|
+
* address() returned earlier, without scanning. Unknown identifiers are
|
|
48
|
+
* skipped, and a returned peripheral might be out of range. Other platforms
|
|
49
|
+
* reject with OPERATION_NOT_SUPPORTED.
|
|
50
|
+
*/
|
|
51
|
+
retrieveCachedPeripherals(identifiers: readonly string[]): Promise<Peripheral[]>;
|
|
52
|
+
/** A host for GATT services of this process, advertised by this adapter. */
|
|
53
|
+
createLocalPeripheral(): LocalPeripheral;
|
|
54
|
+
/**
|
|
55
|
+
* Stops this adapter's scan and local peripherals, disconnects the
|
|
56
|
+
* peripherals connected through it, and releases the adapter and every object
|
|
57
|
+
* that came from it. Once the promise resolves, a Dongl is free for other
|
|
58
|
+
* programs. Calls on the closed objects then fail with OBJECT_NOT_INITIALIZED,
|
|
59
|
+
* they emit no more events, and getAdapters() returns a new Adapter for the
|
|
60
|
+
* device.
|
|
61
|
+
*/
|
|
62
|
+
close(): Promise<void>;
|
|
63
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
64
|
+
removeAllListeners(...args: Parameters<EventEmitter<AdapterEvents>['removeAllListeners']>): this;
|
|
65
|
+
}
|
package/dist/adapter.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Adapter = void 0;
|
|
4
|
+
const node_events_1 = require("node:events");
|
|
5
|
+
const local_1 = require("./local");
|
|
6
|
+
const native_1 = require("./native");
|
|
7
|
+
const peripheral_1 = require("./peripheral");
|
|
8
|
+
const registry_1 = require("./registry");
|
|
9
|
+
const EVENTS = ['scanStart', 'scanStop', 'scanFound', 'scanUpdated', 'powerOn', 'powerOff'];
|
|
10
|
+
const construct = Symbol('construct');
|
|
11
|
+
/**
|
|
12
|
+
* A Bluetooth adapter.
|
|
13
|
+
*
|
|
14
|
+
* There is one Adapter object per native adapter object. Most backends keep a
|
|
15
|
+
* single native object per adapter, so every enumeration returns the same
|
|
16
|
+
* Adapter. On Windows each enumeration creates a new native object, and
|
|
17
|
+
* listeners on one Adapter only hear about calls made through it.
|
|
18
|
+
*
|
|
19
|
+
* Events are delivered on the JavaScript thread in the order they happened.
|
|
20
|
+
* While an adapter has listeners it stays alive, even if nothing else
|
|
21
|
+
* references it. close() releases it and its peripherals right away.
|
|
22
|
+
*/
|
|
23
|
+
class Adapter extends node_events_1.EventEmitter {
|
|
24
|
+
#handle;
|
|
25
|
+
#rehook;
|
|
26
|
+
#closing;
|
|
27
|
+
constructor(token, handle) {
|
|
28
|
+
if (token !== construct)
|
|
29
|
+
throw new TypeError('Use Adapter.getAdapters()');
|
|
30
|
+
super();
|
|
31
|
+
this.#handle = handle;
|
|
32
|
+
this.#rehook = (0, registry_1.retainWhileListening)(this, EVENTS);
|
|
33
|
+
handle.subscribe();
|
|
34
|
+
}
|
|
35
|
+
/** @internal */
|
|
36
|
+
static wrap(handle) {
|
|
37
|
+
return (0, registry_1.intern)(handle.key(), () => new Adapter(construct, handle), () => handle.release());
|
|
38
|
+
}
|
|
39
|
+
/** Every adapter of every available backend. */
|
|
40
|
+
static async getAdapters() {
|
|
41
|
+
return (await native_1.native.getAdapters()).map(Adapter.wrap);
|
|
42
|
+
}
|
|
43
|
+
/** Whether Bluetooth is enabled on any adapter. */
|
|
44
|
+
static bluetoothEnabled() {
|
|
45
|
+
return native_1.native.bluetoothEnabled();
|
|
46
|
+
}
|
|
47
|
+
identifier() {
|
|
48
|
+
return this.#handle.identifier();
|
|
49
|
+
}
|
|
50
|
+
address() {
|
|
51
|
+
return this.#handle.address();
|
|
52
|
+
}
|
|
53
|
+
isPowered() {
|
|
54
|
+
return this.#handle.isPowered();
|
|
55
|
+
}
|
|
56
|
+
powerOn() {
|
|
57
|
+
return this.#handle.powerOn();
|
|
58
|
+
}
|
|
59
|
+
powerOff() {
|
|
60
|
+
return this.#handle.powerOff();
|
|
61
|
+
}
|
|
62
|
+
scanStart() {
|
|
63
|
+
return this.#handle.scanStart();
|
|
64
|
+
}
|
|
65
|
+
scanStop() {
|
|
66
|
+
return this.#handle.scanStop();
|
|
67
|
+
}
|
|
68
|
+
/** Scans for `timeoutMs` milliseconds, then stops. Other calls on this adapter wait for it. */
|
|
69
|
+
async scanFor(timeoutMs) {
|
|
70
|
+
return this.#handle.scanFor(timeoutMs);
|
|
71
|
+
}
|
|
72
|
+
scanIsActive() {
|
|
73
|
+
return this.#handle.scanIsActive();
|
|
74
|
+
}
|
|
75
|
+
/** The peripherals seen by the current or last scan. */
|
|
76
|
+
scanGetResults() {
|
|
77
|
+
return this.#handle.scanGetResults().map(peripheral_1.Peripheral.wrap);
|
|
78
|
+
}
|
|
79
|
+
getPairedPeripherals() {
|
|
80
|
+
return this.#handle.getPairedPeripherals().then(handles => handles.map(peripheral_1.Peripheral.wrap));
|
|
81
|
+
}
|
|
82
|
+
getConnectedPeripherals() {
|
|
83
|
+
return this.#handle.getConnectedPeripherals().then(handles => handles.map(peripheral_1.Peripheral.wrap));
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* The peripherals CoreBluetooth already knows on macOS, by the identifiers
|
|
87
|
+
* address() returned earlier, without scanning. Unknown identifiers are
|
|
88
|
+
* skipped, and a returned peripheral might be out of range. Other platforms
|
|
89
|
+
* reject with OPERATION_NOT_SUPPORTED.
|
|
90
|
+
*/
|
|
91
|
+
async retrieveCachedPeripherals(identifiers) {
|
|
92
|
+
return (await this.#handle.retrieveCachedPeripherals(identifiers)).map(peripheral_1.Peripheral.wrap);
|
|
93
|
+
}
|
|
94
|
+
/** A host for GATT services of this process, advertised by this adapter. */
|
|
95
|
+
createLocalPeripheral() {
|
|
96
|
+
return local_1.LocalPeripheral.wrap(this.#handle.createLocalPeripheral());
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Stops this adapter's scan and local peripherals, disconnects the
|
|
100
|
+
* peripherals connected through it, and releases the adapter and every object
|
|
101
|
+
* that came from it. Once the promise resolves, a Dongl is free for other
|
|
102
|
+
* programs. Calls on the closed objects then fail with OBJECT_NOT_INITIALIZED,
|
|
103
|
+
* they emit no more events, and getAdapters() returns a new Adapter for the
|
|
104
|
+
* device.
|
|
105
|
+
*/
|
|
106
|
+
close() {
|
|
107
|
+
this.#closing ??= this.#close();
|
|
108
|
+
return this.#closing;
|
|
109
|
+
}
|
|
110
|
+
async [Symbol.asyncDispose]() {
|
|
111
|
+
await this.close();
|
|
112
|
+
}
|
|
113
|
+
removeAllListeners(...args) {
|
|
114
|
+
super.removeAllListeners(...args);
|
|
115
|
+
this.#rehook();
|
|
116
|
+
return this;
|
|
117
|
+
}
|
|
118
|
+
async #close() {
|
|
119
|
+
const key = this.#handle.key();
|
|
120
|
+
// NOTE: A Dongl whose port closes during a scan can stop answering until
|
|
121
|
+
// it's replugged, so the scan and the connections end first. Failures
|
|
122
|
+
// don't stop the release.
|
|
123
|
+
try {
|
|
124
|
+
if (await this.#handle.scanIsActive())
|
|
125
|
+
await this.#handle.scanStop();
|
|
126
|
+
}
|
|
127
|
+
catch { }
|
|
128
|
+
const connections = this.#handle.connections().map(peripheral_1.Peripheral.wrap);
|
|
129
|
+
const hosts = this.#handle.hosts().map(local_1.LocalPeripheral.wrap);
|
|
130
|
+
await Promise.allSettled([...connections.map(peripheral => peripheral.disconnect()), ...hosts.map(host => host.stop())]);
|
|
131
|
+
for (const object of (0, registry_1.registered)()) {
|
|
132
|
+
object[registry_1.releaseFrom]?.(key);
|
|
133
|
+
}
|
|
134
|
+
await this.#handle.close();
|
|
135
|
+
this.removeAllListeners();
|
|
136
|
+
(0, registry_1.unregister)(key, this);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
exports.Adapter = Adapter;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { Adapter } from './adapter';
|
|
2
|
+
/** A source of adapters: the operating system's Bluetooth stack, Dongl or the simulator. */
|
|
3
|
+
export declare class Backend {
|
|
4
|
+
#private;
|
|
5
|
+
private constructor();
|
|
6
|
+
/** Every available backend. */
|
|
7
|
+
static getBackends(): Promise<Backend[]>;
|
|
8
|
+
/** The operating system's Bluetooth backend. */
|
|
9
|
+
static getNative(): Promise<Backend>;
|
|
10
|
+
/** The Dongl backend, regardless of `Config.dongl.useDonglBackend`. */
|
|
11
|
+
static getDongl(): Promise<Backend>;
|
|
12
|
+
static getSimulator(): Promise<Backend>;
|
|
13
|
+
identifier(): string;
|
|
14
|
+
bluetoothEnabled(): Promise<boolean>;
|
|
15
|
+
adapters(): Promise<Adapter[]>;
|
|
16
|
+
}
|
package/dist/backend.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Backend = void 0;
|
|
4
|
+
const adapter_1 = require("./adapter");
|
|
5
|
+
const native_1 = require("./native");
|
|
6
|
+
const registry_1 = require("./registry");
|
|
7
|
+
const construct = Symbol('construct');
|
|
8
|
+
/** A source of adapters: the operating system's Bluetooth stack, Dongl or the simulator. */
|
|
9
|
+
class Backend {
|
|
10
|
+
#handle;
|
|
11
|
+
constructor(token, handle) {
|
|
12
|
+
if (token !== construct)
|
|
13
|
+
throw new TypeError('Use Backend.getBackends()');
|
|
14
|
+
this.#handle = handle;
|
|
15
|
+
}
|
|
16
|
+
/** @internal */
|
|
17
|
+
static wrap(handle) {
|
|
18
|
+
return (0, registry_1.intern)(handle.key(), () => new Backend(construct, handle));
|
|
19
|
+
}
|
|
20
|
+
/** Every available backend. */
|
|
21
|
+
static async getBackends() {
|
|
22
|
+
return (await native_1.native.getBackends()).map(Backend.wrap);
|
|
23
|
+
}
|
|
24
|
+
/** The operating system's Bluetooth backend. */
|
|
25
|
+
static async getNative() {
|
|
26
|
+
return Backend.wrap(await native_1.native.getNativeBackend());
|
|
27
|
+
}
|
|
28
|
+
/** The Dongl backend, regardless of `Config.dongl.useDonglBackend`. */
|
|
29
|
+
static async getDongl() {
|
|
30
|
+
return Backend.wrap(await native_1.native.getDonglBackend());
|
|
31
|
+
}
|
|
32
|
+
static async getSimulator() {
|
|
33
|
+
return Backend.wrap(await native_1.native.getSimulatorBackend());
|
|
34
|
+
}
|
|
35
|
+
identifier() {
|
|
36
|
+
return this.#handle.identifier();
|
|
37
|
+
}
|
|
38
|
+
bluetoothEnabled() {
|
|
39
|
+
return this.#handle.bluetoothEnabled();
|
|
40
|
+
}
|
|
41
|
+
async adapters() {
|
|
42
|
+
return (await this.#handle.adapters()).map(adapter_1.Adapter.wrap);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
exports.Backend = Backend;
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
export interface SimpleBluezConfig {
|
|
2
|
+
/** Reach BlueZ over the D-Bus system bus (true) or the session bus. */
|
|
3
|
+
useSystemBus: boolean;
|
|
4
|
+
/** How long connect() waits for BlueZ, in milliseconds. */
|
|
5
|
+
connectionTimeout: number;
|
|
6
|
+
/** How long disconnect() waits for BlueZ, in milliseconds. */
|
|
7
|
+
disconnectionTimeout: number;
|
|
8
|
+
}
|
|
9
|
+
export interface WinRTConfig {
|
|
10
|
+
experimentalUseOwnMtaApartment: boolean;
|
|
11
|
+
experimentalReinitializeWinrtApartmentOnMainThread: boolean;
|
|
12
|
+
useDeferredDisconnect: boolean;
|
|
13
|
+
}
|
|
14
|
+
export interface DonglConfig {
|
|
15
|
+
/** Include Dongl adapters in Backend.getBackends() and Adapter.getAdapters(). */
|
|
16
|
+
useDonglBackend: boolean;
|
|
17
|
+
autoUpdate: boolean;
|
|
18
|
+
forceUpdate: boolean;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Process-wide settings of each backend. Set them before the first call that
|
|
22
|
+
* reaches a backend; later changes might not take effect.
|
|
23
|
+
*/
|
|
24
|
+
export declare const Config: Readonly<{
|
|
25
|
+
simpleBluez: SimpleBluezConfig & {
|
|
26
|
+
reset(): void;
|
|
27
|
+
};
|
|
28
|
+
winRT: WinRTConfig & {
|
|
29
|
+
reset(): void;
|
|
30
|
+
};
|
|
31
|
+
dongl: DonglConfig & {
|
|
32
|
+
reset(): void;
|
|
33
|
+
};
|
|
34
|
+
/** Restores every backend's defaults. */
|
|
35
|
+
resetAll(): void;
|
|
36
|
+
}>;
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Config = void 0;
|
|
4
|
+
const native_1 = require("./native");
|
|
5
|
+
function setting(name) {
|
|
6
|
+
return {
|
|
7
|
+
get: () => native_1.native.configGet(name),
|
|
8
|
+
set: (value) => native_1.native.configSet(name, value),
|
|
9
|
+
enumerable: true,
|
|
10
|
+
};
|
|
11
|
+
}
|
|
12
|
+
function group(name, settings) {
|
|
13
|
+
const object = { reset: () => native_1.native.configReset(name) };
|
|
14
|
+
for (const [key, descriptor] of Object.entries(settings)) {
|
|
15
|
+
Object.defineProperty(object, key, descriptor);
|
|
16
|
+
}
|
|
17
|
+
return Object.freeze(object);
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Process-wide settings of each backend. Set them before the first call that
|
|
21
|
+
* reaches a backend; later changes might not take effect.
|
|
22
|
+
*/
|
|
23
|
+
exports.Config = Object.freeze({
|
|
24
|
+
simpleBluez: group('simpleBluez', {
|
|
25
|
+
useSystemBus: setting('simpleBluez.useSystemBus'),
|
|
26
|
+
connectionTimeout: setting('simpleBluez.connectionTimeout'),
|
|
27
|
+
disconnectionTimeout: setting('simpleBluez.disconnectionTimeout'),
|
|
28
|
+
}),
|
|
29
|
+
winRT: group('winRT', {
|
|
30
|
+
experimentalUseOwnMtaApartment: setting('winRT.experimentalUseOwnMtaApartment'),
|
|
31
|
+
experimentalReinitializeWinrtApartmentOnMainThread: setting('winRT.experimentalReinitializeWinrtApartmentOnMainThread'),
|
|
32
|
+
useDeferredDisconnect: setting('winRT.useDeferredDisconnect'),
|
|
33
|
+
}),
|
|
34
|
+
dongl: group('dongl', {
|
|
35
|
+
useDonglBackend: setting('dongl.useDonglBackend'),
|
|
36
|
+
autoUpdate: setting('dongl.autoUpdate'),
|
|
37
|
+
forceUpdate: setting('dongl.forceUpdate'),
|
|
38
|
+
}),
|
|
39
|
+
/** Restores every backend's defaults. */
|
|
40
|
+
resetAll() {
|
|
41
|
+
native_1.native.configReset('all');
|
|
42
|
+
},
|
|
43
|
+
});
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/** SimpleBLE's error classification, as in the C++ `SimpleBLE::ErrorCode`. */
|
|
2
|
+
export type ErrorCode = 'INVALID_ARGUMENT' | 'OUT_OF_MEMORY' | 'OBJECT_NOT_INITIALIZED' | 'INVALID_BACKEND_REFERENCE' | 'PERIPHERAL_NOT_CONNECTED' | 'GATT_SERVICE_NOT_FOUND' | 'GATT_CHARACTERISTIC_NOT_FOUND' | 'GATT_DESCRIPTOR_NOT_FOUND' | 'OPERATION_NOT_SUPPORTED' | 'OPERATION_FAILED' | 'WINRT_ACCESS_DENIED' | 'WINRT_EXCEPTION' | 'CORE_BLUETOOTH_EXCEPTION' | 'UNCLASSIFIED_EXCEPTION' | 'ADAPTER_IN_USE';
|
|
3
|
+
/** An error raised by SimpleBLE. */
|
|
4
|
+
export declare class SimpleBLEError extends Error {
|
|
5
|
+
readonly name = "SimpleBLEError";
|
|
6
|
+
readonly code: ErrorCode;
|
|
7
|
+
/** The original HRESULT of a WinRT failure. */
|
|
8
|
+
readonly nativeCode?: number;
|
|
9
|
+
constructor(code: ErrorCode, message: string, nativeCode?: number);
|
|
10
|
+
}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.SimpleBLEError = void 0;
|
|
4
|
+
/** An error raised by SimpleBLE. */
|
|
5
|
+
class SimpleBLEError extends Error {
|
|
6
|
+
name = 'SimpleBLEError';
|
|
7
|
+
code;
|
|
8
|
+
/** The original HRESULT of a WinRT failure. */
|
|
9
|
+
nativeCode;
|
|
10
|
+
constructor(code, message, nativeCode) {
|
|
11
|
+
super(message);
|
|
12
|
+
this.code = code;
|
|
13
|
+
if (nativeCode !== undefined)
|
|
14
|
+
this.nativeCode = nativeCode;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
exports.SimpleBLEError = SimpleBLEError;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|