{"id":46846298,"url":"https://github.com/node-red-contrib/node-red-contrib-victron-ble","last_synced_at":"2026-03-10T14:37:07.514Z","repository":{"id":304404022,"uuid":"1018360969","full_name":"node-red-contrib/node-red-contrib-victron-ble","owner":"node-red-contrib","description":"A modern TypeScript/Node.js library to parse Victron Instant Readout BLE advertisements","archived":false,"fork":false,"pushed_at":"2026-02-09T08:36:16.000Z","size":329,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-09T13:52:51.308Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/node-red-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"konne"}},"created_at":"2025-07-12T05:20:31.000Z","updated_at":"2026-02-09T08:36:18.000Z","dependencies_parsed_at":"2025-07-12T22:37:55.349Z","dependency_job_id":null,"html_url":"https://github.com/node-red-contrib/node-red-contrib-victron-ble","commit_stats":null,"previous_names":["node-red-contrib/node-red-contrib-victron-ble"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/node-red-contrib/node-red-contrib-victron-ble","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-red-contrib%2Fnode-red-contrib-victron-ble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-red-contrib%2Fnode-red-contrib-victron-ble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-red-contrib%2Fnode-red-contrib-victron-ble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-red-contrib%2Fnode-red-contrib-victron-ble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/node-red-contrib","download_url":"https://codeload.github.com/node-red-contrib/node-red-contrib-victron-ble/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/node-red-contrib%2Fnode-red-contrib-victron-ble/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30337352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T12:41:07.687Z","status":"ssl_error","status_checked_at":"2026-03-10T12:41:06.728Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-03-10T14:37:06.830Z","updated_at":"2026-03-10T14:37:07.504Z","avatar_url":"https://github.com/node-red-contrib.png","language":"TypeScript","funding_links":["https://github.com/sponsors/konne"],"categories":[],"sub_categories":[],"readme":"# Victron BLE for Node.js \u0026 Node-RED\n\nA modern TypeScript/Node.js library to parse Victron Instant Readout BLE advertisements, inspired by the excellent [keshavdv/victron-ble](https://github.com/keshavdv/victron-ble) Python library.\n\n## What does this library do?\n\n- **Parses Victron Energy BLE advertisements** (Instant Readout) from Victron devices (SmartShunt, Smart Battery Sense, Solar Charger, etc.)\n- **Decrypts and decodes** the data using your device's unique encryption key\n- **Works out-of-the-box** as a Node.js library, a CLI tool, and a Node-RED node\n- **No Python or extra dependencies required**—runs natively on Node.js, including on Victron GX, Ekrano, and similar devices\n\n---\n\n## Usage\n\n### 1. CLI Tool\n\nAfter installing dependencies and building the project, you can use the CLI to scan and read Victron BLE devices:\n\n```sh\n# Discover Victron BLE devices\nnpx victron-ble discover\n\n# Read data from a device (replace ADDRESS and KEY)\nnpx victron-ble read \u003cDEVICE_ADDRESS\u003e \u003cENCRYPTION_KEY\u003e\n```\n\n### 2. Node-RED Node\n\n- **Install via the Node-RED Palette Manager** (search for `victron-ble`)\n- Drag the Victron BLE node into your flow\n- Enter your device's BLE address and encryption key (see below)\n- The node will emit parsed data as messages\n\n---\n\n## Getting Your Victron Device's Encryption Key\n\nTo decrypt BLE advertisements, you need the device's unique encryption key. You can find this in the official VictronConnect app:\n\n1. Pair with your device in the VictronConnect app\n2. Go to the device's **Product Info** section\n3. Find the **Instant Readout via Bluetooth** area\n4. Click **Show** next to Instant Readout Details to reveal the encryption key\n5. Copy the MAC address and the key\n\n\u003e **Note:** The key is required for both the CLI and Node-RED node to decode data.\n\n---\n\n## Why this library?\n\nThis project is inspired by [keshavdv/victron-ble](https://github.com/keshavdv/victron-ble), but is written in TypeScript/Node.js for:\n- **Native Node-RED integration** (no Python or extra installation)\n- **Easy deployment** on Victron GX, Ekrano, and similar embedded systems\n- **Modern, type-safe codebase**\n\n---\n\n## BLE Backend Selection\n\nThis library supports two different BLE backends:\n\n1. **bluetoothctl terminal output parsing** (default):\n   - The library will first attempt to use a custom adapter that parses the terminal output of the `bluetoothctl` command.\n   - This approach is necessary to support Victron GX, Ekrano, and similar devices, as well as most Linux systems where noble may not function, because it need to run as root.\n   - The adapter runs `bluetoothctl` as a subprocess, parses its output in real time, and emits BLE advertisement events.\n   - **Note:** This method does not work on macOS or Windows, as `bluetoothctl` is not available there.\n\n2. **noble** (fallback):\n   - If `bluetoothctl` is not available or fails to start, the library falls back to the [noble](https://github.com/noble/noble) BLE library.\n   - This is the standard for Node.js BLE access and works on macOS, Windows, and some Linux systems.\n   - **Important limitation:** noble requires root access to access BLE hardware. On Victron GX, Ekrano, and similar devices, Node-RED runs under a non-root user, so noble cannot be used in these environments. This is a key reason for using the bluetoothctl-based approach on these platforms.\n\n\u003e **Note:** We previously attempted to use the `node-ble` library, but found its performance and CPU usage unacceptable for production use, especially on embedded hardware.\n\nThe backend is selected automatically at runtime. If `bluetoothctl` is not available, the library will attempt to use noble instead.\n\n---\n\n## License\n\nMIT\n\n---\n\n## Credits\n\n- Inspired by [keshavdv/victron-ble](https://github.com/keshavdv/victron-ble)\n- Not affiliated with or supported by Victron Energy ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnode-red-contrib%2Fnode-red-contrib-victron-ble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnode-red-contrib%2Fnode-red-contrib-victron-ble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnode-red-contrib%2Fnode-red-contrib-victron-ble/lists"}