From 2d28ae6d692db263c9bec8c8589aa632d97c85b5 Mon Sep 17 00:00:00 2001
From: Michael Geers <michael@geers.tv>
Date: Tue, 19 May 2026 18:30:09 +0200
Subject: [PATCH] docs: vehicle brand consistency (#30018)

---
 templates/README.md                           | 23 ++++++++++++++++---
 templates/definition/vehicle/cardata.yaml     |  4 ++--
 .../vehicle/ford-connect-query.yaml           |  4 +++-
 .../definition/vehicle/ford-connect.yaml      |  4 +++-
 templates/definition/vehicle/hyundai-us.yaml  |  4 ++--
 5 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/templates/README.md b/templates/README.md
index 4425f6d31..6a27b14bf 100644
--- a/templates/README.md
+++ b/templates/README.md
@@ -22,10 +22,27 @@ The following describes each possible element in a yaml file
 
 Each product contains:
 
-- `brand`: an optional brand description of the product
-- `description`: an optional description e.g. of the product model. Expects `generic`, `de`, `en`: an optional description of the product
+- `brand`: company that makes the product or offers the service. No regions, variants, or API names — those, if required for clarity, belong in `description`.
+- `description`: product, service, model, or API name. Expects `generic`, `de`, `en`.
 
-Either `brand`, or `description` need to be set.
+Either `brand` or `description` needs to be set. Examples by device class:
+
+- Vehicles — `brand` is the make, `description` the connected service:
+  - `brand: Hyundai`, `description.generic: Bluelink`
+  - `brand: Hyundai`, `description.generic: Bluelink (US)`
+- Chargers — `brand` is the manufacturer, `description` the product model:
+  - `brand: ABL`, `description.generic: eMH1`
+  - `brand: ABL`, `description.generic: eMH2`
+  - `brand: Alfen`, `description.generic: Eve`
+- Meters — `brand` is the manufacturer, `description` the product model:
+  - `brand: ABB`, `description.generic: A43`
+  - `brand: my-PV`, `description.generic: AC ELWA 2`
+- Tariffs — `brand` is the service provider, `description` the API variant:
+  - `brand: Electricity Maps`, `description.generic: Commercial API`
+  - `brand: Electricity Maps`, `description.generic: Free API`
+- Generic integrations (OSS tools, community projects): omit `brand`, put the project name in `description.generic`, set `group: generic`. Keep upstream casing (e.g. `TeslaFi`, `ioBroker.bmw`, `mg2mqtt`).
+
+Note: The official website of the manufacturer or service provider is the reference for the exact spelling.
 
 ## `group`
 
diff --git a/templates/definition/vehicle/cardata.yaml b/templates/definition/vehicle/cardata.yaml
index e5ab356d8..3f1db2255 100644
--- a/templates/definition/vehicle/cardata.yaml
+++ b/templates/definition/vehicle/cardata.yaml
@@ -2,10 +2,10 @@ template: cardata
 products:
   - brand: BMW
     description:
-      generic: CarData (EU Data Act)
+      generic: CarData
   - brand: Mini
     description:
-      generic: CarData (EU Data Act)
+      generic: CarData
 requirements:
   description:
     de: |
diff --git a/templates/definition/vehicle/ford-connect-query.yaml b/templates/definition/vehicle/ford-connect-query.yaml
index d3d2fa22c..e753f013b 100644
--- a/templates/definition/vehicle/ford-connect-query.yaml
+++ b/templates/definition/vehicle/ford-connect-query.yaml
@@ -1,6 +1,8 @@
 template: ford-connect-query
 products:
-  - brand: Ford (FordConnect Query)
+  - brand: Ford
+    description:
+      generic: FordConnect Query
 params:
   - preset: vehicle-common
   - name: clientid
diff --git a/templates/definition/vehicle/ford-connect.yaml b/templates/definition/vehicle/ford-connect.yaml
index cbd9836ef..b42c77b35 100644
--- a/templates/definition/vehicle/ford-connect.yaml
+++ b/templates/definition/vehicle/ford-connect.yaml
@@ -1,7 +1,9 @@
 template: ford-connect
 deprecated: true
 products:
-  - brand: Ford (Legacy FordConnect)
+  - brand: Ford
+    description:
+      generic: FordConnect (Legacy)
 params:
   - preset: vehicle-common
   - name: clientid
diff --git a/templates/definition/vehicle/hyundai-us.yaml b/templates/definition/vehicle/hyundai-us.yaml
index f1e20d4e5..8617ff685 100644
--- a/templates/definition/vehicle/hyundai-us.yaml
+++ b/templates/definition/vehicle/hyundai-us.yaml
@@ -1,8 +1,8 @@
 template: hyundai-us
 products:
-  - brand: Hyundai (US)
+  - brand: Hyundai
     description:
-      generic: Bluelink
+      generic: Bluelink (US)
 params:
   - preset: vehicle-base
 render: |