simplejsble 1.2.1-dev94 → 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 CHANGED
@@ -1,15 +1,34 @@
1
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">
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(), peripheral.address(), peripheral.rssi());
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 run in the order
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 before `connect()`.
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 13.0 or newer | x64, arm64 | Bluetooth permission for the app that runs Node.js |
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 the [usage guide](https://docs.simpleble.org/simplejsble/usage) for
141
- Bluetooth permissions and platform details.
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). See the included [LICENSE](LICENSE.md)
164
- for the complete terms.
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,6 @@
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
5
  export { Logging, type LogEntry, type LogLevel } from './logging';
6
6
  export { LocalCharacteristic, LocalPeripheral, LocalService, type LocalCharacteristicEvents, type LocalPeripheralEvents, } from './local';
@@ -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
  }
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "simplejsble",
3
- "version": "1.2.1-dev94",
3
+ "version": "1.3.0-dev.188",
4
4
  "description": "SimpleBLE for Node.js and Electron: a cross-platform Bluetooth Low Energy library",
5
5
  "keywords": [
6
6
  "bluetooth",