@eiguudewie/node-red-contrib-bmw-cardata 0.9.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 mm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the 
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# @eiguudewie/node-red-contrib-bmw-cardata
+
+Node-RED integration for the **BMW CarData REST API**. Reads vehicle telemetry such as State of Charge (SoC) via OAuth2 and forwards it to other systems.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Prerequisites](#prerequisites)
+3. [BMW CarData Portal – Setup](#bmw-cardata-portal--setup)
+4. [Installation](#installation)
+5. [Configuration](#configuration)
+6. [Nodes](#nodes)
+   - [bmw-cardata-config](#bmw-cardata-config)
+   - [bmw-cardata-soc](#bmw-cardata-soc)
+   - [bmw-cardata-query](#bmw-cardata-query)
+7. [Example Flow](#example-flow)
+8. [Rate Limit](#rate-limit)
+9. [API Endpoints](#api-endpoints)
+10. [License](#license)
+
+---
+
+## Overview
+
+This package provides three Node-RED nodes for the BMW CarData REST API:
+
+- **bmw-cardata-config** – Central config node. Manages OAuth2 authentication (Device Flow with PKCE), automatic token refresh, and container lifecycle. Shared by all other nodes.
+- **bmw-cardata-soc** – Reads the battery State of Charge (SoC). Simple, fixed datapoints, output as integer or full object.
+- **bmw-cardata-query** – Generic query node. Configurable datapoints and container name, returns the full raw telemetry response.
+
+Authentication is handled once via a browser-based BMW account confirmation. Tokens are stored and refreshed automatically. Container management (required by the BMW API) is fully automatic and cached locally.
+
+---
+
+## Prerequisites
+
+- Node-RED >= 3.0
+- Node.js >= 16
+- BMW vehicle with an active ConnectedDrive account
+- Registered BMW CarData API client (see below)
+
+---
+
+## BMW CarData Portal – Setup
+
+Before using the nodes you need to create an API client in the BMW CarData Portal. This is a one-time step.
+
+### 1. Open the BMW CarData Portal
+
+→ [https://bmw-cardata.bmwgroup.com/customer](https://bmw-cardata.bmwgroup.com/customer)
+
+Sign in with your BMW ConnectedDrive account.
+
+### 2. Create a Client ID
+
+1. Navigate to **"API Clients"** → **"Create CarData Client"**
+2. Enter a name (e.g. `HomeAutomation`)
+3. Select the scope **`cardata:api:read`**
+4. Confirm the creation
+5. Copy the displayed **Client ID** (format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`)
+
+> ⚠️ The Client ID is only shown in full once – save it immediately.
+
+### 3. Find your VIN
+
+The **VIN (Vehicle Identification Number)** is 17 characters long. Where to find it:
+
+- Dashboard (base of the windshield, visible from outside) or driver's door jamb sticker
+- Vehicle registration or title document
+- BMW ConnectedDrive app or online portal
+- Vehicle registration certificate (Zulassungsbescheinigung Teil I, field E) — Germany
+
+---
+
+## Installation
+
+Via the Node-RED Palette Manager: search for **`@eiguudewie/node-red-contrib-bmw-cardata`** and click Install.
+
+Via npm:
+
+```bash
+cd ~/.node-red
+npm install @eiguudewie/node-red-contrib-bmw-cardata
+```
+
+Then restart Node-RED:
+
+```bash
+sudo systemctl restart nodered
+# or
+node-red
+```
+
+---
+
+## Configuration
+
+All nodes share a single **bmw-cardata-config** node that holds credentials and manages the API session. Configure it once and reuse it across all BMW nodes in your flow.
+
+### Authentication (OAuth2 Device Flow with PKCE)
+
+1. Open the config node, enter **Client ID** and **VIN**, then save
+2. Click **"Authenticate now"**
+3. Open the displayed link in your browser and enter the **user code**
+4. Sign in with your BMW account and confirm access
+5. Node-RED detects the confirmation automatically and stores the token
+
+The access token is renewed automatically using the stored refresh token. The session is persisted in `~/.node-red/bmw-cardata-session-{nodeId}.json`.
+
+### Containers
+
+The BMW CarData API requires a **container** that declares which datapoints to return. The plugin manages containers automatically:
+
+- On first use, a suitable ACTIVE container is located or a new one is created
+- Container keys and IDs are cached locally — subsequent requests need no extra API calls
+- The **Inspect containers** button in the config node shows all containers and their cached keys
+- Individual containers can be deleted from the UI
+- **Clear container cache** forces a fresh lookup on the next request
+
+Default keys used when no custom keys are configured:
+
+| Key | Description |
+|-----|-------------|
+| `vehicle.drivetrain.batteryManagement.header` | State of Charge (%) |
+| `vehicle.drivetrain.electricEngine.charging.status` | Charging status |
+| `vehicle.powertrain.electric.battery.charging.power` | Charging power (kW) |
+
+### API Call Counter
+
+The config node tracks every API call and shows the running total in the UI. The counter and last-call timestamp are persisted across Node-RED restarts.
+
+- Resets automatically when a rate-limit response is received (HTTP 403, error code `CU-429`)
+- Can be reset manually via the **Reset counter** button or by sending `msg.resetCallCounter = true`
+
+### Debug Mode
+
+When **Debug Mode** is enabled, verbose `trace` and `info` messages appear in the Node-RED log, prefixed with `[bmw-cardata]`. Warnings and errors are always logged.
+
+| Level | When logged |
+|-------|-------------|
+| `trace` | Debug mode only — token TTL, raw API responses, container lookup steps |
+| `info`  | Debug mode only — session loaded, token refreshed, container found/created |
+| `warn`  | Always — recoverable errors, 404 retries, rate limit hit |
+| `error` | Always — failures that stop an operation |
+
+---
+
+## Nodes
+
+### bmw-cardata-config
+
+Central configuration node. Manages authentication, token refresh, and container lifecycle.
+
+| Field | Description |
+|-------|-------------|
+| **Client ID** | API Client ID from the BMW CarData Portal |
+| **VIN** | 17-character Vehicle Identification Number |
+| **Debug Mode** | Enable verbose log output |
+
+---
+
+### bmw-cardata-soc
+
+Reads the vehicle's **State of Charge (SoC)**. Always uses the three built-in default datapoints. For custom datapoints use `bmw-cardata-query` instead.
+
+#### Input
+
+| Property | Description |
+|----------|-------------|
+| any message | Triggers the request |
+| `msg.vin` | Override the configured VIN |
+| `msg.resetCallCounter = true` | Reset the API call counter before the request |
+
+#### Output
+
+| Property | Description |
+|----------|-------------|
+| `msg.payload` | SoC as integer, e.g. `75` *(SoC only mode)* |
+| `msg.payload` | `{ soc, vin, timestamp, raw, apiCalls }` *(Full object mode)* |
+| `msg.bmw` | Object with all fields above |
+| `msg.apiCalls` | `{ count, lastCallAt }` |
+| `msg.topic` | `bmw/{VIN}/soc` |
+
+#### Settings
+
+| Field | Description |
+|-------|-------------|
+| **Output mode** | `SoC only` (integer) or `Full object` |
+| **Show call count** | Append API call count to node status text |
+
+---
+
+### bmw-cardata-query
+
+Generic query node. Returns the full raw telemetry response for a configurable set of datapoints.
+
+#### Container modes
+
+| Configuration | Behaviour |
+|--------------|-----------|
+| Keys + Name | Finds or creates a container with those keys, named as specified |
+| Keys only | Finds or creates a container with those keys, named `NR_Default` |
+| Name only | Looks up an existing ACTIVE container by name, returns all its data |
+| Neither | Uses the three built-in default keys |
+
+An existing container whose keys are a **superset** of the requested keys will be reused — no new container is created unnecessarily.
+
+#### Input
+
+| Property | Description |
+|----------|-------------|
+| any message | Triggers the request |
+| `msg.vin` | Override the configured VIN |
+| `msg.resetCallCounter = true` | Reset the API call counter before the request |
+
+#### Output
+
+| Property | Description |
+|----------|-------------|
+| `msg.payload` | Full raw telematic data response object |
+| `msg.apiCalls` | `{ count, lastCallAt }` |
+| `msg.topic` | `bmw/{VIN}/query` |
+
+#### Settings
+
+| Field | Description |
+|-------|-------------|
+| **Container Name** | Name for new containers, or name to look up (name-only mode). Active container names are suggested as you type. |
+| **Container Keys** | Datapoints to request, one per line. Leave empty for defaults or name-only mode. |
+| **Show call count** | Append API call count to node status text |
+
+---
+
+## Example Flow
+
+A ready-to-import example flow is available at `examples/bmw-cardata-openwb-soc.json`.
+
+It demonstrates a minimal setup: an Inject node fires every 30 minutes, the BMW SoC node fetches the current charge level, and an HTTP Request node forwards the value to an EV charging controller.
+
+---
+
+## Rate Limit
+
+> ⚠️ The BMW CarData API allows a maximum of **50 calls per 24 hours**. The exact daily reset time is not documented by BMW.
+
+Recommendations:
+- Trigger SoC requests at an interval of **at least 30 minutes** (≤ 48 calls/day)
+- Container list and detail requests also count against the limit — use the local cache
+- Monitor the **API call counter** in the config node UI
+
+---
+
+## API Endpoints
+
+All endpoints are based on the official [BMW CarData Swagger spec](https://bmw-cardata.bmwgroup.com/customer/public/assets/swagger/swagger-customer-api-v1.json).
+
+| Purpose | Endpoint |
+|---------|----------|
+| Device code | `POST https://customer.bmwgroup.com/gcdm/oauth/device/code` |
+| Token | `POST https://customer.bmwgroup.com/gcdm/oauth/token` |
+| Create container | `POST https://api-cardata.bmwgroup.com/customers/containers` |
+| List containers | `GET https://api-cardata.bmwgroup.com/customers/containers` |
+| Container details | `GET https://api-cardata.bmwgroup.com/customers/containers/{containerId}` |
+| Delete container | `DELETE https://api-cardata.bmwgroup.com/customers/containers/{containerId}` |
+| Telematic data | `GET https://api-cardata.bmwgroup.com/customers/vehicles/{vin}/telematicData?containerId=...` |
+| Vehicle mappings | `GET https://api-cardata.bmwgroup.com/customers/vehicles/mappings` |
+
+---
+
+## License
+
+MIT