ebaauw / homebridge-p1

Homebridge plugin for DSMR end-consumer (P1) interface
Apache License 2.0
53 stars 11 forks source link
dsmr dsmrp1 homebridge-plugin homekit p1 smartmeter

Homebridge P1

Downloads Version Homebridge Discord verified-by-homebridge

GitHub issues GitHub pull requests JavaScript Style Guide

Homebridge plugin for DSMR end-consumer (P1) interface

Copyright © 2018-2024 Erik Baauw. All rights reserved.

This Homebridge plugin exposes a smart meter to Apple's HomeKit, using the end-consumer (P1) interface of the Dutch Smart Meter Requirements (DSMR). It provides insight from HomeKit into your actual and historic energy consumption.

The smart meter sends a push notification ("telegram" in DSMR speak), every second, updating the electricity consumption almost in real time. Older versions of DSMR might send notifications less frequently. Gas consumption is updated once every five minutes. Homebridge P1 maintains the historic consumption.

Depending on the smart meter capabilities, Homebridge P1 exposes up to three HomeKit accessories:

Each accessory exposes a service with Total Consumption, just like an Eve Energy, enabling the Eve app to display the consumption history. Eve computes the Total Cost and Projected Cost.

In case of 3-phase electricity, the accessory contains a service per phase showing Power, Current, and Voltage.

Prerequisites

You need a smart meter that provides a P1 port that complies to DSMR (currently DSMR 5.0, DSMR 4.2, and DSMR 2.2+ are tested).
The companies maintaining the electricity and natural gas networks in the Netherlands, united in Netbeer Nederland are replacing existing electricity and gas meters with smart meters. In my home, they installed a Landys +Gyr E350 (ZCF1100).
Smart meters in Flandres (Belgium), Luxembourg, and Sweden might provide a P1 port as well. I don't know about the rollout plans in those countries. One Flandres installation is reported working, see #47; one Swedish installation is reported not working, see #50.

You need a cable to connect the smart meter's P1 port to a USB port. I got mine here, but you could also make one yourself, as described here. The cable is quite short (~1m) but you can extend it using a regular USB extension cable (female-A to A).

You need a server to run Homebridge. This can be anything running Node.js: from a Raspberry Pi, a NAS system, or an always-on PC running Linux, macOS, or Windows. See the Homebridge Wiki for details. I run Homebridge P1 on a Raspberry Pi 3B+.

Note that Homebridge P1 uses the serialport package to connect to the P1 cable. This package uses some non-JavasScript addons, that need to be compiled while installing Homebridge P1. The server running Homebridge P1 needs to have the appropriate development tools installed.

The user running Homebridge needs privileges to list the serial port devices and to open the serial port device for the P1 cable. Under Raspbian, user pi has these privileges by default. If you run Homebridge under a different user, make sure it's member of the dialout group, and, for Buster, of the gpio group.

To interact with HomeKit, you need Siri or a HomeKit app on an iPhone, Apple Watch, iPad, iPod Touch, or Apple TV (4th generation or later). I recommend to use the latest released versions of iOS, watchOS, and tvOS.
Please note that Siri and even Apple's Home app still provide only limited HomeKit support. To use Homebridge P1, you want to check out some other HomeKit apps, like the Eve app (free) or Matthias Hochgatterer's Home+ app (paid).

As HomeKit uses Bonjour to discover Homebridge, the server running Homebridge must be on the same subnet as your iDevices running HomeKit. For remote access and for HomeKit automations, you need to setup an Apple TV (4th generation or later), HomePod, or iPad as home hub.

Installation

To install Homebridge P1:

Configuration

Homebridge P1 should detect the USB serial cable automatically. In case it doesn't or when you have multiple USB serial devices, you can specify the serialport in config.json:

"platforms": [
  {
    "platform": "P1",
    "serialport": "/dev/ttyUSB0"
  }
]

If Homebridge P1 doesn't receive any data and you have a meter with an older DSMR version, you might need to specify:

"platforms": [
  {
    "platform": "P1",
    "serialport": "/dev/ttyUSB0",
    "dsmr22": true
  }
]

If Homebridge P1 receives data too late (i.e. after the Homebridge server has started) no accessories will be exposed to HomeKit. In this case, set "timeout" in config.json and restart Homebridge. This parameter specifies the number of seconds Homebridge P1 waits for data, before giving up and letting Homebridge startup continue without any P1 accessories. Note that accessories from other plugins will not be reachable while Homebridge P1 waits for data, so you want to set "timeout" as low as possible, while keeping in mind a telegram might be lost due to communication glitches. The default of "timeout": 5 assumes the meter sends a telegram every second. DSMR v2.2 meters only send a telegram every 10 seconds, so when "dsmr22": true is set, a default "timeout": 50 is used.

Caveats

Homebridge P1 is a hobby project of mine, provided as-is, with no warranty whatsoever. I've been running it successfully at my home for years, but your mileage might vary.

The HomeKit terminology needs some getting used to. An accessory more or less corresponds to a physical device, accessible from your iOS device over WiFi or Bluetooth. A bridge (like Homebridge) is an accessory that provides access to other, bridged, accessories. An accessory might provide multiple services. Each service corresponds to a virtual device (like a lightbulb, switch, motion sensor, ..., but also: a programmable switch button, accessory information, battery status). Siri interacts with services, not with accessories. A service contains one or more characteristics. A characteristic is like a service attribute, which might be read or written by HomeKit apps. You might want to checkout Apple's HomeKit Accessory Simulator, which is distributed as an additional tool for Xcode.

Exposing the smart meter to HomeKit is a bit of a hack, lacking proper HomeKit support for smart meters. Also, Eve lacks proper support for gas consumption. The following limitations apply: