Profilformat

Ein Add-on-Profil ist eine JSON-Datei. Sie beschreibt ein Gerät vollständig: wie der nomos system Controller es erreicht, was er senden kann, welche Werte zurückkommen und was davon in App, Automationen und Quick Konfig erscheint. Diese Seite beschreibt das Format; wie Sie es im Profil Editor bearbeiten, steht dort. Profile mit eigener Verbindung über TCP, UDP, HTTP oder seriell beschreibt CommandServer im Einzelnen, vollständige Beispiele für HTTP, TCP (Modbus), UDP, MQTT und KNX stehen unter Beispielprofile.

INFO

Jedes Profil der Profilliste lässt sich mit dem Download-Symbol als .json speichern. Ein vorhandenes Profil, das Ihrem Gerät ähnelt, ist der beste Ausgangspunkt.

Aufbau im Überblick

{
	"version": "1.0",
	"author": "Muster Integration GmbH",
	"description": "Wallbox XY",
	"manufacturer": "XY",
	"model": "Wallbox",
	"platform": "XY",
	"category": "Energy",
	"type": "EV Charger",
	"className": "XY_WALLBOX",
	"engineType": "",
	"structure": { "config": {}, "commands": {}, "mappings": {} },
	"polling": {},
	"properties": {},
	"propertiesMeta": {},
	"mappings": {},
	"mappingsMeta": {},
	"actionTemplates": [],
	"triggerTemplates": [],
	"hooks": {},
	"cameras": [],
	"components": {}
}

Block	Inhalt
Grunddaten	Name, Hersteller, Kategorie, Typ, Engine-Typ
structure	Nur CommandServer: Verbindung, Befehle und Antwortmuster, siehe CommandServer
polling	Nur CommandServer: Befehle, die regelmäßig gesendet werden
properties, propertiesMeta	Aktionen: was an das Gerät gesendet werden kann, und ihre Beschriftung
mappings, mappingsMeta	Rückmeldungen: welche Werte das Gerät meldet, und ihre Beschriftung
actionTemplates, triggerTemplates	Vorlagen für Automationen und Quick Konfig
hooks	Werte, die das Gerät per HTTP selbst senden darf
cameras	Kamerabilder des Geräts
components	Unterprofile: mehrere Geräte über eine Verbindung

Wichtig für das Verständnis: structure beschreibt nur, was über die Leitung geht. App, Automationen und gespeicherte Werte arbeiten ausschließlich mit properties und mappings. Ein CommandServer-Profil braucht deshalb beides: den Befehl in structure.commands und die Aktion in properties, das Antwortmuster in structure.mappings und die Rückmeldung in mappings.

Grunddaten

Feld	Pflicht	Bedeutung
version	ja	Versionsnummer, z. B. 1.0. Bestehende Geräte übernehmen Änderungen nur bei höherer Version, siehe Profil ändern
description	ja	Name in der Profilliste und Vorschlag für den Gerätenamen
author, manufacturer, model	ja	Angaben zu Autor und Gerät
platform	ja	Herkunft, meist der Hersteller. Bei KNX KNX, bei MQTT MQTT
category, type	ja	Siehe Kategorie und Typ
engineType	ja	Siehe Engine-Typ
className	CommandServer, KNX	Bei CommandServer der Name der Verbindung (nur A–Z, 0–9, _, -, höchstens 28 Zeichen), bei KNX immer KNX, bei MQTT und BUS leer
supportUrl	nein	Hilfeseite zum Gerät, erscheint als Info-Schaltfläche
compatibility	nein	Abdeckung des Geräts in Prozent
nomosCertified	nein	true nur bei Profilen, die nomos system geprüft hat
minVersion	nein	Mindestversion des Controllers; ältere Controller lehnen das Anlegen eines Geräts ab
tags	nein	Kennzeichen, siehe unten
hideProperties, hideMappings	nein	Setzt der Profil Editor selbst, siehe Vorlagen

Tags mit Wirkung: uihidden (Gerät nicht in der App), voicehidden (nicht an Sprachassistenten und die Matter-Brücke). Ein Feld name gehört nicht in das Hauptprofil: Es würde den Namen ersetzen, den der Benutzer beim Anlegen vergibt.

