Skip to content

Commit 4732410

Browse files
author
Daisuke Baba
committed
Merge branch 'release/4.0.0'
2 parents 535df1d + 6816439 commit 4732410

25 files changed

+13233
-6251
lines changed

‎.babelrc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"presets": [
3+
[
4+
"@babel/preset-env",
5+
{
6+
"targets": {
7+
"node": "current"
8+
}
9+
}
10+
]
11+
],
12+
"env": {
13+
"test": {
14+
"plugins": [
15+
"@babel/plugin-transform-modules-commonjs"
16+
]
17+
}
18+
}
19+
}

‎.eslintrc.js‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
module.exports = {
2+
root: true,
3+
env: {
4+
browser: false,
5+
node: true,
6+
es6: true,
7+
mocha: true,
8+
jest: true
9+
},
10+
parserOptions: {
11+
parser: 'babel-eslint',
12+
sourceType: 'module',
13+
ecmaVersion: 9
14+
},
15+
extends: [
16+
'plugin:prettier/recommended',
17+
'prettier',
18+
'eslint:recommended',
19+
],
20+
plugins: [
21+
'prettier'
22+
],
23+
rules: {
24+
}
25+
}

‎.jshintrc‎

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎.prettierrc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"semi": true,
3+
"singleQuote": true
4+
}

‎.travis.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
language: node_js
22
node_js:
3-
- "8"
43
- "10"
4+
- "12"
55

66
addons:
77
apt:

