Connecting digitalSTROM with Home Assistant: local integration and automations

In digitalSTROM installations, lights, blinds, and other loads are connected to terminals in the electrical panel, controlled via push buttons and a digitalSTROM server (dSS20). When other systems such as Philips Hue, Sonos, and a FRITZ!Box are added, it makes sense to bring everything together locally in Home Assistant, without a cloud account and without storing the dSS password in Home Assistant. To do this, I wrote a small integration and published it together with suitable automations as pfstr/ha-digitalstrom-local under the MIT License.

In short: the dSS provides a usable JSON API with events. If used carefully, it delivers push buttons, scenes, and the Leaving and Arriving activities to Home Assistant without delay, allowing automations that digitalSTROM alone does not support.

How the integration works

The dSS provides its API via HTTPS on port 8080, using a self-signed certificate. digitalSTROM provides app tokens for programs: the program requests a token, the user authorizes it in the Configurator under System > Access authorization, and the program then logs in with it. The dSS password remains with the user.

DSS=https://dss.local:8080/json
curl -sk "$DSS/system/requestApplicationToken?applicationName=Home%20Assistant"
curl -sk "$DSS/system/loginApplication?loginToken=<APP-TOKEN>"
curl -sk "$DSS/event/subscribe?name=callScene&subscriptionID=42&token=<SESSION>"
curl -sk "$DSS/event/get?subscriptionID=42&timeout=30000&token=<SESSION>"

The integration keeps such a long-poll connection open continuously. Every scene triggered by a push button, the app, or the Configurator arrives as an event. States such as “light on in room” or presence are stored in the dSS cache under /usr/states and can be queried without putting load on the terminals.

Direct queries of output values (device/getOutputValue) instead travel over the dS485 bus to the terminal and take half a second to a full second per value. Many such queries at short intervals can overload the meters. The integration therefore reads only blind positions and Joker outputs directly, every 15 minutes and about one minute after movement.

In addition, the integration reports every room scene as well as Leaving and Arriving as the digitalstrom_local_event event to Home Assistant. This makes it possible to freely assign 2× or 4× taps on a regular light switch.

Automations as blueprints

The following automations are included in the repository as blueprints and can be imported into Home Assistant using the import button in the README.

Motion-activated lighting that does not turn off manually switched-on lights

When motion is detected, the light turns on, then turns off again after an adjustable period without motion. Optionally, this applies only below a brightness threshold, only during a time window, or dimmed at night. If someone turns on the light using the push button, it remains on. A helper switch (input_boolean) records whether the automation turned on the light; only then does it turn it off again.

One detail only becomes apparent in operation: the “sensor clear for 2 minutes” trigger is a counter that Home Assistant discards at every restart. If the sensor last detected motion before the restart, it does not switch to “clear” again, and the light stays on. The blueprint therefore also checks every minute whether a light it turned on is still lit even though the sensor has been clear long enough.

Turn off lights when leaving the room

The motion-lighting shutoff time is a compromise: too short, and the light turns off while someone is standing still in the room; too long, and it remains on for minutes after they leave. Another blueprint therefore uses a second sensor outside the room, typically in the hallway. If it detects motion, the sensor in the room detected motion shortly before (within 30 seconds), and it then remains clear there, the room light turns off immediately. With Hue sensors, which report “clear” about 10 seconds after the last motion, this takes around 10 to 15 seconds after leaving the room.

To ensure nobody is left sitting in the dark, the rule applies only under certain conditions: the light must have been turned on by the motion automation, shower mode must not be active, and at most one person may be home. The number of people is determined from the phones that Home Assistant knows as persons. The 30-second condition also protects against the case where someone remains still in the room while another person walks through the hallway.

Shower mode with 2× tapping

In the shower, a motion sensor usually does not detect anyone, and after the configured time it gets dark. Tapping the bathroom button 2× triggers mood 2 (scene 17) in digitalSTROM. The automation detects this scene in the room and enables a shower mode that blocks switching off. Motion during the first 2 minutes is ignored (undressing, getting in). The first motion after that ends shower mode, after which the normal shutoff time applies again. After an adjustable maximum duration (20 minutes by default), it ends automatically.

4× tapping starts Sonos

If you tap a button rapidly several times, digitalSTROM cycles through moods in sequence: scene 5, 17, 18, and scene 19 on the fourth tap. If you set scene 19 to “Do not change output” for all lights in the Configurator, it is available for other purposes. A blueprint responds to this scene, turns off the room light, and starts the Sonos speaker in the room or, in rooms without a speaker, several speakers together.

The corresponding script considers three points: if a speaker is already playing, the new room is added to its group so that playback remains synchronized. If nothing can be resumed, it plays a radio station from the Radio Browser directory. And the same starting volume is set before every start; otherwise, one room plays quietly while another plays as loudly as someone last listened to music there.

Leaving and arriving via FRITZ!Box

The FRITZ!Box Tools integration reports whether a phone is on Wi-Fi; it evaluates the box’s device list and therefore covers the 2.4 GHz network, 5 GHz network, and LAN at the same time. If nobody is home anymore and Leaving was not triggered, a blueprint triggers Leaving. On arriving home, Arriving follows and, if it is dark, a welcome light.

Additionally, an automation can turn off lights from other systems (such as Hue) and pause Sonos when Leaving is triggered. The dSS turns off the digitalSTROM lights itself.

Floor plan as a dashboard

A clear display in Home Assistant is a floor plan using the built-in picture-elements card. Each room has a transparent SVG overlaid on the plan, replaced by a slightly yellow one when the light is on; tapping the room switches the light. Lights, speakers, blinds, and sensors are placed as symbols at their locations. Instructions with an example configuration are available in the repository under docs/floor-plan-dashboard.md.

Issues encountered in practice

A device search on the Hue Bridge adds all devices currently in pairing mode. Afterwards, check the device list to ensure that only your own lights were added.

The terminals’ scene tables can be read and changed through the API, for example with device/getSceneMode and device/saveScene. Each of these calls goes over the bus. Before making changes, back up the old values, for example in a CSV file, so that you can restore them if necessary.