Ein Punkt im Namen des Profils wird beim Import zu _, denn ein Punkt trennt beim Laden Profil und Unterprofil.

Kategorie und Typ

Kategorie und Typ entscheiden über Symbol und Bedienelement in der App und darüber, ob und als was das Gerät über die Matter-Brücke erscheint. Verwenden Sie die Werte, die der Profil Editor anbietet, z. B.:

Kategorie	Typen
Lighting	Lightbulb
Switches	Switch, Trigger
Thermostats	Thermostat, Thermostat Variation TA
Window Coverings	Window Covering, Window Covering Up/Down
Sunblinds	Sunblind
Sensors	Temperature Sensor, Humidity Sensor, Contact Sensor, Motion Sensor, CO2 Sensor, Smoke Sensor, Light Sensor, Rain Sensor, Wind Sensor, Weather Station, Binary Sensor, …
Energy	Inverter, Smart Meter, EV Charger, Heat Pump, Heating Controller, Pellet Boiler, Power Sensor
Fans, Doors, Garage Door, Valves	Fan, Door, Garage Door Opener, Valve
Security Systems	Lock, Alarm, Camera, Security System

Wählen Sie den Typ nach dem wichtigsten Wert des Geräts.

Engine-Typ

engineType	Verbindung	Besonderheiten
"" (CommandServer)	Eigene Verbindung über TCP, UDP, HTTP, HTTPS oder seriell	structure und polling, siehe CommandServer
MQTT	Über den Broker des MQTT-Skills	Topics je Aktion und Rückmeldung, siehe MQTT
KNX	Über die KNX-Schnittstelle	Profil ohne Adressen, Gruppenadressen beim Anlegen, siehe KNX
BUS	Werte kommen nur über Webhooks	Für Geräte, die von sich aus per HTTP melden
ZWAVE	Über den Z-Wave-Skill	Wird über die Z-Wave-Seite angelegt

Jedes Gerät aus einem CommandServer-, MQTT- oder BUS-Profil zählt gegen die Zahl der Add-ons, die Ihre Lizenz erlaubt.

Aktionen und Rückmeldungen

properties (Aktionen) sind alles, was an das Gerät gesendet werden kann. mappings (Rückmeldungen) sind die Werte, die das Gerät meldet. Ein Name darf in beiden vorkommen, etwa state zum Schalten und als gemeldeter Zustand; nur dann zeigt die App einen Schalter, der den tatsächlichen Zustand wiedergibt.

"properties": {
	"state":     {"method": "set", "property": "ENA", "datatype": "bool"},
	"switchon":  {"method": "set", "property": "ENA", "value": 1, "datatype": "bool", "uihidden": true},
	"switchoff": {"method": "set", "property": "ENA", "value": 0, "datatype": "bool", "uihidden": true}
},
"mappings": {
	"state":     {"method": "get", "property": "ENABLE_USER", "datatype": "bool", "defaultValue": false},
	"reachable": {"method": "get", "property": "REACHABLE", "datatype": "bool", "defaultValue": false}
}

Felder

Feld	In	Bedeutung
method	beide	Aktionen: command (Befehl senden), set (Eigenschaft setzen), alias (auf eine andere Aktion umleiten). Rückmeldungen: get
command	Aktionen	Name des Befehls bei method: "command"
property	beide	Bei set: Name der Eigenschaft. Bei Rückmeldungen: Name des gemeldeten Werts, bei CommandServer der Name eines Antwortmusters, bei KNX immer value
datatype	beide	Siehe Datentypen
value	Aktionen	Fester Wert, siehe Fester Wert
defaultValue	beide	Aktionen: Wert, wenn keiner mitkommt. Rückmeldungen: Anfangswert bis zur ersten Meldung
valueList	beide	Auswahlwerte, siehe Wertelisten
min, max, internalMin, internalMax	beide	Siehe Skalierung
unit	beide	Siehe Einheiten
stepValue	beide	Schrittweite von Schiebereglern (nicht step)
uihidden	beide	Nicht als eigene Zeile in der App
process	Rückmeldungen	Siehe Verarbeitung
customFormat	Rückmeldungen	Siehe Darstellung
simulateFeedback	Aktionen	true: Der gesendete Wert gilt sofort als gemeldet. Für Geräte ohne Rückmeldung
prefix, suffix	Aktionen	Werden mit Komma vor bzw. hinter den Wert gesetzt (prefix,wert)
sizeInBit	beide	KNX: Größe des Datenpunkts. Bei 1 werden true/false als 1/0 gesendet
filterDPT	beide	KNX: angebotene Datenpunkttypen beim Zuordnen der Gruppenadresse
mqtt, mqttValue, mqttPayload, mqttScale	beide	MQTT, siehe MQTT

