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 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
+ }
@@ -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
+ }
@@ -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;
@@ -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
+ });
@@ -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 {};