MBMD: document negation (#993)

Author: naltatis

docs/devices/plugins.mdx

@@ -633,6 +633,18 @@ Das `modbus`-Plugin kann Daten von jedem Modbus-fähigen Gerät oder SunSpec-kom
 Viele Strommessgeräte sind bereits vorkonfiguriert (siehe [MBMD Supported Devices](https://github.com/volkszaehler/mbmd#supported-devices)).
 Es ist ebenfalls möglich Modbus Register zu Schreiben um weitere Wallboxen zu integrieren.
 
+**Beispiel**:
+
+```yaml
+source: modbus
+id: 1
+uri: 192.168.1.10:502
+register:
+  address: 300
+  type: holding
+  decode: uint16
+```
+
 Schaue in die [Modbus Dokumentation](/docs/reference/modbus) für weitere Details.
 
 ### MQTT <Tag label="lesen" category="read" /> <Tag label="schreiben" category="write" /> {#mqtt}

docs/reference/modbus.md

@@ -114,6 +114,80 @@ value: Power
 scale: -1 # floating point factor applied to result, e.g. for kW to W conversion
 ```
 
+## Negation von Werten {#negation}
+
+Bei MBMD-Messgeräten können Messwerte durch Voranstellen eines `-` (Minus) vor dem Aliasnamen invertiert werden.
+Dies ist nützlich, wenn Messgeräte in unterschiedlichen Konfigurationen oder Montagerichtungen verwendet werden und das Vorzeichen der Messwerte angepasst werden muss.
+
+### Unterstützte Messungen
+
+Die Negation funktioniert für folgende MBMD-Messungen:
+
+- `power` - Gesamtleistung
+- `currents` - Ströme pro Phase (Array)
+- `powers` - Leistungen pro Phase (Array)
+
+### Syntax
+
+```yaml
+meters:
+  - name: my-meter
+    type: modbus
+    model: sdm
+    power: -Power # invertiert den Leistungswert
+```
+
+### Beispiele
+
+#### Invertierte Gesamtleistung
+
+```yaml
+meters:
+  - name: pv-meter
+    type: modbus
+    model: sdm
+    power: -Power # Leistung wird invertiert (z. B. +1000 W wird zu -1000 W)
+```
+
+#### Invertierte Phasenleistungen
+
+```yaml
+meters:
+  - name: grid-meter
+    type: modbus
+    model: sdm
+    power: Power
+    powers:
+      - -PowerL1 # Phase 1 invertiert
+      - -PowerL2 # Phase 2 invertiert
+      - -PowerL3 # Phase 3 invertiert
+```
+
+#### Invertierte Ströme (einzelne Phasen)
+
+```yaml
+meters:
+  - name: grid-meter
+    type: modbus
+    model: sdm
+    power: Power
+    currents:
+      - -CurrentL1 # Strom Phase 1 invertiert
+      - CurrentL2 # Strom Phase 2 normal
+      - -CurrentL3 # Strom Phase 3 invertiert
+```
+
+### Anwendungsfälle
+
+**Falsch montierte Messgeräte**:
+Wenn ein Stromsensor/Messgerät physisch in der falschen Richtung installiert ist, können die Werte in der Software korrigiert werden.
+
+**Netzeinspeisung vs. Verbrauch**:
+Für PV-Messgeräte, bei denen die Vorzeichenkonvention umgekehrt werden muss.
+
+**Unterschiedliche CT-Orientierungen**:
+Für mehrphasige Installationen mit unterschiedlich ausgerichteten Stromwandlern.
+
 ## Manuelle Konfiguration
 
 Falls das Modbus-Gerät nicht direkt unterstützt wird oder von den vordefinierten Modellen abweichende Werte gelesen oder geschrieben werden sollen, können die Modbus Register auch vollständig manuell konfiguriert werden.

i18n/en/docusaurus-plugin-content-docs/current/devices/plugins.mdx

@@ -633,6 +633,18 @@ The `modbus` plugin can read data from any Modbus-capable device or SunSpec-comp
 Many power meters are already pre-configured (see [MBMD Supported Devices](https://github.com/volkszaehler/mbmd#supported-devices)).
 It's also possible to write Modbus registers to integrate additional wallboxes.
 
+**Example**:
+
+```yaml
+source: modbus
+id: 1
+uri: 192.168.1.10:502
+register:
+  address: 300
+  type: holding
+  decode: uint16
+```
+
 See the [Modbus Documentation](/docs/reference/modbus) for more details.
 
 ### MQTT <Tag label="read" category="read" /> <Tag label="write" category="write" /> {#mqtt}

i18n/en/docusaurus-plugin-content-docs/current/reference/modbus.md

@@ -110,6 +110,80 @@ value: Power
 scale: -1 # floating point factor applied to result, e.g. for kW to W conversion
 ```
 
+## Value Negation {#negation}
+
+For MBMD meters, measurement values can be inverted by prefixing the alias name with a `-` (minus sign).
+This is useful when meters are used in different configurations or mounting orientations and the sign of measurement values needs to be adjusted.
+
+### Supported Measurements
+
+Negation works for the following MBMD measurements:
+
+- `power` - Total power
+- `currents` - Currents per phase (array)
+- `powers` - Powers per phase (array)
+
+### Syntax
+
+```yaml
+meters:
+  - name: my-meter
+    type: modbus
+    model: sdm
+    power: -Power # inverts the power value
+```
+
+### Examples
+
+#### Inverted Total Power
+
+```yaml
+meters:
+  - name: pv-meter
+    type: modbus
+    model: sdm
+    power: -Power # Power will be inverted (e.g. +1000 W becomes -1000 W)
+```
+
+#### Inverted Phase Powers
+
+```yaml
+meters:
+  - name: grid-meter
+    type: modbus
+    model: sdm
+    power: Power
+    powers:
+      - -PowerL1 # Phase 1 inverted
+      - -PowerL2 # Phase 2 inverted
+      - -PowerL3 # Phase 3 inverted
+```
+
+#### Inverted Currents (Individual Phases)
+
+```yaml
+meters:
+  - name: grid-meter
+    type: modbus
+    model: sdm
+    power: Power
+    currents:
+      - -CurrentL1 # Current Phase 1 inverted
+      - CurrentL2 # Current Phase 2 normal
+      - -CurrentL3 # Current Phase 3 inverted
+```
+
+### Use Cases
+
+**Incorrectly Mounted Meters**:
+If a current sensor/meter is physically installed in the wrong direction, you can correct the values in software.
+
+**Grid Feed-in vs. Consumption**:
+For solar meters where the sign convention needs to be reversed.
+
+**Different CT Orientations**:
+For multi-phase installations with differently oriented current transformers.
+
 ## Manual Configuration
 
 If the Modbus device is not directly supported or if values deviating from the predefined models are to be read or written, the Modbus registers can also be configured manually.