Bei CommandServer wird aus {"method": "set", "property": "ENA"} der Befehl SETENA, aus {"method": "command", "command": "ON"} der Befehl ON. Beide müssen in structure.commands stehen.

Datentypen

datatype	Bedeutung
bool	Ja/Nein. Als „aus“ gelten 0, false, off, aus, offline, close, closed, error, warning (Groß-/Kleinschreibung egal), alles andere als „ein“. Ein Gerät, das open meldet, ist also „ein“
int, float	Ganze Zahl bzw. Kommazahl (Punkt als Dezimaltrennzeichen)
string	Text
null	Aktion ohne Wert, z. B. eine Schaltfläche. Ein mitgeschickter Wert wird verworfen
trigger	Aktion, die nur ausgelöst wird, etwa Stopp einer Beschattung

Standardnamen

Die App erkennt Werte an ihrem Namen und zeigt dafür das passende Bedienelement. Verwenden Sie für diese Werte genau diese Namen:

Name	Wert	Datentyp
state	Ein/Aus	bool
level	Helligkeit 0–100	int
color-temperature	Farbtemperatur in Mired	int
position	Position einer Beschattung 0–100	int
stop	Beschattung anhalten	trigger
openclose	Öffnen/Schließen, Pflicht bei Garagentoren	bool
opened	Tür oder Tor offen	bool
temperature, setpoint	Ist- und Solltemperatur	float
hvacmode	Betriebsart	int oder string
isheating, heatingpower	Heizt gerade, Heizleistung in %	bool, int
humidity, co2, pressure, noise	Messwerte	Zahl
battery	Batteriestand in %	int
reachable	Erreichbarkeit	bool
power	Leistung	float
pv_power, grid, battery_power, battery_state, e_day, e_total	Energie: PV-Leistung, Netz, Speicher, Ertrag heute und gesamt. grid aus Sicht des Hauses: Einspeisung positiv, Bezug negativ	Zahl

Weitere Werte dürfen eigene Namen tragen (Kleinbuchstaben, Ziffern, _, -); die App zeigt sie als Textzeile. Der Profil Editor schlägt beim Namen alle bekannten Namen vor.

state, switchon und switchoff

Schaltet die App ein Gerät, sendet der Controller nicht state, sondern switchon bzw. switchoff. Automationen verwenden dagegen state selbst. Ein schaltbares Gerät braucht deshalb alle drei Aktionen: state mit dem Datentyp bool und switchon/switchoff mit demselben Befehl und dem festen Wert 1 bzw. 0, beide mit uihidden. In propertiesMeta fasst ein Eintrag die drei zusammen:

"propertiesMeta": {
	"state": {"text": "State", "properties": ["state", "switchon", "switchoff"]}
}

Fester Wert

value an einer Aktion ist der Wert, den sie sendet, wenn keiner mitkommt. Kommt ein Wert mit, etwa aus der App, gewinnt dieser, außer bei "datatype": "null": Dann wird immer value gesendet. In Automationen gewinnt dagegen immer der feste Wert des Profils. Für Schaltflächen mit festem Inhalt (Szene aufrufen, Taste drücken) deshalb "datatype": "null" und value verwenden.

Wertelisten

"valueList": [
	{"text": "Off", "value": "0"},
	{"text": "Low", "value": "1"},
	{"text": "High", "value": "2"}
]

