node-red-contrib-victron-ble/README.md

node-red node to parse Instant Readout advertisement data from Victron BLE devices

# Victron BLE for Node.js & Node-RED

A 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.

## What does this library do?

- **Parses Victron Energy BLE advertisements** (Instant Readout) from Victron devices (SmartShunt, Smart Battery Sense, Solar Charger, etc.)
- **Decrypts and decodes** the data using your device's unique encryption key
- **Works out-of-the-box** as a Node.js library, a CLI tool, and a Node-RED node
- **No Python or extra dependencies required**—runs natively on Node.js, including on Victron GX, Ekrano, and similar devices

---

## Usage

### 1. CLI Tool

After installing dependencies and building the project, you can use the CLI to scan and read Victron BLE devices:

```sh
# Discover Victron BLE devices
npx victron-ble discover

# Discover with a specific BLE backend
npx victron-ble discover --bluetooth noble

# Read data from a device (replace ADDRESS and KEY)
npx victron-ble read <DEVICE_ADDRESS> <ENCRYPTION_KEY>
```

### 2. Node-RED Node

- **Install via the Node-RED Palette Manager** (search for `victron-ble`)
- Drag the Victron BLE node into your flow
- Enter your device's BLE address and encryption key (see below)
- The node will emit parsed data as messages

---

## Getting Your Victron Device's Encryption Key

To decrypt BLE advertisements, you need the device's unique encryption key. You can find this in the official VictronConnect app:

1. Pair with your device in the VictronConnect app
2. Go to the device's **Product Info** section
3. Find the **Instant Readout via Bluetooth** area
4. Click **Show** next to Instant Readout Details to reveal the encryption key
5. Copy the MAC address and the key

> **Note:** The key is required for both the CLI and Node-RED node to decode data.

---

## Why this library?

This project is inspired by [keshavdv/victron-ble](https://github.com/keshavdv/victron-ble), but is written in TypeScript/Node.js for:
- **Native Node-RED integration** (no Python or extra installation)
- **Easy deployment** on Victron GX, Ekrano, and similar embedded systems
- **Modern, type-safe codebase**

---

## BLE Backend Selection

This library supports three different BLE backends:

1. **BlueZ via DBus** (default on Linux when available):
   - The library first attempts to use BlueZ directly through the system DBus API.
   - This avoids the root access requirement of noble and avoids parsing terminal output from `bluetoothctl`.
   - It reads Victron Instant Readout advertisement data from BlueZ `Device1.ManufacturerData` updates.
   - **Note:** This backend is only available on Linux systems with BlueZ and DBus access.

2. **bluetoothctl terminal output parsing** (fallback):
   - If the DBus backend is unavailable or fails to start, the library attempts to use a custom adapter that parses the terminal output of the `bluetoothctl` command.
   - This approach is necessary to support Victron GX, Ekrano, and similar devices, as well as most Linux systems where noble may not function, because noble needs to run as root.
   - The adapter runs `bluetoothctl` as a subprocess, parses its output in real time, and emits BLE advertisement events.
   - **Note:** This method does not work on macOS or Windows, as `bluetoothctl` is not available there.

3. **noble** (final fallback):
   - If BlueZ DBus and `bluetoothctl` are not available or fail to start, the library falls back to the [noble](https://github.com/noble/noble) BLE library.
   - This is the standard for Node.js BLE access and works on macOS, Windows, and some Linux systems.
   - **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 BlueZ DBus or `bluetoothctl` approaches on these platforms.

> **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.

The CLI selects the backend automatically by default in this order: BlueZ DBus, `bluetoothctl`, then noble.
Use `--bluetooth auto`, `--bluetooth bluez`, `--bluetooth bluetoothctl`, or `--bluetooth noble` with `discover` or `read` to choose a backend explicitly.

---

## License

MIT

---

## Credits

- Inspired by [keshavdv/victron-ble](https://github.com/keshavdv/victron-ble)
- Not affiliated with or supported by Victron Energy