Profilformat¶

Ein Profil ist ein JSON-Dokument, das Modbus-Register auf Home-Assistant-Entities abbildet. Profile werden aus dem eingebauten profiles/-Verzeichnis und aus <HA-Konfiguration>/sg_energy_hub/profiles/ geladen.

Felder auf oberster Ebene¶

Feld	Pflicht	Bedeutung
`id`	ja	Stabile Kennung, `a-z0-9_`
`name`	ja	Modellname für die UI
`vendor`	ja	Hersteller
`device_type`	ja	`inverter`, `battery`, `heat_pump`, `energy_meter`, `system`
`model_pattern`	nein	Regex für Anzeige und spätere Discovery
`description`	nein	Freitext
`version`	nein	Profilversion, Standard `1.0.0`
`verified`	nein	`true` erst nach Test an echter Hardware
`demo`	nein	Markiert das simulierte Profil; genau eines ist erlaubt
`modbus_config`	nein	Verbindungsdefaults
`registers`	ja	Nicht-leere Liste von Registern

`modbus_config`¶

Feld	Standard	Bedeutung
`default_port`	502	TCP-Port
`unit_id`	1	Modbus-Unit-ID
`byte_order`	`big`	Byte-Reihenfolge im 16-Bit-Wort
`word_order`	`big`	Wort-Reihenfolge bei 32/64-Bit-Werten
`timeout`	5	Sekunden

Registerfelder¶

Feld	Pflicht	Bedeutung
`address`	ja	0–65535
`name`	ja	Stabile Kennung, `a-z0-9_`
`label`	nein	Anzeigename; Standard ist der Name in Titelform
`type`	nein	`uint16`, `int16`, `uint32`, `int32`, `uint64`, `int64`, `float32`, `float64`, `string`
`length`	bei `string`	Zeichenanzahl
`unit`	nein	Einheit, z. B. `W`, `kWh`, `%`, `°C`
`scale`	nein	Divisor, Standard 1
`offset`	nein	Wird nach der Skalierung addiert, Standard 0
`precision`	nein	Nachkommastellen
`access`	nein	`ro` (Standard) oder `rw`
`function`	nein	`holding` (Standard) oder `input`
`device_class`	nein	HA Device Class, z. B. `power`, `energy`, `battery`, `temperature`
`state_class`	nein	`measurement`, `total`, `total_increasing` oder `null`
`icon`	nein	Material-Icon
`entity_category`	nein	`diagnostic` oder `config`
`enabled_default`	nein	Standard `true`
`basic`	nein	Standard `true`; `false` erfordert Pro
`tier`	nein	`"pro"` ist die Kurzform für `basic: false`
`entity`	nein	Standard `true`; `false` liest das Register, erzeugt aber keine Entity
`enum`	nein	Zuordnung von Ganzzahlen zu Labels

Skalierung¶

scale ist ein Divisor:

{"address": 500, "name": "pv1_power", "type": "uint16", "unit": "W", "scale": 10}

Rohwert 5000 wird zu 500.0 W. Beim Schreiben wird die Rechnung umgekehrt.

Mehrregister-Werte¶

uint32, int32, float32 belegen zwei Register, uint64, int64, float64 vier. word_order bestimmt die Reihenfolge:

big: höherwertiges Wort zuerst,
little: niederwertiges Wort zuerst (bei vielen Wechselrichtern üblich).

byte_order bestimmt die Bytes innerhalb jedes Worts.

Enums¶

{
  "address": 540,
  "name": "heat_pump_status",
  "type": "uint16",
  "state_class": null,
  "enum": {"0": "off", "1": "heating", "2": "cooling", "5": "fault"}
}

Der Sensorzustand ist das zugeordnete Label. Unbekannte Werte erscheinen als Rohzahl.

Beispiel¶

{
  "id": "example_inverter",
  "name": "Example Inverter",
  "vendor": "Example",
  "device_type": "inverter",
  "model_pattern": "EX-.*",
  "version": "0.1.0",
  "verified": false,
  "modbus_config": {
    "default_port": 502,
    "byte_order": "big",
    "word_order": "little"
  },
  "registers": [
    {
      "address": 500,
      "name": "pv_power",
      "type": "uint16",
      "unit": "W",
      "scale": 10,
      "device_class": "power",
      "state_class": "measurement"
    },
    {
      "address": 514,
      "name": "battery_soc",
      "type": "uint16",
      "unit": "%",
      "device_class": "battery",
      "state_class": "measurement"
    }
  ]
}

Prüfregeln¶

Profil-IDs und Registernamen müssen eindeutig sein.
Registerbereiche dürfen sich innerhalb derselben Function nicht überlappen.
scale darf nicht null sein.
length ist nur bei string erlaubt.
enum ist nur bei Ganzzahltypen erlaubt.
Das Demo-Profil muss eindeutig sein.
scripts/check_repository.py prüft diese Regeln in der CI.