Bei einer Aktion ist die Liste zugleich eine Erlaubnisliste: Ein Wert, der nicht darin steht, wird abgewiesen. Automationen zeigen die Auswahl nur, wenn dieselbe Liste auch in der Vorlage steht; wiederholen Sie sie dort.

Skalierung

internalMin/internalMax sind der Wertebereich des Geräts, min/max der Bereich in nomos (App, Automationen). Der Controller rechnet linear um, in beide Richtungen. Beispiel: Die Wallbox erwartet den Ladestrom in mA (6000–32000), die App zeigt A (6–32):

"amperelimit": {"method": "set", "property": "CURR", "datatype": "int", "unit": "A",
	"min": 6, "max": 32, "internalMin": 6000, "internalMax": 32000}

WARNING

Skaliert wird, sobald max gesetzt ist. Fehlende Grenzen gelten als min 0, max 100, internalMin 0, internalMax 100. Ein "max": 3000 ohne internalMin/internalMax rechnet einen Gerätewert 0–100 also auf 0–3000 hoch. Setzen Sie entweder alle vier Grenzen oder keine.

• Das Ergebnis wird auf ganze Zahlen gerundet. Eine Umrechnung von W in kW mit Nachkommastellen geht deshalb nicht über die Skalierung; nehmen Sie bei CommandServer ein Format ({%/1000.00}, siehe Formatfilter) oder geben Sie den Wert in der Einheit des Geräts aus.
• Gesendete Werte werden auf min/max begrenzt.
• Ein umgekehrter Bereich ist möglich, z. B. "internalMin": 100, "internalMax": 0 für eine Beschattung, die 0 % als geschlossen meldet.

Einheiten

unit ist entweder eine Kategorie, die die App für jeden Benutzer passend anzeigt und umrechnet (temperature, percent, luminescence, voltage, current, electric, energy, co2, angle, noise, pressure, currency, bigmetric, smallmetric), oder eine feste Einheit wie W, kW, kWh, Hz, m³/h, die so angezeigt wird.

Für color-temperature gilt: Der Wert ist in nomos immer in Mired. Spricht das Gerät Kelvin, geben Sie "internalUnit": "kelvin" an, den Kelvin-Bereich kalt zuerst ("internalMin": 6500, "internalMax": 2700) und als min/max die Mired-Werte (154/370).

Verarbeitung

process an einer Rückmeldung bearbeitet den Wert nach dem Empfang, unter anderem: invert (Vorzeichen drehen), wattHoursToKilowattHours, openCloseToBoolean (Wörter wie open/closed in Ja/Nein), calculateGridPrice, calculatePhotovoltaicsPrice, calculateWaterPrice (Wert × Preis aus der Systemvariable GRID_PRICE, PV_PRICE bzw. WATER_PRICE). Auslöser in Automationen vergleichen den Wert vor dieser Verarbeitung.

Darstellung

customFormat legt fest, wie die App einen Wert zeigt. Der Schlüssel format ist ein Ausdruck in JsonLogic, der den angezeigten Wert berechnet; jeder weitere Schlüssel ist eine Farbe, die gilt, wenn ihr Ausdruck wahr ist.

"grid": {"method": "get", "property": "GRID", "datatype": "float", "unit": "W",
	"customFormat": {
		"format": {"Math.abs": {"Math.round": {"var": "value"}}},
		"red-minus": {"<": [{"var": "value"}, 0]},
		"green-plus": {">": [{"var": "value"}, 0]}
	}}

Für format gibt es zusätzlich Math.round, Math.abs und die übrigen Math-Funktionen, toFixed1, toFixed2, toFixed3 sowie CustomFormatter.toHHMM und CustomFormatter.toHHMMSS (Sekunden als Uhrzeit). Farben: green, red, blue, orange, purple, als Textfarbe allein oder mit -plus, -minus, -circle, -square als Punkt vor dem Wert.

Beschriftungen und Gruppen

propertiesMeta und mappingsMeta geben jeder Aktion bzw. Rückmeldung ihre Beschriftung:

"mappingsMeta": {
	"power": {"text": "Power", "group": "Vehicle charging", "properties": ["power"]}
}

