simplejsble 1.2.1-dev90 → 1.3.0-dev.188
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/README.md +37 -21
- package/dist/config.d.ts +9 -2
- package/dist/config.js +3 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +3 -1
- package/dist/logging.d.ts +22 -0
- package/dist/logging.js +38 -0
- package/dist/peripheral.d.ts +7 -0
- package/dist/peripheral.js +9 -0
- package/package.json +1 -1
- 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/README.md
CHANGED
|
@@ -1,15 +1,34 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<
|
|
3
|
-
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/simpleble/simpleble/main/docs/public/simpleBLE-logo.png">
|
|
4
|
+
<img src="https://raw.githubusercontent.com/simpleble/simpleble/main/docs/public/simpleBLE-logo-dark.png" alt="SimpleBLE" width="360">
|
|
5
|
+
</picture>
|
|
4
6
|
</p>
|
|
5
7
|
|
|
6
8
|
# SimpleJSBLE
|
|
7
9
|
|
|
10
|
+
**Build Bluetooth once. Ship it everywhere.**
|
|
11
|
+
|
|
8
12
|
SimpleJSBLE brings [SimpleBLE](https://github.com/simpleble/simpleble) to Node.js
|
|
9
13
|
and Electron on Windows, macOS, and Linux. Discover and connect Bluetooth
|
|
10
14
|
peripherals, read and write GATT values, subscribe to notifications, and host
|
|
11
15
|
local GATT services through one API, with TypeScript types included.
|
|
12
16
|
|
|
17
|
+
## Why SimpleJSBLE
|
|
18
|
+
|
|
19
|
+
- **One cross-platform API:** Keep your Bluetooth code the same in Node.js and Electron on Windows, macOS, and Linux.
|
|
20
|
+
- **Native underneath:** Use WinRT, CoreBluetooth, and BlueZ through one maintained stack.
|
|
21
|
+
- **Built for real products:** Act as a central or a peripheral on every supported platform.
|
|
22
|
+
- **Commercially supported:** Ship proprietary applications with commercial licensing and direct technical support from the team that builds SimpleBLE.
|
|
23
|
+
|
|
24
|
+
## Support and resources
|
|
25
|
+
|
|
26
|
+
- **Documentation:** The [usage guide](https://docs.simpleble.org/simplejsble/usage?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=support) and [examples](https://github.com/simpleble/simpleble/tree/main/examples/simplejsble) cover every API.
|
|
27
|
+
- **Commercial support:** Visit [simpleble.org](https://simpleble.org/?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=support) or [email us](mailto:contact@simpleble.org) about licensing and professional services.
|
|
28
|
+
- **Community:** Ask questions and share projects in [GitHub Discussions](https://github.com/simpleble/simpleble/discussions).
|
|
29
|
+
- **Dongl:** Prototype and ship with the [official SimpleBLE USB adapter](https://www.simpleble.org/dongl?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=support).
|
|
30
|
+
- **Contribute:** Send changes to [simpleble/simpleble](https://github.com/simpleble/simpleble/tree/main/simplejsble); the [publishing guide](https://github.com/simpleble/simpleble/blob/main/docs/extras/simplejsble-publishing.md) covers builds and releases.
|
|
31
|
+
|
|
13
32
|
## Get started
|
|
14
33
|
|
|
15
34
|
Use Node.js 22 or newer:
|
|
@@ -29,7 +48,7 @@ import { Adapter } from 'simplejsble';
|
|
|
29
48
|
const [adapter] = await Adapter.getAdapters();
|
|
30
49
|
|
|
31
50
|
adapter.on('scanFound', peripheral => {
|
|
32
|
-
console.log(peripheral.identifier()
|
|
51
|
+
console.log(`${peripheral.identifier()} [${peripheral.address()}] ${peripheral.rssi()} dBm`);
|
|
33
52
|
});
|
|
34
53
|
await adapter.scanFor(5000);
|
|
35
54
|
```
|
|
@@ -46,8 +65,8 @@ and `scanGetResults()` for the peripherals seen by the last scan. An adapter
|
|
|
46
65
|
always gives you the same `Peripheral` object for the same device, whether it
|
|
47
66
|
came from an event or from a list.
|
|
48
67
|
|
|
49
|
-
Calls that talk to the Bluetooth stack return promises and
|
|
50
|
-
they were made. Data the library already holds, such as a peripheral's
|
|
68
|
+
Calls that talk to the Bluetooth stack return promises, and calls on one
|
|
69
|
+
object run in the order they were made. Data the library already holds, such as a peripheral's
|
|
51
70
|
`identifier()`, `rssi()`, or `manufacturerData()`, is returned directly. An
|
|
52
71
|
active scan or connection keeps Node.js running until it ends.
|
|
53
72
|
|
|
@@ -101,7 +120,7 @@ changing them.
|
|
|
101
120
|
|
|
102
121
|
## Use a Dongl
|
|
103
122
|
|
|
104
|
-
A [Dongl](https://docs.simpleble.org/dongl) is a USB Bluetooth adapter made for
|
|
123
|
+
A [Dongl](https://docs.simpleble.org/dongl?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=dongl) is a USB Bluetooth adapter made for
|
|
105
124
|
SimpleBLE. Its backend is on by default; use the adapters of the Dongl backend:
|
|
106
125
|
|
|
107
126
|
```js
|
|
@@ -121,7 +140,8 @@ Dongl for other programs. Adapters also support `await using`.
|
|
|
121
140
|
`Config` holds the Dongl, BlueZ, and WinRT backend settings; set them before the
|
|
122
141
|
first call that reaches a backend. Pairing through a Dongl happens without the
|
|
123
142
|
operating system: set `setPasskeyRequestHandler`, `setPasskeyDisplayHandler`, or
|
|
124
|
-
`setNumericComparisonHandler` on the peripheral
|
|
143
|
+
`setNumericComparisonHandler` on the peripheral, and await the promise it
|
|
144
|
+
returns, before `connect()`.
|
|
125
145
|
|
|
126
146
|
## Electron
|
|
127
147
|
|
|
@@ -133,12 +153,12 @@ apps need an `NSBluetoothAlwaysUsageDescription` entry in their `Info.plist`.
|
|
|
133
153
|
|
|
134
154
|
| Platform | Architectures | Requirements |
|
|
135
155
|
| --- | --- | --- |
|
|
136
|
-
| macOS
|
|
156
|
+
| macOS 15.0 or newer | x64, arm64 | Bluetooth permission for the app that runs Node.js |
|
|
137
157
|
| Windows 10 or newer | x64, arm64 | |
|
|
138
158
|
| Linux with glibc 2.28 or newer | x64, arm64 | BlueZ and the D-Bus library |
|
|
139
159
|
|
|
140
|
-
See
|
|
141
|
-
|
|
160
|
+
See [Bluetooth permissions](https://docs.simpleble.org/fundamentals/permissions?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=platforms)
|
|
161
|
+
for the setup each platform needs.
|
|
142
162
|
|
|
143
163
|
## Versions
|
|
144
164
|
|
|
@@ -149,20 +169,16 @@ under the `latest` tag, and development builds of the main branch under `dev`:
|
|
|
149
169
|
npm install simplejsble@dev
|
|
150
170
|
```
|
|
151
171
|
|
|
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
172
|
## License
|
|
161
173
|
|
|
162
174
|
SimpleJSBLE follows the [SimpleBLE license](https://github.com/simpleble/simpleble/blob/main/LICENSE.md),
|
|
163
|
-
the Business Source License 1.1 (BUSL-1.1).
|
|
164
|
-
|
|
175
|
+
the Business Source License 1.1 (BUSL-1.1). It is free for non-commercial use,
|
|
176
|
+
and commercial use needs a commercial license. We offer free commercial licenses
|
|
177
|
+
for small projects and early-stage companies: [email us](mailto:contact@simpleble.org)
|
|
178
|
+
or [leave us a message](https://www.simpleble.org/contact?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=license) to discuss your use
|
|
179
|
+
case. Commercial licenses carry no royalties or revenue sharing; see the
|
|
180
|
+
[licensing page](https://docs.simpleble.org/licensing?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=license) for terms.
|
|
165
181
|
|
|
166
182
|
---
|
|
167
183
|
|
|
168
|
-
**SimpleBLE** is a project powered by [The California Open Source Company](https://californiaopensource.com
|
|
184
|
+
**SimpleBLE** is a project powered by [The California Open Source Company](https://californiaopensource.com/?utm_source=npm&utm_medium=referral&utm_campaign=simplejsble_readme&utm_content=footer).
|
package/dist/config.d.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
export interface SimpleBluezConfig {
|
|
2
2
|
/** Reach BlueZ over the D-Bus system bus (true) or the session bus. */
|
|
3
3
|
useSystemBus: boolean;
|
|
4
|
-
/** How long connect() waits for BlueZ, in milliseconds. */
|
|
4
|
+
/** How long connect() waits for BlueZ, in milliseconds. Fractions round up. */
|
|
5
5
|
connectionTimeout: number;
|
|
6
|
-
/** How long disconnect() waits for BlueZ, in milliseconds. */
|
|
6
|
+
/** How long disconnect() waits for BlueZ, in milliseconds. Fractions round up. */
|
|
7
7
|
disconnectionTimeout: number;
|
|
8
8
|
}
|
|
9
9
|
export interface WinRTConfig {
|
|
@@ -11,6 +11,10 @@ export interface WinRTConfig {
|
|
|
11
11
|
experimentalReinitializeWinrtApartmentOnMainThread: boolean;
|
|
12
12
|
useDeferredDisconnect: boolean;
|
|
13
13
|
}
|
|
14
|
+
export interface AndroidConfig {
|
|
15
|
+
/** Negotiate MTU on connect. Defaults to true. */
|
|
16
|
+
negotiateMtu: boolean;
|
|
17
|
+
}
|
|
14
18
|
export interface DonglConfig {
|
|
15
19
|
/** Include Dongl adapters in Backend.getBackends() and Adapter.getAdapters(). */
|
|
16
20
|
useDonglBackend: boolean;
|
|
@@ -28,6 +32,9 @@ export declare const Config: Readonly<{
|
|
|
28
32
|
winRT: WinRTConfig & {
|
|
29
33
|
reset(): void;
|
|
30
34
|
};
|
|
35
|
+
android: AndroidConfig & {
|
|
36
|
+
reset(): void;
|
|
37
|
+
};
|
|
31
38
|
dongl: DonglConfig & {
|
|
32
39
|
reset(): void;
|
|
33
40
|
};
|
package/dist/config.js
CHANGED
|
@@ -31,6 +31,9 @@ exports.Config = Object.freeze({
|
|
|
31
31
|
experimentalReinitializeWinrtApartmentOnMainThread: setting('winRT.experimentalReinitializeWinrtApartmentOnMainThread'),
|
|
32
32
|
useDeferredDisconnect: setting('winRT.useDeferredDisconnect'),
|
|
33
33
|
}),
|
|
34
|
+
android: group('android', {
|
|
35
|
+
negotiateMtu: setting('android.negotiateMtu'),
|
|
36
|
+
}),
|
|
34
37
|
dongl: group('dongl', {
|
|
35
38
|
useDonglBackend: setting('dongl.useDonglBackend'),
|
|
36
39
|
autoUpdate: setting('dongl.autoUpdate'),
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
export { Adapter, type AdapterEvents } from './adapter';
|
|
2
2
|
export { Backend } from './backend';
|
|
3
|
-
export { Config, type DonglConfig, type SimpleBluezConfig, type WinRTConfig } from './config';
|
|
3
|
+
export { Config, type AndroidConfig, type DonglConfig, type SimpleBluezConfig, type WinRTConfig } from './config';
|
|
4
4
|
export { SimpleBLEError, type ErrorCode } from './errors';
|
|
5
|
+
export { Logging, type LogEntry, type LogLevel } from './logging';
|
|
5
6
|
export { LocalCharacteristic, LocalPeripheral, LocalService, type LocalCharacteristicEvents, type LocalPeripheralEvents, } from './local';
|
|
6
7
|
export { Peripheral, type BluetoothAddressType, type Characteristic, type CharacteristicCapability, type Descriptor, type PeripheralEvents, type Service, } from './peripheral';
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.Peripheral = exports.LocalService = exports.LocalPeripheral = exports.LocalCharacteristic = exports.SimpleBLEError = exports.Config = exports.Backend = exports.Adapter = void 0;
|
|
3
|
+
exports.Peripheral = exports.LocalService = exports.LocalPeripheral = exports.LocalCharacteristic = exports.Logging = exports.SimpleBLEError = exports.Config = exports.Backend = exports.Adapter = void 0;
|
|
4
4
|
const errors_1 = require("./errors");
|
|
5
5
|
const handlers_1 = require("./handlers");
|
|
6
6
|
const native_1 = require("./native");
|
|
@@ -39,6 +39,8 @@ var config_1 = require("./config");
|
|
|
39
39
|
Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_1.Config; } });
|
|
40
40
|
var errors_2 = require("./errors");
|
|
41
41
|
Object.defineProperty(exports, "SimpleBLEError", { enumerable: true, get: function () { return errors_2.SimpleBLEError; } });
|
|
42
|
+
var logging_1 = require("./logging");
|
|
43
|
+
Object.defineProperty(exports, "Logging", { enumerable: true, get: function () { return logging_1.Logging; } });
|
|
42
44
|
var local_1 = require("./local");
|
|
43
45
|
Object.defineProperty(exports, "LocalCharacteristic", { enumerable: true, get: function () { return local_1.LocalCharacteristic; } });
|
|
44
46
|
Object.defineProperty(exports, "LocalPeripheral", { enumerable: true, get: function () { return local_1.LocalPeripheral; } });
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/** SimpleBLE's log levels, from 'none' (off) to the most detailed, 'verbose'. */
|
|
2
|
+
export type LogLevel = 'none' | 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
|
|
3
|
+
/** One entry of SimpleBLE's log. */
|
|
4
|
+
export interface LogEntry {
|
|
5
|
+
readonly level: Exclude<LogLevel, 'none'>;
|
|
6
|
+
/** The component that logged it, such as `SimpleBLE` or `SimpleBLE->SimpleBluez`. */
|
|
7
|
+
readonly module: string;
|
|
8
|
+
readonly file: string;
|
|
9
|
+
readonly line: number;
|
|
10
|
+
readonly function: string;
|
|
11
|
+
readonly message: string;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* SimpleBLE's log, process-wide. By default, entries up to 'info' go to
|
|
15
|
+
* standard output.
|
|
16
|
+
*/
|
|
17
|
+
export declare const Logging: {
|
|
18
|
+
level: LogLevel;
|
|
19
|
+
setCallback(callback: ((entry: LogEntry) => void) | null): void;
|
|
20
|
+
logToStdout(): void;
|
|
21
|
+
logToFile(path?: string): void;
|
|
22
|
+
};
|
package/dist/logging.js
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Logging = void 0;
|
|
4
|
+
const native_1 = require("./native");
|
|
5
|
+
/**
|
|
6
|
+
* SimpleBLE's log, process-wide. By default, entries up to 'info' go to
|
|
7
|
+
* standard output.
|
|
8
|
+
*/
|
|
9
|
+
exports.Logging = Object.freeze({
|
|
10
|
+
/** The most detailed level that is logged; 'none' turns logging off. */
|
|
11
|
+
get level() {
|
|
12
|
+
return native_1.native.loggingGetLevel();
|
|
13
|
+
},
|
|
14
|
+
set level(level) {
|
|
15
|
+
native_1.native.loggingSetLevel(level);
|
|
16
|
+
},
|
|
17
|
+
/**
|
|
18
|
+
* Delivers each entry to `callback` on the JavaScript thread, in the order
|
|
19
|
+
* they were logged, instead of writing it out. null discards entries.
|
|
20
|
+
*/
|
|
21
|
+
setCallback(callback) {
|
|
22
|
+
if (callback === null) {
|
|
23
|
+
native_1.native.loggingSetCallback(null);
|
|
24
|
+
return;
|
|
25
|
+
}
|
|
26
|
+
if (typeof callback !== 'function')
|
|
27
|
+
throw new TypeError('callback must be a function or null');
|
|
28
|
+
native_1.native.loggingSetCallback(entry => callback(Object.freeze(entry)));
|
|
29
|
+
},
|
|
30
|
+
/** Writes entries to standard output, the default. */
|
|
31
|
+
logToStdout() {
|
|
32
|
+
native_1.native.loggingToStdout();
|
|
33
|
+
},
|
|
34
|
+
/** Appends entries to `path`, or to a new timestamped file in the working directory. */
|
|
35
|
+
logToFile(path) {
|
|
36
|
+
native_1.native.loggingToFile(path);
|
|
37
|
+
},
|
|
38
|
+
});
|
package/dist/peripheral.d.ts
CHANGED
|
@@ -73,5 +73,12 @@ export declare class Peripheral extends EventEmitter<PeripheralEvents> {
|
|
|
73
73
|
* return a promise.
|
|
74
74
|
*/
|
|
75
75
|
setNumericComparisonHandler(handler: ((passkey: string) => boolean | Promise<boolean>) | null): Promise<void>;
|
|
76
|
+
/**
|
|
77
|
+
* Secures a Dongl connection with LE Secure Connections. With `mitm`, the
|
|
78
|
+
* peer must also be authenticated through the passkey or numeric comparison
|
|
79
|
+
* handlers. Pairing started by this call creates no bond, and the Dongl
|
|
80
|
+
* disconnects if it fails.
|
|
81
|
+
*/
|
|
82
|
+
secureConnection(mitm?: boolean): Promise<void>;
|
|
76
83
|
removeAllListeners(...args: Parameters<EventEmitter<PeripheralEvents>['removeAllListeners']>): this;
|
|
77
84
|
}
|
package/dist/peripheral.js
CHANGED
|
@@ -166,6 +166,15 @@ class Peripheral extends node_events_1.EventEmitter {
|
|
|
166
166
|
setNumericComparisonHandler(handler) {
|
|
167
167
|
return this.#numericComparison.set(handler, id => this.#handle.setNumericComparisonHandler(id));
|
|
168
168
|
}
|
|
169
|
+
/**
|
|
170
|
+
* Secures a Dongl connection with LE Secure Connections. With `mitm`, the
|
|
171
|
+
* peer must also be authenticated through the passkey or numeric comparison
|
|
172
|
+
* handlers. Pairing started by this call creates no bond, and the Dongl
|
|
173
|
+
* disconnects if it fails.
|
|
174
|
+
*/
|
|
175
|
+
async secureConnection(mitm = false) {
|
|
176
|
+
return this.#handle.secureConnection(mitm);
|
|
177
|
+
}
|
|
169
178
|
removeAllListeners(...args) {
|
|
170
179
|
super.removeAllListeners(...args);
|
|
171
180
|
this.#rehook();
|
package/package.json
CHANGED
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|