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

BMW CarData API integration for Node-RED – OAuth2 Device Flow with PKCE, SoC and telemetry access for electric vehicles

npm install @eiguudewie/node-red-contrib-bmw-cardata

@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
2. Prerequisites
3. BMW CarData Portal – Setup
4. Installation
5. Configuration
6. Nodes
   • bmw-cardata-config
   • bmw-cardata-soc
   • bmw-cardata-query
7. Rate Limit
8. API Endpoints
9. 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

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:

cd ~/.node-red
npm install @eiguudewie/node-red-contrib-bmw-cardata

Then restart Node-RED:

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:

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
• Can be reset automatically on a daily schedule via the Reset counter at field (HH:MM, 24h format, e.g. 04:00)

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.

Nodes

bmw-cardata-config

Central configuration node. Manages authentication, token refresh, and container lifecycle.

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

Output

Settings

bmw-cardata-query

Generic query node. Returns the full raw telemetry response for a configurable set of datapoints.

Container modes

An existing container whose keys are a superset of the requested keys will be reused — no new container is created unnecessarily.

Input

Output

Settings

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.

License

MIT