• text: Beschriftung. Der Benutzer kann sie je Gerät umbenennen.
• group: Abschnitt, unter dem die App den Wert zeigt. Nur bei Geräten mit vielen Werten; sonst weglassen. Die Abschnitte erscheinen in der Reihenfolge im Profil.
• properties: Welche Einträge diese Zeile zusammenfasst, z. B. state, switchon und switchoff. Bei KNX wird aus jedem Eintrag in propertiesMeta und mappingsMeta ein Feld für eine Gruppenadresse.

Übersetzung

Beschriftungen, Gruppen und Texte von Wertelisten und Vorlagen werden übersetzt, wenn sie genau einem Begriff entsprechen, den nomos kennt, etwa State, Brightness, Power, Temperature, Reachable, Turn On, Is Turned On, Off, Low, Medium, High. Jeder andere Text erscheint in allen Sprachen so, wie er im Profil steht. Schreiben Sie solche Texte deshalb in der Sprache der Anlage, oder nehmen Sie die englischen Standardbegriffe, die der Profil Editor vorschlägt.

Vorlagen

Vorlagen sind die Einträge, die Automationen und die Quick Konfig anbieten.

"actionTemplates": [
	{"templateid": "switchon", "mapping": "switchon", "text": "Turn On", "icon": "toggle-on"},
	{"templateid": "level", "mapping": "level", "text": "Brightness", "icon": "sun-o"}
],
"triggerTemplates": [
	{"templateid": "state.on", "mapping": "state", "text": "Is Turned On", "value": "1", "icon": "toggle-on"}
]

Feld	Bedeutung
templateid	Eindeutige Kennung; wird in gespeicherten Automationen verwendet, deshalb später nicht mehr ändern
mapping	Die Aktion (bei actionTemplates) bzw. Rückmeldung (bei triggerTemplates), auf die sich die Vorlage bezieht. Gibt es sie nicht, fällt die Vorlage weg
text, textsuffix	Beschriftung und Zusatz
icon	Name eines Font-Awesome-Symbols ohne fa-, z. B. toggle-on, bolt, thermometer
value	Fester Wert; die Automation zeigt dann kein Eingabefeld
valueList	Auswahl in der Automation; Kopie der Liste der Aktion bzw. Rückmeldung
placeholder	Beispieltext im leeren Eingabefeld einer Aktion mit Text
hideInQuickConfig	true: nicht in der Quick Konfig, aber in Automationen

hideProperties: true bzw. hideMappings: true bewirken, dass Automationen nur die Vorlagen anbieten statt aller Aktionen bzw. Rückmeldungen. Der Profil Editor setzt beide beim Speichern selbst: true, sobald es mindestens eine Vorlage gibt.

Abfragen

Nur CommandServer. Jeder Eintrag sendet einen Befehl aus structure.commands in festem Abstand, beim Start sofort einmal:

"polling": {
	"Status": {"interval": 30, "editableInterval": true, "command": "STATUS"}
}

• interval: Abstand in Sekunden.
• editableInterval: true: Das Intervall wird beim Anlegen des Geräts abgefragt (vorbelegt mit interval).
• value und editableValue: optionaler Wert, der mit dem Befehl gesendet wird, und ob er beim Anlegen abgefragt wird.

Unterprofile können nicht abfragen; Abfragen gehören zum Hauptprofil.

Webhooks

Mit Webhooks meldet ein Gerät Werte selbst, statt abgefragt zu werden, z. B. ein Taster, der bei jedem Druck eine Adresse aufruft. Im Profil geben Sie an, welche Rückmeldungen das dürfen; jeder Eintrag braucht eine Rückmeldung gleichen Namens:

"hooks": {"action": {"enabled": true}, "battery": {"enabled": true}},
"mappings": {
	"action":  {"method": "get", "property": "ACTION", "datatype": "int"},
	"battery": {"method": "get", "property": "BATTERY", "datatype": "int", "unit": "percent"}
}

