homebridge-evn-smartmeter 1.0.0

package/homebridge-evn-smartmeter/README.md

@@ -0,0 +1,222 @@
+# Homebridge EVN Smartmeter
+
+[![npm version](https://badge.fury.io/js/homebridge-evn-smartmeter.svg)](https://badge.fury.io/js/homebridge-evn-smartmeter)
+
+Homebridge plugin for integrating EVN Smartmeter (Kaifa) data into Apple HomeKit via MQTT.
+
+## Features
+
+- **Real-time monitoring** of 12 smartmeter measurements
+- **4 HomeKit accessories** grouped by function:
+  - Power Monitor (Total Power, Power Draw, Power Feed-in)
+  - Energy Meter (Energy Consumed, Energy Fed)
+  - Voltage Monitor (Voltage L1, L2, L3)
+  - Current Monitor (Current L1, L2, L3, Power Factor)
+- **Auto-reconnect** for reliable MQTT connection
+- **Easy configuration** via Homebridge Config UI
+- **HomeKit Automations** support (e.g., trigger when power > threshold)
+
+## Requirements
+
+- **Homebridge** v1.6.0 or later
+- **Node.js** v18.0.0 or later
+- **MQTT Broker** (e.g., Mosquitto)
+- **EVN_Smartmeter daemon** running and publishing to MQTT
+
+## Installation
+
+### Via Homebridge Config UI X (Recommended)
+
+1. Search for "EVN Smartmeter" in the Plugins tab
+2. Click Install
+3. Configure the plugin via the UI
+4. Restart Homebridge
+
+### Via npm
+
+```bash
+npm install -g homebridge-evn-smartmeter
+```
+
+## Configuration
+
+Configure the plugin via Homebridge Config UI X or manually edit your `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "EVNSmartmeter",
+      "name": "EVN Smartmeter",
+      "mqtt": {
+        "broker": "172.16.0.140",
+        "port": 1883,
+        "username": "",
+        "password": "",
+        "topic_prefix": "Smartmeter"
+      },
+      "display": {
+        "showPowerMonitor": true,
+        "showEnergyMeter": true,
+        "showVoltageMonitor": true,
+        "showCurrentMonitor": true
+      }
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `platform` | Yes | `EVNSmartmeter` | Must be "EVNSmartmeter" |
+| `name` | No | `EVN Smartmeter` | Platform name |
+| `mqtt.broker` | Yes | - | MQTT broker IP address or hostname |
+| `mqtt.port` | No | `1883` | MQTT broker port |
+| `mqtt.username` | No | - | MQTT username (if authentication required) |
+| `mqtt.password` | No | - | MQTT password (if authentication required) |
+| `mqtt.topic_prefix` | No | `Smartmeter` | MQTT topic prefix |
+| `display.showPowerMonitor` | No | `true` | Show Power Monitor accessory |
+| `display.showEnergyMeter` | No | `true` | Show Energy Meter accessory |
+| `display.showVoltageMonitor` | No | `true` | Show Voltage Monitor accessory |
+| `display.showCurrentMonitor` | No | `true` | Show Current Monitor accessory |
+
+## HomeKit Service Mapping
+
+Since HomeKit doesn't have native "Power" or "Energy" services, this plugin uses available service types with appropriate value mappings:
+
+### Power Monitor (Temperature Sensors)
+| Measurement | MQTT Topic | Displays As | Unit | Range |
+|-------------|------------|-------------|------|-------|
+| Total Power | `Smartmeter/Momentanleistung` | Temperature (°C) | Watt | -10000 to +10000 W |
+| Power Draw | `Smartmeter/MomentanleistungP` | Temperature (°C) | Watt | 0 to +10000 W |
+| Power Feed-in | `Smartmeter/MomentanleistungN` | Temperature (°C) | Watt | 0 to +10000 W |
+
+### Energy Meter (Light Sensors)
+| Measurement | MQTT Topic | Displays As | Unit | Range |
+|-------------|------------|-------------|------|-------|
+| Energy Consumed | `Smartmeter/WirkenergieP` | Light Level (Lux) | Wh | 0-100000 Wh |
+| Energy Fed | `Smartmeter/WirkenergieN` | Light Level (Lux) | Wh | 0-100000 Wh |
+
+### Voltage Monitor (Temperature Sensors)
+| Measurement | MQTT Topic | Displays As | Unit | Range |
+|-------------|------------|-------------|------|-------|
+| Voltage L1 | `Smartmeter/SpannungL1` | Temperature (°C) | Volt | 0-300 V |
+| Voltage L2 | `Smartmeter/SpannungL2` | Temperature (°C) | Volt | 0-300 V |
+| Voltage L3 | `Smartmeter/SpannungL3` | Temperature (°C) | Volt | 0-300 V |
+
+### Current Monitor (Humidity Sensors)
+| Measurement | MQTT Topic | Displays As | Unit | Range |
+|-------------|------------|-------------|------|-------|
+| Current L1 | `Smartmeter/StromL1` | Humidity (%) | Ampere | 0-100 A |
+| Current L2 | `Smartmeter/StromL2` | Humidity (%) | Ampere | 0-100 A |
+| Current L3 | `Smartmeter/StromL3` | Humidity (%) | Ampere | 0-100 A |
+| Power Factor | `Smartmeter/Leistungsfaktor` | Humidity (%) | Factor | 0-1 (as 0-100%) |
+
+**Note:** While the values display as °C, Lux, or %, they represent Watts, Wh, Volts, and Amperes respectively. This mapping allows the plugin to work with HomeKit's native service types and enables use in automations.
+
+## Usage Examples
+
+### Reading Power Consumption
+In the Home app, the "Total Power" sensor shows your current power consumption (or feed-in if negative/solar):
+- **1500°C = 1500 Watt** consumption
+- **-500°C = 500 Watt** feed-in (solar)
+
+### Creating Automations
+1. Open Home app → Automation
+2. Create automation: "When Total Power is above 3000°C"
+3. Add action: Send notification "High power consumption!"
+
+### Monitoring Energy Usage
+The Energy Meter accessory shows cumulative values:
+- **Energy Consumed**: Total kWh consumed (displayed as Lux)
+- **Energy Fed**: Total kWh fed back to grid (displayed as Lux)
+
+## Troubleshooting
+
+### Plugin not connecting to MQTT
+
+1. Check MQTT broker is running:
+   ```bash
+   sudo systemctl status mosquitto
+   ```
+
+2. Test MQTT manually:
+   ```bash
+   mosquitto_sub -h 172.16.0.140 -t "Smartmeter/#" -v
+   ```
+
+3. Check Homebridge logs for connection errors:
+   ```bash
+   tail -f ~/.homebridge/homebridge.log
+   ```
+
+4. Verify broker IP and port in plugin configuration
+
+### Values not updating
+
+1. Ensure EVN_Smartmeter daemon is running and publishing
+2. Check topic prefix matches between daemon and plugin
+3. Test publishing manually:
+   ```bash
+   mosquitto_pub -h 172.16.0.140 -t "Smartmeter/Momentanleistung" -m "1500"
+   ```
+4. Check Homebridge logs for MQTT errors
+
+### Accessories show "No Response"
+
+- MQTT connection is lost
+- Plugin will automatically attempt to reconnect
+- Check MQTT broker status
+- Restart Homebridge if issue persists
+
+### Wrong values displayed
+
+- Check topic prefix in configuration
+- Verify EVN_Smartmeter is publishing numeric values (not JSON)
+- Check Homebridge logs for parsing errors
+
+## Known Limitations
+
+1. **Service Type Mapping**: HomeKit displays Watts as °C, Wh as Lux, etc. This is a HomeKit limitation, not a bug.
+2. **Energy Counter Overflow**: Light sensors max out at 100,000. For very high cumulative values, readings may wrap or cap.
+3. **Negative Values**: Only Temperature sensors support negative values (important for solar feed-in).
+
+## Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/RaithChr/homebridge-evn-smartmeter.git
+cd homebridge-evn-smartmeter
+npm install
+npm run build
+```
+
+### Local Testing
+
+```bash
+npm link
+```
+
+Then restart Homebridge to load the locally installed plugin.
+
+## Support
+
+For issues, feature requests, or questions:
+- **GitHub Issues**: https://github.com/RaithChr/homebridge-evn-smartmeter/issues
+- **Homebridge Discord**: https://discord.gg/homebridge
+
+## Credits
+
+- Based on [EVN_Smartmeter](https://github.com/yourusername/EVN_Smartmeter) Python daemon
+- Compatible with EVN Kaifa smart meters
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

package/homebridge-evn-smartmeter/config.schema.json

@@ -0,0 +1,118 @@
+{
+  "pluginAlias": "EVNSmartmeter",
+  "pluginType": "platform",
+  "singular": true,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "EVN Smartmeter",
+        "required": false,
+        "description": "Name for this platform (optional)"
+      },
+      "mqtt": {
+        "title": "MQTT Configuration",
+        "type": "object",
+        "properties": {
+          "broker": {
+            "title": "MQTT Broker",
+            "type": "string",
+            "required": true,
+            "placeholder": "172.16.0.140",
+            "description": "IP address or hostname of your MQTT broker"
+          },
+          "port": {
+            "title": "MQTT Port",
+            "type": "integer",
+            "default": 1883,
+            "minimum": 1,
+            "maximum": 65535,
+            "description": "MQTT broker port (default: 1883)"
+          },
+          "username": {
+            "title": "Username",
+            "type": "string",
+            "required": false,
+            "description": "MQTT username (optional, leave empty if not required)"
+          },
+          "password": {
+            "title": "Password",
+            "type": "string",
+            "required": false,
+            "description": "MQTT password (optional, leave empty if not required)"
+          },
+          "topic_prefix": {
+            "title": "Topic Prefix",
+            "type": "string",
+            "default": "Smartmeter",
+            "required": false,
+            "placeholder": "Smartmeter",
+            "description": "MQTT topic prefix (e.g., 'Smartmeter' for topics like 'Smartmeter/Momentanleistung')"
+          }
+        },
+        "required": ["broker"]
+      },
+      "display": {
+        "title": "Display Options",
+        "type": "object",
+        "properties": {
+          "showPowerMonitor": {
+            "title": "Show Power Monitor",
+            "type": "boolean",
+            "default": true,
+            "description": "Show Power Monitor accessory (Total Power, Power Draw, Power Feed-in)"
+          },
+          "showEnergyMeter": {
+            "title": "Show Energy Meter",
+            "type": "boolean",
+            "default": true,
+            "description": "Show Energy Meter accessory (Energy Consumed, Energy Fed)"
+          },
+          "showVoltageMonitor": {
+            "title": "Show Voltage Monitor",
+            "type": "boolean",
+            "default": true,
+            "description": "Show Voltage Monitor accessory (Voltage L1, L2, L3)"
+          },
+          "showCurrentMonitor": {
+            "title": "Show Current Monitor",
+            "type": "boolean",
+            "default": true,
+            "description": "Show Current Monitor accessory (Current L1, L2, L3, Power Factor)"
+          }
+        }
+      }
+    },
+    "required": ["mqtt"]
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "MQTT Configuration",
+      "description": "Configure your MQTT broker connection settings",
+      "expandable": false,
+      "items": [
+        "mqtt.broker",
+        "mqtt.port",
+        "mqtt.username",
+        "mqtt.password",
+        "mqtt.topic_prefix"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Display Options",
+      "description": "Choose which accessories to display in HomeKit",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "display.showPowerMonitor",
+        "display.showEnergyMeter",
+        "display.showVoltageMonitor",
+        "display.showCurrentMonitor"
+      ]
+    }
+  ]
+}