‎CHANGELOG.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Revision History
2+
3+
* 4.0.0
4+
- The node category is now `Network` rather than `Input` and `Output`.
5+
- Improve stability on Linux by introducing BlueZ 5 D-Bus API
6+
- On Linux, this node is no longer dependent on the HCI socket library, which has lots of problematic issues that caused inconsistent results with old BlueZ CLI tools.
7+
- Note that when Node-RED process is run by non-root user, add the user to `bluetooth` group so to access BlueZ D-Bus API. For example, run `sudo usermod -G bluetooth -a pi` prior to starting the process if it's run by `pi` user.
8+
- BlueZ's BLE scanning seems to detect devices having `random` address type. But not sure if such devices work with this node properly.
9+
- Tested on Raspbian (4.19.97-v7l+) and Raspberry Pi 3/4.
10+
- With the following packages
11+
- bluez 5.50-1.2~deb10u1
12+
- bluez-firmware 1.2-4+rpt2
13+
- Improve BLE Device Scanning UI/UX
14+
- Check `BLE Scanning` in order to start scanning, and `Scan Result` select box will be fullfilled automatically whenever devices are found. The update will be performed every 10 seconds. The first scan result will appear after 5 seconds since the scanning starts. See the updated README document for detail.
15+
- `GENERIC_BLE_TRACE` environment variable is no longer working. Use `DEBUG` environment variable instead.
16+
- `DEBUG=node-red-contrib-generic-ble:index` is compatible with `GENERIC_BLE_TRACE=true`.
17+
- `DEBUG=node-red-contrib-generic-ble:*` will output all trace logs within the project.
18+
- `DEBUG=node-red-contrib-generic-ble:index:api` will output all API endpoint access logs.
19+
- `DEBUG=node-red-contrib-generic-ble:noble:*` will output all trace logs under `src/noble` modules.
20+
21+
* 3.1.0
22+
- Support Node.js v10.x LTS (Fix #14 and #17)
23+
24+
* 3.0.0
25+
- Refactor entire architecture
26+
- Peripheral connections are retained until it disconnects
27+
- Characteristic subscriptions are retained while the ongoing flows are running (will be unsubscribed on stopping them though)
28+
- The max number of concurrent BLE connections is 5 or 6 according to [this document](https://github.com/noble/noble#maximum-simultaneous-connections)
29+
30+
* 2.0.4
31+
- Fix an issue where this node don't work with [email protected]
32+
33+
* 2.0.3
34+
- Fix an issue where noble looses a reference to a peripheral after it is disconnected
35+
36+
* 2.0.2
37+
- Fix an issue where Write operation cannot be performed properly (#4)
38+
39+
* 2.0.1
40+
- Fix an issue where `Select from scan result` failed to list characteristics
41+
42+
* 2.0.0
43+
- Add `Poll Notify Events` message support so that Generic BLE out node can start to subscribe the given characteristic events
44+
- Support characteristic query by one or more uuids
45+
- Add `Mute Notify Events` to `Generic BLE` config node for this node to avoid unnecessary device connection for event subscription
46+
- Replace `RED.log` functions with node logging functions as possible to offer precise logging control via UI
47+
- Add `Operation Timeout` to `Generic BLE` config node to set the waiting time for Read/Write/Notify response **per characteristic** rather than per device
48+
- `GENERIC_BLE_OPERATION_WAIT_MS` is introduced for default `Operation Timeout` value
49+
- Remove `Listening Period` from `Generic BLE` config node
50+
- `GENERIC_BLE_NOTIFY_WAIT_MS` is removed
51+
52+
* 1.0.2
53+
- Improve README
54+
- Add an example flow file available from the editor UI
55+
56+
* 1.0.1
57+
- Fix an issue where custom characteristics cannot be listed on the Generic BLE config node dialog
58+
59+
* 1.0.0
60+
- Fix an issue where some devices cannot be discovered within a specific time window even after they can be connected
61+
- Fix an issue where the Scan Result select widget didn't show the same item as the stored device info
62+
- Update Scan Result option list whenever Local Name is resolved
63+
- Improve stability by fixing minor bugs
64+
65+
* 0.1.0
66+
- Initial Release (alpha)
67+
- `node-red` keyword is not yet added

‎README.md‎

Lines changed: 55 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,74 @@
11
node-red-contrib-generic-ble
22
===
33

4-
A Node-RED node for providing access to generic BLE devices via GATT.
4+
A Node-RED node for providing access to generic BLE **peripheral** devices via GATT.
5+
6+
As of v4.0.0, this node is optmized for Linux with BlueZ 5 D-Bus API (HCI socket is no longer used on Linux).
7+
macOS and Windows should still work as nothing is modified for these platforms.
58

69
Supported operations are as follows:
710

811
- Read
912
- Write
1013
- Write without Response
11-
- Notify
14+
- Notify (Subscribing the Notify events)
1215

13-
# How to use
16+
The node status modes are as follows:
17+
18+
- `missing` the configured BLE peripheral device is missing.　When the device is discovered, the state transitions to `disconnected`. The `disconnected` device may transiton to `missing` again when RSSI is invalidated (Linux only)
19+
- `disconnected` when the configured BLE peripheral device is found but not conncted
20+
- `connecting` when the configured BLE peripheral device is being connecting
21+
- `connected` when the configured BLE peripheral device is connected
22+
- `disconnecting` when the configured BLE peripheral device is being disconnecting
23+
- `error` when unexpected error occurs
1424

15-
## How to configure a new BLE peripheral
25+
Known issues for Linux BlueZ D-Bus API:
1626

17-
At first, drag either a `generic ble in` node or a `generic ble out` node to the workspace from the node palette and double-click the node. And you can find the following dialog. Here, click the pencil icon (`1`) to add a new BLE peripheral or edit the existing one.
27+
- Unlike the oler version, **you must set the process owner's permission properly and manually**. Non-root user's Node-RED process will fail to get this node working. Read `Installation Note (Linux)` below.
28+
- It seems the local name in advertisement packet isn't transferred to `LocalName` property in org.bluez.Device1 BlueZ D-Bus API. With the HCI socket implementaion, the local name was resolved. So the local name can be resolved on macOS and Windows.
29+
- `Bluetooth: hci0: hardware error 0x03` error sometimes occurs (and logged in syslog). When it's observed, all devices are disconnected and cahches are gone. The node tries to power on the BLE adapter again.
1830

19-
![ble in node](images/ble1.png)
31+
# How to use
2032

21-
Then the new config node dialog appears like this.
33+
## How to configure a new BLE peripheral device
2234

23-
![ble config node](images/ble2.png)
35+
At first, drag either a `Generic BLE in` node or a `Generic BLE out` node to the workspace from the node palette and double-click the node. And you can find the following dialog. Here, click the pencil icon (`1`) to add a new BLE peripheral or edit the existing one.
2436

25-
The `Scan Result` shows the scanned BLE peripherals. It can be empty when no peripherals are found.
37+
![ble out node](images/ble1.png)
2638

27-
In order for the dialog to list your device, turn BLE on prior to open the dialog. Close the dialog then re-open it if you'd like to get the latest scan result.
39+
Then the new config node dialog appears as shown below.
2840

29-
By default, you have to enter either MAC address or UUID manually to configure your BLE peripheral. However, by checking `Select from scan result`(`2`), you can choose the peripheral if it exists in the scan result.
41+
The `BLE Scanning` shows whether or not BLE scanning is going on. In order to start BLE scanning, check it (`2`).
42+
43+
![ble config node](images/ble2.png)
44+
45+
As soon as you check it, `Scan Result` select box and `Apply` button appear. The scan results are automatically fufilled in the select box. The content will be refreshed every 10 seconds.
3046

3147
![ble config node](images/ble3.png)
3248

33-
When you choose the peripheral, `GATT Characteristics` shows all characteristics discovered in it, and `Local Name`, `MAC` and `UUID` are automatically resolved as well.
49+
Chosoe one of the listed devices and then click `Apply` to populate `Local Name`, `MAC` and `UUID` input text boxes. Clicking `Apply` button also triggers GATT characteristics discovery as well.
50+
51+
The following picure shows the `Apply` button clicking results. `GATT Characteristics` has a characteristic list of the selected device. When you see `(not available)` message in the box, check if the device is NOT sleeping (a sleeping device fails to respond to a connect request) and click `Apply` again.
3452

35-
If you cannot find your peripheral in the `Scan Result`, you can reload the result by closing this dialog and re-opening it as described above.
53+
`GATT Characteristics` must be populated as the node uses the list to verify if a given characteristic UUID is valid on performing `Read`, `Write` and `Subscribe` requests.
3654

37-
Click `Add` (`3`) when the information on the dialog looks good.
55+
Click `Add` (`3`) to save the information when everything is OK.
3856

3957
![ble config node](images/ble4.png)
4058

41-
Click `Done` (`4`) to finish the `ble in` node settings.
59+
Now back to `Generic BLE out` node.
60+
Click `Done` (`4`) to finish the `Generic BLE out` node settings.
61+
62+
![ble config node](images/ble5.png)
63+
64+
You can also import an example flow from the menu icon(`三`) > Import > Examples > node-red-contrib-generic-ble > 01-read-write for learning more about this node.
4265

4366
## How to translate gatttool command into flow
4467

4568
In this example, we show how to describe `gatttool` commands for characteristic value write and read with Generic BLE nodes.
4669

70+
**NOTICE: As of BlueZ 5, gatttool is deprecated. gatttool will be removed in the future relesase.**
71+
4772
### Characteristics Value Write
4873

4974
The following simple command line just issues a characteristic write request to the handle `0x0027`, which the BLE peripheral associates with the characteristic uuid `f000aa02-0451-4000-b000-000000000000`(uuids and handles can be listed by `gatttool -b 88:99:00:00:FF:FF --characteristics command`).
@@ -149,11 +174,22 @@ See `info` tab for detail on the editor UI.
149174

150175
# Example Flow
151176

152-
You can import [the example flow](examples/01-read-write.json) on Node-RED UI. You need to change Generic BLE config node named `nRF5x` or add a new config node for your device.
177+
You can import [the example flow](examples/01-read-write.json) on Node-RED UI.
178+
179+
# Installation Note (Linux)
180+
181+
The Node-RED process owner must belong to `bluetooth` group in order to access BlueZ D-Bus API, otherwise this node doesn't work at all because of bluetoothd permission issue.
182+
For example, if you're going to run the process by `pi` user, run the following command.
183+
184+
```
185+
sudo usermod -G bluetooth -a pi
186+
```
153187

154-
# How to install
188+
Then reboot the OS so that the policy changes take effect.
155189

156-
This will take approx. 3 minutes on Raspberry Pi 3.
190+
```
191+
sudo reboot
192+
```
157193

158194
## Node-RED users
159195

@@ -163,7 +199,7 @@ cd ~/.node-red
163199
npm install node-red-contrib-generic-ble
164200
```
165201

166-
Then restart Node-RED process.
202+
Then restart Node-RED process. Again, for Linux users, read the above chapter `Installation Note (Linux)` to get this node working.
167203

168204
## CANDY RED users
169205

@@ -189,70 +225,3 @@ $ NODE_ENV=development npm run build
189225
# package
190226
$ NODE_ENV=development npm pack
191227
```
192-
193-
## HCI Dump Debugging (Raspbian/Ubuntu/Debian)
194-
195-
```
196-
sudo apt-get update
197-
sudo apt-get install bluez-hcidump
198-
```
199-
200-
then
201-
202-
```
203-
sudo hcidump -t -x
204-
```
205-
206-
## Enabling trace log
207-
208-
Set `GENERIC_BLE_TRACE=true` on starting Node-RED and you can find the precise log in `/var/log/syslog`.
209-
210-
# Revision History
211-
212-
* 3.1.0
213-
- Support Node.js v10.x LTS (Fix #14 and #17)
214-
215-
* 3.0.0
216-
- Refactor entire architecture
217-
- Peripheral connections are retained until it disconnects
218-
- Characteristic subscriptions are retained while the ongoing flows are running (will be unsubscribed on stopping them though)
219-
- The max number of concurrent BLE connections is 5 or 6 according to [this document](https://github.com/noble/noble#maximum-simultaneous-connections)
220-
221-
* 2.0.4
222-
- Fix an issue where this node don't work with [email protected]
223-
224-
* 2.0.3
225-
- Fix an issue where noble looses a reference to a peripheral after it is disconnected
226-
227-
* 2.0.2
228-
- Fix an issue where Write operation cannot be performed properly (#4)
229-
230-
* 2.0.1
231-
- Fix an issue where `Select from scan result` failed to list characteristics
232-
233-
* 2.0.0
234-
- Add `Poll Notify Events` message support so that Generic BLE out node can start to subscribe the given characteristic events
235-
- Support characteristic query by one or more uuids
236-
- Add `Mute Notify Events` to `Generic BLE` config node for this node to avoid unnecessary device connection for event subscription
237-
- Replace `RED.log` functions with node logging functions as possible to offer precise logging control via UI
238-
- Add `Operation Timeout` to `Generic BLE` config node to set the waiting time for Read/Write/Notify response **per characteristic** rather than per device
239-
- `GENERIC_BLE_OPERATION_WAIT_MS` is introduced for default `Operation Timeout` value
240-
- Remove `Listening Period` from `Generic BLE` config node
241-
- `GENERIC_BLE_NOTIFY_WAIT_MS` is removed
242-
243-
* 1.0.2
244-
- Improve README
245-
- Add an example flow file available from the editor UI
246-
247-
* 1.0.1
248-
- Fix an issue where custom characteristics cannot be listed on the Generic BLE config node dialog
249-
250-
* 1.0.0
251-
- Fix an issue where some devices cannot be discovered within a specific time window even after they can be connected
252-
- Fix an issue where the Scan Result select widget didn't show the same item as the stored device info
253-
- Update Scan Result option list whenever Local Name is resolved
254-
- Improve stability by fixing minor bugs
255-
256-
* 0.1.0
257-
- Initial Release (alpha)
258-
- `node-red` keyword is not yet added

0 commit comments

Comments
 (0)