Beim Anlegen des Geräts nennt der Controller die Adresse, die das Gerät aufrufen soll. Sie hat die Form http://<IP des Controllers>/api/v1/hook/<Geräte-ID>; die Werte stehen als Parameter in der Adresse (GET) oder im Body (POST, als Formular oder JSON):

http://192.168.1.10/api/v1/hook/C12?action=1&battery=98

Der Controller übernimmt nur Parameter, die in hooks freigegeben sind, und antwortet mit 200, wenn mindestens ein Wert übernommen wurde, sonst mit 204.

DANGER

Webhooks haben keine Anmeldung. Jedes Gerät im lokalen Netz, das die Adresse kennt, kann die freigegebenen Werte setzen. Über den Fernzugriff ist die Adresse gesperrt. Geben Sie deshalb nur Rückmeldungen frei, die ein Gerät tatsächlich senden muss, und lösen Sie mit ihnen keine sicherheitsrelevanten Automationen aus, etwa das Öffnen einer Tür.

Kameras

"cameras": [
	{"type": "mjpeg", "url": "http://%SERVERIP%/mjpegstream.cgi?usr=%USERNAME%&pwd=%PASSWORD%"}
]

type: snapshot (Einzelbild, Standard), mjpeg, rtsp oder otherhttp. In der URL werden Platzhalter %NAME% durch die Werte aus der Kommunikation ersetzt. Beim Anlegen des Geräts entsteht je Eintrag eine Kamera. Ist bei rtsp oder otherhttp die Höchstzahl an Videostreams erreicht, wird die Kamera ohne Meldung übersprungen.

Unterprofile

"components": {
	"out1": {"name": "Ausgang 1", "category": "Switches", "type": "Switch",
		"properties": {}, "propertiesMeta": {}, "mappings": {}, "mappingsMeta": {}}
}

Jeder Schlüssel wird beim Anlegen des Geräts ein eigenes Gerät namens „Gerätename Ausgang 1“. Alle teilen die Verbindung des Hauptprofils; structure, polling und cameras gibt es nur im Hauptprofil. Fehlende Grunddaten (Version, Hersteller, Kategorie, Typ, Engine-Typ) übernimmt ein Unterprofil vom Hauptprofil. Den Schlüssel eines Unterprofils nicht mehr ändern, wenn Geräte es verwenden.

MQTT

MQTT-Profile verwenden den Broker, der im MQTT-Skill eingerichtet ist; ein Profil kann keinen eigenen Broker wählen. Beim Anlegen des Geräts geben Sie ein MQTT Topic ein, das im Profil als %mqttTopic% steht.

"properties": {
	"switchon": {"method": "command", "command": "power", "value": 1,
		"mqtt": "cmnd/%mqttTopic%/POWER", "datatype": "null", "uihidden": true},
	"level": {"method": "command", "command": "brightness",
		"mqtt": "cmnd/%mqttTopic%/Dimmer", "datatype": "int", "unit": "percent"}
},
"mappings": {
	"level": {"method": "get", "property": "dimmer", "mqtt": "stat/%mqttTopic%/RESULT",
		"mqttValue": "Dimmer", "datatype": "int", "unit": "percent"},
	"reachable": {"method": "get", "property": "reachable", "mqtt": "tele/%mqttTopic%/LWT",
		"mqttValue": "", "datatype": "bool", "defaultValue": true}
}

Feld	Bedeutung
mqtt	Topic. Bei Rückmeldungen sind + und # als Platzhalter erlaubt
command	Aktionen: Name des Befehls. Aktionen mit demselben command müssen dasselbe Topic haben, wie switchon und switchoff
mqttPayload	Aktionen: Nutzlast mit \# als Platz für den Wert, z. B. {"brightness":\#}. Ohne mqttPayload wird der Wert allein gesendet
mqttValue	Rückmeldungen: Welcher Teil einer JSON-Nutzlast der Wert ist. Mit Punkt ein Pfad (ENERGY.Power), ohne Punkt das erste Feld dieses Namens, bei einem Array eine Position. Leer: die ganze Nutzlast
mqttScale	Rückmeldungen: wird als Einheit an den Wert gehängt, rechnet aber nicht um. Nur zusammen mit "unit": "energy" sinnvoll (kW wird zu W)

