{"_id":"@eiguudewie/node-red-contrib-bmw-cardata","_rev":"3-f9e260293c693549833c1b784ced9baa","name":"@eiguudewie/node-red-contrib-bmw-cardata","dist-tags":{"latest":"0.10.1"},"versions":{"0.9.0":{"name":"@eiguudewie/node-red-contrib-bmw-cardata","version":"0.9.0","keywords":["node-red","bmw","cardata","electric vehicle","soc","ev","connected drive","telematics"],"author":"","license":"MIT","_id":"@eiguudewie/node-red-contrib-bmw-cardata@0.9.0","maintainers":[{"name":"eiguudewie","email":"mum@gmx.de"}],"homepage":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata#readme","bugs":{"url":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata/issues"},"dist":{"shasum":"d16c5246be04724bd14051fb547865444348871d","tarball":"https://registry.npmjs.org/@eiguudewie/node-red-contrib-bmw-cardata/-/node-red-contrib-bmw-cardata-0.9.0.tgz","fileCount":9,"integrity":"sha512-dbMw5UgKUqBidbxVzihLdXKDZpftP9Clt5VeV8Z6AiLvUQD+AVA8mWO2GV0pVJ0KofTKDcpWAjG+dHBUwxRk3g==","signatures":[{"sig":"MEUCIQD5rbHyMdvkRqEFp3Rf2dqh/u2TB0suK73TtJKx2fTE1wIgc7DsBbGhRDnJE2mBUVoTulWyzWFZgeWSx74L3aPfgiA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":123198},"engines":{"node":">=16.0.0"},"gitHead":"77cd67824b04889925bce9e6f534752bec4b1efc","_npmUser":{"name":"eiguudewie","email":"mum@gmx.de"},"node-red":{"nodes":{"bmw-cardata-soc":"bmw-cardata-soc.js","bmw-cardata-query":"bmw-cardata-query.js","bmw-cardata-config":"bmw-cardata-config.js"},"minVersion":">=3.0.0"},"repository":{"url":"git+https://github.com/eiguudewie/node-red-contrib-bmw-cardata.git","type":"git"},"_npmVersion":"11.9.0","description":"BMW CarData API integration for Node-RED – OAuth2 Device Flow with PKCE, SoC and telemetry access for electric vehicles","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/node-red-contrib-bmw-cardata_0.9.0_1773917861450_0.3748462167341011","host":"s3://npm-registry-packages-npm-production"}},"0.10.0":{"name":"@eiguudewie/node-red-contrib-bmw-cardata","version":"0.10.0","keywords":["node-red","bmw","cardata","electric vehicle","soc","ev","connected drive","telematics"],"author":"","license":"MIT","_id":"@eiguudewie/node-red-contrib-bmw-cardata@0.10.0","maintainers":[{"name":"eiguudewie","email":"mum@gmx.de"}],"homepage":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata#readme","bugs":{"url":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata/issues"},"dist":{"shasum":"ea389b24601b4c4c8dec68b24d4e0c84966bcb05","tarball":"https://registry.npmjs.org/@eiguudewie/node-red-contrib-bmw-cardata/-/node-red-contrib-bmw-cardata-0.10.0.tgz","fileCount":9,"integrity":"sha512-rNseI7nwaQpAmdTA4eW4OCX9mLnk/3NwTaQ5pXmBvXbZp6KaJBhwQ/krp8VSpdsCddwH8ohJz0ZsryrOkyZrJA==","signatures":[{"sig":"MEUCIQDIrHWZR3Lo0OP3xXPhXYorqep7b7q+FlWIr9lJPwM7HQIgDT3AAGf+xDsi1eyIPLRrqhQhcsXqyz500EGrndE33U0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":126017},"engines":{"node":">=16.0.0"},"gitHead":"37855336be7d1b0f334cec3aadfc7d316b184bbd","_npmUser":{"name":"eiguudewie","email":"mum@gmx.de"},"node-red":{"nodes":{"bmw-cardata-soc":"bmw-cardata-soc.js","bmw-cardata-query":"bmw-cardata-query.js","bmw-cardata-config":"bmw-cardata-config.js"},"minVersion":">=3.0.0"},"repository":{"url":"git+https://github.com/eiguudewie/node-red-contrib-bmw-cardata.git","type":"git"},"_npmVersion":"11.9.0","description":"BMW CarData API integration for Node-RED – OAuth2 Device Flow with PKCE, SoC and telemetry access for electric vehicles","directories":{},"_nodeVersion":"24.14.0","dependencies":{"axios":"^1.7.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/node-red-contrib-bmw-cardata_0.10.0_1773924781871_0.64575481790958","host":"s3://npm-registry-packages-npm-production"}},"0.10.1":{"name":"@eiguudewie/node-red-contrib-bmw-cardata","version":"0.10.1","description":"BMW CarData API integration for Node-RED – OAuth2 Device Flow with PKCE, SoC and telemetry access for electric vehicles","keywords":["node-red","bmw","cardata","electric vehicle","soc","ev","connected drive","telematics"],"author":"","license":"MIT","homepage":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata#readme","bugs":{"url":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata/issues"},"repository":{"type":"git","url":"git+https://github.com/eiguudewie/node-red-contrib-bmw-cardata.git"},"engines":{"node":">=16.0.0"},"node-red":{"minVersion":">=3.0.0","version":">=3.0.0","nodes":{"bmw-cardata-config":"bmw-cardata-config.js","bmw-cardata-soc":"bmw-cardata-soc.js","bmw-cardata-query":"bmw-cardata-query.js"}},"dependencies":{"axios":"^1.7.0"},"_id":"@eiguudewie/node-red-contrib-bmw-cardata@0.10.1","_nodeVersion":"16.20.2","_npmVersion":"8.19.4","dist":{"integrity":"sha512-CwYOmsBLQqmDWznODI36Vn6sxrAZ9SMu4VQPI688pyRic9X/DnmB9+l2W6XbFuNRoiyc8S+i+IPWpH27q69QKw==","shasum":"2b1b3374ec2290ef7a45c5f8e489f978a2e22184","tarball":"https://registry.npmjs.org/@eiguudewie/node-red-contrib-bmw-cardata/-/node-red-contrib-bmw-cardata-0.10.1.tgz","fileCount":9,"unpackedSize":126043,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCwreTGeGAu/GKCod4cCvwyBbaYxXB3q08Ta4J/S+GCpQIgfStRa/oMVzymAOf5NGVAwn4vfC5Ur1dx+6gPzhXcHGI="}]},"_npmUser":{"name":"eiguudewie","email":"mum@gmx.de"},"directories":{},"maintainers":[{"name":"eiguudewie","email":"mum@gmx.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/node-red-contrib-bmw-cardata_0.10.1_1773963019652_0.8736662219540885"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T10:57:41.357Z","modified":"2026-03-19T23:30:19.913Z","0.9.0":"2026-03-19T10:57:41.597Z","0.10.0":"2026-03-19T12:53:02.038Z","0.10.1":"2026-03-19T23:30:19.800Z"},"bugs":{"url":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata/issues"},"license":"MIT","homepage":"https://github.com/eiguudewie/node-red-contrib-bmw-cardata#readme","keywords":["node-red","bmw","cardata","electric vehicle","soc","ev","connected drive","telematics"],"repository":{"type":"git","url":"git+https://github.com/eiguudewie/node-red-contrib-bmw-cardata.git"},"description":"BMW CarData API integration for Node-RED – OAuth2 Device Flow with PKCE, SoC and telemetry access for electric vehicles","maintainers":[{"name":"eiguudewie","email":"mum@gmx.de"}],"readme":"# @eiguudewie/node-red-contrib-bmw-cardata\n\nNode-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.\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Prerequisites](#prerequisites)\n3. [BMW CarData Portal – Setup](#bmw-cardata-portal--setup)\n4. [Installation](#installation)\n5. [Configuration](#configuration)\n6. [Nodes](#nodes)\n   - [bmw-cardata-config](#bmw-cardata-config)\n   - [bmw-cardata-soc](#bmw-cardata-soc)\n   - [bmw-cardata-query](#bmw-cardata-query)\n7. [Rate Limit](#rate-limit)\n8. [API Endpoints](#api-endpoints)\n9. [License](#license)\n\n---\n\n## Overview\n\nThis package provides three Node-RED nodes for the BMW CarData REST API:\n\n- **bmw-cardata-config** – Central config node. Manages OAuth2 authentication (Device Flow with PKCE), automatic token refresh, and container lifecycle. Shared by all other nodes.\n- **bmw-cardata-soc** – Reads the battery State of Charge (SoC). Simple, fixed datapoints, output as integer or full object.\n- **bmw-cardata-query** – Generic query node. Configurable datapoints and container name, returns the full raw telemetry response.\n\nAuthentication 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.\n\n---\n\n## Prerequisites\n\n- Node-RED >= 3.0\n- Node.js >= 16\n- BMW vehicle with an active ConnectedDrive account\n- Registered BMW CarData API client (see below)\n\n---\n\n## BMW CarData Portal – Setup\n\nBefore using the nodes you need to create an API client in the BMW CarData Portal. This is a one-time step.\n\n### 1. Open the BMW CarData Portal\n\n→ [https://bmw-cardata.bmwgroup.com/customer](https://bmw-cardata.bmwgroup.com/customer)\n\nSign in with your BMW ConnectedDrive account.\n\n### 2. Create a Client ID\n\n1. Navigate to **\"API Clients\"** → **\"Create CarData Client\"**\n2. Enter a name (e.g. `HomeAutomation`)\n3. Select the scope **`cardata:api:read`**\n4. Confirm the creation\n5. Copy the displayed **Client ID** (format: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`)\n\n> ⚠️ The Client ID is only shown in full once – save it immediately.\n\n### 3. Find your VIN\n\nThe **VIN (Vehicle Identification Number)** is 17 characters long. Where to find it:\n\n- Dashboard (base of the windshield, visible from outside) or driver's door jamb sticker\n- Vehicle registration or title document\n- BMW ConnectedDrive app or online portal\n- Vehicle registration certificate (Zulassungsbescheinigung Teil I, field E) — Germany\n\n---\n\n## Installation\n\nVia the Node-RED Palette Manager: search for **`@eiguudewie/node-red-contrib-bmw-cardata`** and click Install.\n\nVia npm:\n\n```bash\ncd ~/.node-red\nnpm install @eiguudewie/node-red-contrib-bmw-cardata\n```\n\nThen restart Node-RED:\n\n```bash\nsudo systemctl restart nodered\n# or\nnode-red\n```\n\n---\n\n## Configuration\n\nAll 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.\n\n### Authentication (OAuth2 Device Flow with PKCE)\n\n1. Open the config node, enter **Client ID** and **VIN**, then save\n2. Click **\"Authenticate now\"**\n3. Open the displayed link in your browser and enter the **user code**\n4. Sign in with your BMW account and confirm access\n5. Node-RED detects the confirmation automatically and stores the token\n\nThe access token is renewed automatically using the stored refresh token. The session is persisted in `~/.node-red/bmw-cardata-session-{nodeId}.json`.\n\n### Containers\n\nThe BMW CarData API requires a **container** that declares which datapoints to return. The plugin manages containers automatically:\n\n- On first use, a suitable ACTIVE container is located or a new one is created\n- Container keys and IDs are cached locally — subsequent requests need no extra API calls\n- The **Inspect containers** button in the config node shows all containers and their cached keys\n- Individual containers can be deleted from the UI\n- **Clear container cache** forces a fresh lookup on the next request\n\nDefault keys used when no custom keys are configured:\n\n| Key | Description |\n|-----|-------------|\n| `vehicle.drivetrain.batteryManagement.header` | State of Charge (%) |\n| `vehicle.drivetrain.electricEngine.charging.status` | Charging status |\n| `vehicle.powertrain.electric.battery.charging.power` | Charging power (kW) |\n\n### API Call Counter\n\nThe 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.\n\n- Resets automatically when a rate-limit response is received (HTTP 403, error code `CU-429`)\n- Can be reset manually via the **Reset counter** button or by sending `msg.resetCallCounter = true`\n- Can be reset automatically on a daily schedule via the **Reset counter at** field (`HH:MM`, 24h format, e.g. `04:00`)\n\n### Debug Mode\n\nWhen **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.\n\n| Level | When logged |\n|-------|-------------|\n| `trace` | Debug mode only — token TTL, raw API responses, container lookup steps |\n| `info`  | Debug mode only — session loaded, token refreshed, container found/created |\n| `warn`  | Always — recoverable errors, 404 retries, rate limit hit |\n| `error` | Always — failures that stop an operation |\n\n---\n\n## Nodes\n\n### bmw-cardata-config\n\nCentral configuration node. Manages authentication, token refresh, and container lifecycle.\n\n| Field | Description |\n|-------|-------------|\n| **Client ID** | API Client ID from the BMW CarData Portal |\n| **VIN** | 17-character Vehicle Identification Number |\n| **Debug Mode** | Enable verbose log output |\n\n---\n\n### bmw-cardata-soc\n\nReads the vehicle's **State of Charge (SoC)**. Always uses the three built-in default datapoints. For custom datapoints use `bmw-cardata-query` instead.\n\n#### Input\n\n| Property | Description |\n|----------|-------------|\n| any message | Triggers the request |\n| `msg.vin` | Override the configured VIN |\n| `msg.resetCallCounter = true` | Reset the API call counter before the request |\n\n#### Output\n\n| Property | Description |\n|----------|-------------|\n| `msg.payload` | SoC as integer, e.g. `75` *(SoC only mode)* |\n| `msg.payload` | `{ soc, vin, timestamp, raw, apiCalls }` *(Full object mode)* |\n| `msg.bmw` | Object with all fields above |\n| `msg.apiCalls` | `{ count, lastCallAt }` |\n| `msg.topic` | `bmw/{VIN}/soc` |\n\n#### Settings\n\n| Field | Description |\n|-------|-------------|\n| **Output mode** | `SoC only` (integer) or `Full object` |\n| **Show call count** | Append API call count to node status text |\n\n---\n\n### bmw-cardata-query\n\nGeneric query node. Returns the full raw telemetry response for a configurable set of datapoints.\n\n#### Container modes\n\n| Configuration | Behaviour |\n|--------------|-----------|\n| Keys + Name | Finds or creates a container with those keys, named as specified |\n| Keys only | Finds or creates a container with those keys, named `NR_Default` |\n| Name only | Looks up an existing ACTIVE container by name, returns all its data |\n| Neither | Uses the three built-in default keys |\n\nAn existing container whose keys are a **superset** of the requested keys will be reused — no new container is created unnecessarily.\n\n#### Input\n\n| Property | Description |\n|----------|-------------|\n| any message | Triggers the request |\n| `msg.vin` | Override the configured VIN |\n| `msg.resetCallCounter = true` | Reset the API call counter before the request |\n\n#### Output\n\n| Property | Description |\n|----------|-------------|\n| `msg.payload` | Full raw telematic data response object |\n| `msg.apiCalls` | `{ count, lastCallAt }` |\n| `msg.topic` | `bmw/{VIN}/query` |\n\n#### Settings\n\n| Field | Description |\n|-------|-------------|\n| **Container Name** | Name for new containers, or name to look up (name-only mode). Active container names are suggested as you type. |\n| **Container Keys** | Datapoints to request, one per line. Leave empty for defaults or name-only mode. |\n| **Show call count** | Append API call count to node status text |\n\n---\n\n## Rate Limit\n\n> ⚠️ The BMW CarData API allows a maximum of **50 calls per 24 hours**. The exact daily reset time is not documented by BMW.\n\nRecommendations:\n- Trigger SoC requests at an interval of **at least 30 minutes** (≤ 48 calls/day)\n- Container list and detail requests also count against the limit — use the local cache\n- Monitor the **API call counter** in the config node UI\n\n---\n\n## API Endpoints\n\nAll endpoints are based on the official [BMW CarData Swagger spec](https://bmw-cardata.bmwgroup.com/customer/public/assets/swagger/swagger-customer-api-v1.json).\n\n| Purpose | Endpoint |\n|---------|----------|\n| Device code | `POST https://customer.bmwgroup.com/gcdm/oauth/device/code` |\n| Token | `POST https://customer.bmwgroup.com/gcdm/oauth/token` |\n| Create container | `POST https://api-cardata.bmwgroup.com/customers/containers` |\n| List containers | `GET https://api-cardata.bmwgroup.com/customers/containers` |\n| Container details | `GET https://api-cardata.bmwgroup.com/customers/containers/{containerId}` |\n| Delete container | `DELETE https://api-cardata.bmwgroup.com/customers/containers/{containerId}` |\n| Telematic data | `GET https://api-cardata.bmwgroup.com/customers/vehicles/{vin}/telematicData?containerId=...` |\n| Vehicle mappings | `GET https://api-cardata.bmwgroup.com/customers/vehicles/mappings` |\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}