{"id":14978086,"url":"https://github.com/candy-line/node-red-contrib-generic-ble","last_synced_at":"2025-10-28T08:31:51.783Z","repository":{"id":22573577,"uuid":"96719580","full_name":"CANDY-LINE/node-red-contrib-generic-ble","owner":"CANDY-LINE","description":"A Node-RED node set for providing access to generic BLE peripheral GATT characteristics.","archived":false,"fork":false,"pushed_at":"2023-02-14T18:20:22.000Z","size":4185,"stargazers_count":24,"open_issues_count":32,"forks_count":22,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-09-29T01:01:19.382Z","etag":null,"topics":["ble","bluez","bluez-dbus","gatt","gatttool","node-red","peripheral","raspberry-pi-3"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CANDY-LINE.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-10T00:22:52.000Z","updated_at":"2022-11-24T13:26:27.000Z","dependencies_parsed_at":"2024-06-21T05:45:01.873Z","dependency_job_id":"49e07dfb-5580-4f68-8fb6-d2672e8826bb","html_url":"https://github.com/CANDY-LINE/node-red-contrib-generic-ble","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CANDY-LINE%2Fnode-red-contrib-generic-ble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CANDY-LINE%2Fnode-red-contrib-generic-ble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CANDY-LINE%2Fnode-red-contrib-generic-ble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CANDY-LINE%2Fnode-red-contrib-generic-ble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CANDY-LINE","download_url":"https://codeload.github.com/CANDY-LINE/node-red-contrib-generic-ble/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859904,"owners_count":16556031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluez","bluez-dbus","gatt","gatttool","node-red","peripheral","raspberry-pi-3"],"created_at":"2024-09-24T13:56:50.702Z","updated_at":"2025-10-28T08:31:46.363Z","avatar_url":"https://github.com/CANDY-LINE.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"node-red-contrib-generic-ble\n===\n\n[![GitHub release](https://img.shields.io/github/release/CANDY-LINE/node-red-contrib-generic-ble.svg)](https://github.com/CANDY-LINE/node-red-contrib-generic-ble/releases/latest)\n[![master Build Status](https://travis-ci.org/CANDY-LINE/node-red-contrib-generic-ble.svg?branch=master)](https://travis-ci.org/CANDY-LINE/node-red-contrib-generic-ble/)\n\nA Node-RED node set for providing access to generic BLE **peripheral** GATT characteristics.\n\nAs of v4.0.0, this node is optmized for Linux with BlueZ 5 D-Bus API (HCI socket is no longer used on Linux).\nThe node should still work on macOS and Windows as nothing is modified for these platforms.\n\nSupported operations are as follows:\n\n- Start BLE Scanning\n- Stop BLE Scanning\n- Restart BLE Scanning (Stop then start BLE Scanning again)\n- Connect to a peripheral device\n- Disonnect from a peripheral device\n- Read\n- Write\n- Write without Response\n- Notify (Subscribing the Notify events)\n\nThe node status modes are as follows:\n\n- `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)\n- `disconnected` when the configured BLE peripheral device is found but not conncted\n- `connecting` when the configured BLE peripheral device is being connected\n- `connected` when the configured BLE peripheral device is connected\n- `disconnecting` when the configured BLE peripheral device is being disconnected\n- `error` when unexpected error occurs\n\nKnown issues for Linux BlueZ D-Bus API:\n\n- Unlike the older 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](#installation-note-linux).\n- 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.\n- `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.\n\n# How to use\n\n## How to configure a new BLE peripheral device\n\nAt 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.\n\n![ble out node](images/ble1.png)\n\nThen the new config node dialog appears as shown below.\n\nThe `BLE Scanning` shows whether or not BLE scanning is going on. In order to start BLE scanning, check it (`2`).\n\n![ble config node](images/ble2.png)\n\nAs 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.\n\n![ble config node](images/ble3.png)\n\nChosoe 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.\n\nThe 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.\n\n`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.\n\nClick `Add` (`3`) to save the information when everything is OK.\n\n![ble config node](images/ble4.png)\n\nNow back to `Generic BLE out` node.\nClick `Done` (`4`) to finish the `Generic BLE out` node settings.\n\n![ble config node](images/ble5.png)\n\nYou can also import an example flow from the menu icon(`三`) \u003e Import \u003e Examples \u003e node-red-contrib-generic-ble \u003e 01-read-write for learning more about this node.\n\n## How to translate gatttool command into flow\n\nIn this example, we show how to describe `gatttool` commands for characteristic value write and read with Generic BLE nodes.\n\n**NOTICE: As of BlueZ 5, gatttool is deprecated. gatttool will be removed in the future relesase.**\n\n### Characteristics Value Write\n\nThe 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`).\n\n```\n$ gatttool -b 88:99:00:00:FF:FF --char-write-req --handle=0x0027 --value=ca\nCharacteristic value was written successfully\n```\n\nIn this tutorial, we translate the above command into Node-RED flow.\n\nFirst of all, we use the following nodes.\n\n1. `inject` node to trigger a write request\n1. `Generic BLE out` node to perform the write request\n\n![gatttool](images/gatttool-001.jpg)\n\nSo the first step to create a flow is to place the above nodes on the workspace and connect them as shown above.\n\nNext, open the `inject` dialog so that you can provide the write request parameters, the characteristic uuid and the value.\n\n**Important!) Unlike `gatttool`, Generic BLE nodes NEVER use `handles`. Always use `uuid`s instead.**\n\n![gatttool](images/gatttool-002.jpg)\n\nIn this dialog, choose `JSON` at Payload input item since `Generic BLE out` node accepts a JSON object as its input value. See `Inputs` in the node description shown in the `info` tab for detail.\n\n![gatttool](images/gatttool-003.jpg)\n\nClick/tap `...` to launch JSON value editor and populate the following JSON text.\n\n```\n{\n    \"f000aa0204514000b000000000000000\": \"ca\"\n}\n```\n\nThe property `f000aa0204514000b000000000000000` is a characteristic `uuid`. However, unlike `gatttool`, you must strip hyphens from the original uuid value. `Generic BLE` nodes doesn't accept `gatttool` style uuid format.\n\nThe value `ca` is a hex string to be written, which is identical to the above command line.\n\nSo you'll see the following image.\n\n![gatttool](images/gatttool-004.jpg)\n\nClose the dialog by clicking `Done` button after entering the JSON text.\n\nConfigure `Generic BLE out` node for your BLE peripheral (This step is already introduced above so we don't describe here. See `How to configure a new BLE peripheral`).\n\nNow you're ready to issue a characteristic write request to your BLE peripheral. Click `Deploy` and click `inject` node to issue a characteristic write request.\n\n![gatttool](images/gatttool-005.jpg)\n\nNode-RED shows the notification message after your write request is performed successfully.\n\nHere in this tutorial, we use `inject` node to create characteristic write request parameters. However, this isn't the only way to do so. You can use other nodes than `inject` node. All you need is to prepare a valid JSON object for `Generic BLE out` node and provide it to the node.\n\nIn order to retrieve the written value from your BLE peripheral, go to the next step.\n\n### Characteristics Value Read\n\nThe both commands perform characteristic value read commands and return the same result, the characteristic value of the uuid `f000aa02-0451-4000-b000-000000000000`.\n\n```\n$ gatttool -b 88:99:00:00:FF:FF --char-read -u f000aa02-0451-4000-b000-000000000000\nhandle: 0x0027 \t value: ca\n\n$ gatttool -b 88:99:00:00:FF:FF --char-read --handle=0x0027\nCharacteristic value/descriptor: ca\n```\n\nIn this tutorial, we translate the above commands into Node-RED flow.\n\nWe use the following nodes this time.\n\n1. `inject` node to trigger a read command\n1. `Generic BLE in` node to perform the read command\n1. `debug` node to show the read value\n\n![gatttool](images/gatttool-006.jpg)\n\n\nPut the above nodes onto your workspace and add connectors like above.\n\nOpen `inject` node dialog and enter the characteristic `uuid` at Topic input box. Leave default values other than Topic since `Generic BLE in` sees only the topic value.\n\nYou can also leave Topic empty when you want to retrieve all characteristics values.\n\n![gatttool](images/gatttool-007.jpg)\n\nClick `Done` after entering the uuid to close the dialog. You need to configure `Generic BLE in` node to use your BLE peripheral but we skip to mention here as the instruction is described above (See `How to configure a new BLE peripheral` for detail).\n\nClick `Deploy` to function the flow.\n\n![gatttool](images/gatttool-008.jpg)\n\nLet's read the characteristic value by clicking `inject` node pedal. The read result will be displayed on the debug tab.\n\n## BLE in and out nodes\n\nSee `info` tab for detail on the editor UI.\n\n# Example Flow\n\nYou can import [the example flow](examples/01-read-write.json) on Node-RED UI.\n\n# Installation Note (Linux)\n\nThe 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.\nFor example, if you're going to run the process by `pi` user, run the following command.\n\n```\nsudo usermod -G bluetooth -a pi\n```\n\nThen reboot the OS so that the policy changes take effect.\n\n```\nsudo reboot\n```\n\n## Node-RED users\n\nRun the following commands:\n```\ncd ~/.node-red\nnpm install node-red-contrib-generic-ble\n```\n\nThen restart Node-RED process. Again, for Linux users, read the above chapter `Installation Note (Linux)` to get this node working.\n\n## CANDY RED users\n\nRun the following commands:\n```\ncd $(npm -g root)/candy-red\nsudo npm install --unsafe-perm node-red-contrib-generic-ble\n```\n\nThen restart `candy-red` service.\n\n```\nsudo systemctl restart candy-red\n```\n\n# Appendix\n\n## How to build\n\n```\n# build\n$ NODE_ENV=development npm run build\n# package\n$ NODE_ENV=development npm pack\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcandy-line%2Fnode-red-contrib-generic-ble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcandy-line%2Fnode-red-contrib-generic-ble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcandy-line%2Fnode-red-contrib-generic-ble/lists"}