• Gesendet wird mit QoS 0 und ohne Retain.
• %mqttTopic% wird in mqtt, command und property ersetzt, nicht in mqttPayload.
• Ohne Rückmeldung reachable gilt das Gerät immer als erreichbar. Mit dem LWT-Topic des Geräts (Online/Offline) stimmt die Erreichbarkeit.

Fertige MQTT-Vorlagen und eine Node-RED-Anleitung zum Anbinden beliebiger Geräte beschreibt die Seite MQTT-Vorlagen der Add-on-Bibliothek.

KNX

Ein KNX-Profil enthält keine Adressen. Es legt fest, welche Werte ein Gerät hat und wie groß sie auf dem Bus sind; die Gruppenadressen ordnen Sie beim Anlegen des Geräts zu. Gerät erstellen öffnet dafür den Dialog des KNX-Skills mit dem Profil.

"className": "KNX", "engineType": "KNX", "platform": "KNX",
"properties": {
	"state":     {"method": "set", "property": "value", "datatype": "bool", "sizeInBit": 1, "filterDPT": ["1.001"]},
	"switchon":  {"method": "set", "property": "value", "value": 1, "datatype": "bool", "sizeInBit": 1, "uihidden": true},
	"switchoff": {"method": "set", "property": "value", "value": 0, "datatype": "bool", "sizeInBit": 1, "uihidden": true}
},
"propertiesMeta": {"state": {"text": "State", "properties": ["state", "switchon", "switchoff"]}},
"mappings": {
	"state": {"method": "get", "property": "value", "datatype": "bool", "sizeInBit": 1, "filterDPT": ["1.001"]}
},
"mappingsMeta": {"state": {"text": "State", "properties": ["state"]}}

• className und platform sind immer KNX, property ist immer value.
• Jeder Eintrag in propertiesMeta wird ein Feld für die Gruppenadresse zum Schalten, jeder Eintrag in mappingsMeta eines für die Statusadresse. Der Schlüssel muss selbst der Name einer Aktion bzw. Rückmeldung sein. Die Adresse für state gilt auch für switchon und switchoff.
• sizeInBit muss zum Datenpunkttyp passen (1 Bit für Schalten, 8 Bit für Prozent und Stufen, 16 Bit für Temperaturen); filterDPT schränkt die Auswahl beim Zuordnen ein. Die Einheit kommt vom Datenpunkttyp der Gruppenadresse.
• Ein Wert ohne Gruppenadresse tut nichts und erscheint nicht in der App.
• Eine Rückmeldung reachable ist nicht nötig; die Erreichbarkeit folgt der KNX-Verbindung.

Viele Gerätearten (Licht, Dimmer, Beschattung, Thermostat, Sensoren) bringt der KNX-Skill schon mit. Ein eigenes Profil lohnt sich für Geräte, die dort fehlen. Hinweise zu Gruppenadressen und Datenpunkttypen stehen auf der Seite KNX-Vorlagen der Add-on-Bibliothek.

Häufige Fehler

• Werte bleiben leer: Bei CommandServer fehlt die Rückmeldung in mappings, oder ihr property passt nicht zum Namen des Antwortmusters in structure.mappings.
• Schalter springt zurück: Es gibt keine Rückmeldung state, oder das Gerät meldet den Zustand nicht.
• App schaltet nicht: switchon/switchoff fehlen; die App sendet nie state selbst.
• Zahlen falsch skaliert: max ohne internalMin/internalMax (siehe Skalierung).
• Automation bietet einen Wert nicht an: Es gibt Vorlagen, aber keine für diesen Wert (siehe Vorlagen).
• Gerät immer erreichbar: Bei CommandServer fehlen CONNECTEVENT/DISCONNECTEVENT, bei MQTT die Rückmeldung reachable (siehe Erreichbarkeit).
• Ein zweites Profil …_2: Es entsteht nur, wenn Sie bei einem im Profil Editor geänderten Profil Als Kopie wählen. Sonst ersetzt ein erneuter Upload oder Import das vorhandene Profil (siehe Updates aus der Online-Bibliothek).