{"id":15386700,"url":"https://github.com/chrvadala/node-ble","last_synced_at":"2025-04-14T05:14:50.080Z","repository":{"id":39709206,"uuid":"237707128","full_name":"chrvadala/node-ble","owner":"chrvadala","description":"Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus","archived":false,"fork":false,"pushed_at":"2025-01-19T22:09:50.000Z","size":1145,"stargazers_count":333,"open_issues_count":22,"forks_count":50,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-14T05:14:33.101Z","etag":null,"topics":["ble","bluetooth","bluetooth-le","bluetooth-low-energy","bluetooth-peripherals","bluez","bluez-dbus","javascript","nodejs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/node-ble","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrvadala.png","metadata":{"files":{"readme":"README.md","changelog":null,"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},"funding":{"github":"chrvadala"}},"created_at":"2020-02-02T02:25:30.000Z","updated_at":"2025-03-29T04:08:48.000Z","dependencies_parsed_at":"2024-05-16T22:28:58.677Z","dependency_job_id":"8c4fd73f-1b3c-43fe-b046-3c67ee7541d8","html_url":"https://github.com/chrvadala/node-ble","commit_stats":{"total_commits":151,"total_committers":12,"mean_commits":"12.583333333333334","dds":"0.11920529801324509","last_synced_commit":"ece3d3e0f4bb1ce974b55492b5ccabeff38f1f86"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrvadala%2Fnode-ble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrvadala%2Fnode-ble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrvadala%2Fnode-ble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrvadala%2Fnode-ble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrvadala","download_url":"https://codeload.github.com/chrvadala/node-ble/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824693,"owners_count":21167345,"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","bluetooth","bluetooth-le","bluetooth-low-energy","bluetooth-peripherals","bluez","bluez-dbus","javascript","nodejs"],"created_at":"2024-10-01T14:50:13.244Z","updated_at":"2025-04-14T05:14:50.029Z","avatar_url":"https://github.com/chrvadala.png","language":"JavaScript","readme":"# node-ble\n\nBluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - baked by Bluez via DBus\n\n[![chrvadala](https://img.shields.io/badge/website-chrvadala-orange.svg)](https://chrvadala.github.io)\n[![Donate](https://img.shields.io/badge/donate-Paypal-lightgrey.svg)](https://www.paypal.com/paypalme/chrvadala/15)\n\n[![Test](https://github.com/chrvadala/node-ble/workflows/Test/badge.svg)](https://github.com/chrvadala/node-ble/actions)\n[![Coverage Status](https://coveralls.io/repos/github/chrvadala/node-ble/badge.svg?branch=master)](https://coveralls.io/github/chrvadala/node-ble?branch=master)\n[![npm](https://img.shields.io/npm/v/node-ble.svg?maxAge=2592000?style=plastic)](https://www.npmjs.com/package/node-ble)\n[![Downloads](https://img.shields.io/npm/dm/node-ble.svg)](https://www.npmjs.com/package/node-ble)\n\n\n\n\n# Documentation\n- [Documentation testing](https://github.com/chrvadala/node-ble/blob/main/docs/documentation-testing.md)\n- [Quick start guide](#quick-start-guide)\n- [APIs](https://github.com/chrvadala/node-ble/blob/main/docs/api.md)\n  - [createBluetooth](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#createBluetooth)\n  - [Bluetooth](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#Bluetooth)\n  - [Adapter](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#Adapter)\n  - [Device](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#Device)\n  - [GattServer](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#GattServer)\n  - [GattService](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#GattService)\n  - [GattCharacteristic](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#GattCharacteristic)\n\n# Pre-requisites\nThis library works on many architectures supported by Linux. However Windows and Mac OS are [*not* supported](https://github.com/chrvadala/node-ble/issues/31).\n\nIt leverages the `bluez` driver, a component supported by the following platforms and distributions \u003chttps://www.bluez.org/about\u003e.\n\n*node-ble* has been tested on the following operating systems:\n- Raspbian\n- Ubuntu\n- Debian\n\n# Install\n```sh\nnpm install node-ble\n```\n\n# Quick start guide\n\n## Provide permissions\nIn order to allow a connection with the DBus daemon, you have to set up right permissions.\n\nExecute the following command, in order to create the file `/etc/dbus-1/system.d/node-ble.conf`, configured with the current *user id* (Note: You may need to manually change the *user id*).\n\n```sh\necho '\u003c!DOCTYPE busconfig PUBLIC \"-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN\"\n  \"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd\"\u003e\n\u003cbusconfig\u003e\n  \u003cpolicy user=\"__USERID__\"\u003e\n   \u003callow own=\"org.bluez\"/\u003e\n    \u003callow send_destination=\"org.bluez\"/\u003e\n    \u003callow send_interface=\"org.bluez.GattCharacteristic1\"/\u003e\n    \u003callow send_interface=\"org.bluez.GattDescriptor1\"/\u003e\n    \u003callow send_interface=\"org.freedesktop.DBus.ObjectManager\"/\u003e\n    \u003callow send_interface=\"org.freedesktop.DBus.Properties\"/\u003e\n  \u003c/policy\u003e\n\u003c/busconfig\u003e' | sed \"s/__USERID__/$(id -un)/\" | sudo tee /etc/dbus-1/system.d/node-ble.conf \u003e /dev/null\n```\n\n## STEP 1: Get Adapter\nTo start a Bluetooth Low Energy (BLE) connection you need a Bluetooth adapter instance.\n\n```javascript\nconst {createBluetooth} = require('node-ble')\nconst {bluetooth, destroy} = createBluetooth()\nconst adapter = await bluetooth.defaultAdapter()\n```\n\n## STEP 2: Start discovering\nIn order to find a Bluetooth Low Energy device out, you have to start a discovery operation.\n```javascript\nif (! await adapter.isDiscovering())\n  await adapter.startDiscovery()\n```\n\n## STEP 3: Get a device, Connect and Get GATT Server\nUse the adapter instance in order to get a remote Bluetooth device, then connect and interact with the GATT (Generic Attribute Profile) server.\n\n```javascript\nconst device = await adapter.waitDevice('00:00:00:00:00:00')\nawait device.connect()\nconst gattServer = await device.gatt()\n```\n\n## STEP 4a: Read and write a characteristic.\n```javascript\nconst service1 = await gattServer.getPrimaryService('uuid')\nconst characteristic1 = await service1.getCharacteristic('uuid')\nawait characteristic1.writeValue(Buffer.from(\"Hello world\"))\nconst buffer = await characteristic1.readValue()\nconsole.log(buffer)\n```\n\n## STEP 4b: Subscribe to a characteristic.\n```javascript\nconst service2 = await gattServer.getPrimaryService('uuid')\nconst characteristic2 = await service2.getCharacteristic('uuid')\ncharacteristic2.on('valuechanged', buffer =\u003e {\n  console.log(buffer)\n})\nawait characteristic2.startNotifications()\n```\n\n## STEP 5: Disconnect\nWhen you have done you can stop notifications, disconnect and destroy the session.\n```javascript\nawait characteristic2.stopNotifications()\nawait device.disconnect()\ndestroy()\n```\n\n# Changelog\n- **0.x** - Beta version\n- **1.0** - First official version\n- **1.1** - Migrates to gh-workflows\n- **1.2** - Upgrades deps\n- **1.3** - Adds typescript definitions [#10](https://github.com/chrvadala/node-ble/pull/10)\n- **1.4** - Upgrades deps\n- **1.5** - Adds write options configuration  `async writeValue (value, optionsOrOffset = {})` [#20](https://github.com/chrvadala/node-ble/pull/20); Upgrades deps\n- **1.6** - Upgrades deps and removes some dependencies; migrates to npm; improves gh-actions\n- **1.7** - Fixes compatibility issue [#30](https://github.com/chrvadala/node-ble/issues/30); Adds JSdoc; Deprecates NodeJS 10 and 12; Upgrades deps;\n- **1.8** - Upgrades deps and gh-actions os; Adds `Bluetooth.activeAdapters()` func [#45](https://github.com/chrvadala/node-ble/pull/45); \n- **1.9** - Upgrades deps; Adds `writeValueWithoutResponse()` and `writeValueWithResponse` methods [#47](https://github.com/chrvadala/node-ble/pull/47); Improves typescript definition [#48](https://github.com/chrvadala/node-ble/pull/48) \n- **1.10** - Upgrades deps and gh-actions; Fixes memory leak [#37](https://github.com/chrvadala/node-ble/pull/37); Makes MAC Address case insensitive\n- **1.11** - Upgrades deps; Fixes doc [#69](https://github.com/chrvadala/node-ble/pull/69); Adds `getManufacturerData` and `getAdvertisingData`  functions on `Device` [#67](https://github.com/chrvadala/node-ble/pull/67); Adds `getServiceData` functions on `Device`; Improves pre-requisite doc section [#68](https://github.com/chrvadala/node-ble/pull/68)\n- **1.12** - Upgrades deps and actions; Fixes memory leak [#75](https://github.com/chrvadala/node-ble/pull/75); Improved docs with copy-and-paste configuration scripts.\n- **1.13** - Upgrades deps; Fixes race condition [#77](https://github.com/chrvadala/node-ble/pull/77)\n\n# Contributors\n- [chrvadala](https://github.com/chrvadala) (author)\n- [pascalopitz](https://github.com/pascalopitz)\n- [lupol](https://github.com/lupol)\n- [altaircunhajr](https://github.com/altaircunhajr)\n- [derwehr](https://github.com/derwehr)\n- [mxc42](https://github.com/mxc42)\n- [tuxedoxt](https://github.com/tuxedoxt)\n- [raffone17](https://github.com/Raffone17)\n- [gmacario](https://github.com/gmacario)\n- [ianchanning](https://github.com/ianchanning)\n- [nmasse-itix](https://github.com/nmasse-itix)\n\n# References\n- https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/adapter-api.txt?h=5.64\n- https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/device-api.txt?h=5.64\n- https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/gatt-api.txt?h=5.64\n- https://webbluetoothcg.github.io/web-bluetooth - method signatures follow, when possible, WebBluetooth standards\n- https://developers.google.com/web/updates/2015/07/interact-with-ble-devices-on-the-web - method signatures follow, when possible, WebBluetooth standards\n\n# Similar libraries\n- https://github.com/noble/noble\n- https://github.com/abandonware/noble (noble fork)\n- https://www.npmjs.com/package/node-web-bluetooth\n\n# Useful commands\n| Command | Description |\n| --- | --- |\n| rm -r /var/lib/bluetooth/* | Clean Bluetooth cache |\n| hciconfig -a | Adapter info |\n| hcitool dev | Adapter info (through Bluez) |\n| d-feet | DBus debugging tool |\n| nvram bluetoothHostControllerSwitchBehavior=never | Only on Parallels |\n| inxi --bluetooth -z | Bluetooth device info |\n","funding_links":["https://github.com/sponsors/chrvadala","https://www.paypal.com/paypalme/chrvadala/15"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrvadala%2Fnode-ble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrvadala%2Fnode-ble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrvadala%2Fnode-ble/lists"}