digitalstrom-mqtt

KO | EN

gitlite — search

#hacktoberfest #react #typescript #llm #golang #go #android #windows #vue #awesome-list #pytorch #mcp #openai #open-source

digitalstrom-mqtt

(★ 31)

Bridge between digitalSTROM and MQTT

digitalstrom-mqtt 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DigitalSTROM MQTT

This application allows you to set and react to any DigitalSTROM devices using MQTT.

You can set the output values using the command topic and get the current value using the state topic.

![](https://raw.githubusercontent.com/gaetancollaud/digitalstrom-mqtt/master/docs/images/mqtt-explorer.png)

## Migrating from version 1.x to version 2.x

See [Migration from V1.x to V2.x](./migration_v1_v2.md)

## Motivation

[DigitalSTROM](https://www.digitalstrom.com/en/) system is built upon scenes. You press a button, and a scene starts.
The scene can trigger as many output devices as you want. While this is fine for a standalone system, it’s really
difficult to integrate with a more complex automation system. Basically, if you want the master of your automation to be
an external system, you will have a bad time.

DigitalSTROM provides a [REST api](https://developer.digitalstrom.org/api/), but it’s not that easy to use since the
structures of the element can be quite complex. There is also a notification endpoint that uses websocket to alert you
of any value change. This app uses latest version of the REST API and the notification endpoint to provide a simple MQTT
interface.

Currently, digitalSTROM integrations with home automation systems are rare and sometimes limited. The intent of this app
is to solve this issue as all of them support MQTT.

## Concept

The main goal of this application is to have direct access to the output devices (light, blinds,...) and be notified
when something changes. All of this using MQTT as it’s widely used in home automation systems.

This application will not reflect the internal functioning of digitalSTROM. It will rather try to make an abstraction of
it.

### Technical

This app use the [Smarthome API from digitalSTROM](https://developer.digitalstrom.org/api/). It doesn't use the old
`json/device/` api. The documentation is sometimes lacking, some information where found on forum and discussion groups.
Accuracy may not be the best but that's all we have.

## Configuration

You have two ways of configuring the app. Either using a `config.yaml` file next to the executable or with environment
variables.

| required | property                               | description                                                                      | default         | example                     |
|----------|----------------------------------------|----------------------------------------------------------------------------------|-----------------|-----------------------------|
| *        | DIGITALSTROM_HOST                      | Ip address of the digitalstrom system                                            |                 | 192.168.1.10                |
|          | DIGITALSTROM_PORT                      | Secure port of the rest API                                                      | 8080            |                             |
| *        | DIGITALSTROM_API_KEY                   | DigitalSTROM API key                                                             |                 | 782f...6075d                |
| *        | MQTT_URL                               | MQTT url                                                                         |                 | tcp://192.168.1.20:1883     |
|          | MQTT_USERNAME                          | MQTT username                                                                    |                 | myUser                      |
|          | MQTT_PASSWORD                          | MQTT password                                                                    |                 | 9TyVg74e5S                  |
|          | MQTT_TOPIC_PREFIX                      | Topic prefix                                                                     | digitalstrom    |                             |
|          | MQTT_NORMALIZE_DEVICE_NAME             | Remove special chars from device name                                            | true            |                             |
|          | MQTT_RETAIN                            | Retain MQTT messages                                                             | true            |                             |
|          | REFRESH_AT_START                       | should the states be refreshed at start                                          | true            |                             |
|          | LOG_LEVEL                              | log level                                                                        | INFO            | TRACE,DEBUG,INFO,WARN,ERROR |
|          | INVERT_BLINDS_POSITION                 | 100% is fully close                                                              | false           |                             |
|          | METERINGS_ENABLED                      | Whether to poll digitalSTROM metering values                                     | true            | false                       |
|          | METERINGS_INTERVAL_SECONDS             | Polling interval for digitalSTROM metering values                                | 10              | 300                         |
|          | HOME_ASSISTANT_DISCOVERY_ENABLED       | Whether or not publish MQTT Discovery messages for Home Assistant                | true            |                             |
|          | HOME_ASSISTANT_DISCOVERY_PREFIX        | Topic prefix where to publish the MQTT Discovery messaged for Home Assistant     | `homeassistant` |                             |
|          | HOME_ASSISTANT_REMOVE_REGEXP_FROM_NAME | Regular expression to remove from device names when announcing to Home Assistant |                 | `"(light\|cover)"`

### Metering traffic

The meterings module polls `api/v1/apartment/meterings/values` periodically. Large digitalSTROM installations can return
large payloads for this endpoint, so the default 10 second interval may create noticeable baseline network traffic. Set
`METERINGS_ENABLED=false` if you do not need MQTT/HA energy and power sensors, or increase
`METERINGS_INTERVAL_SECONDS` if slower updates are acceptable.

## Obtaining the API key

There is a build-in tool to get the API key. You can run it with the following command:

```shell
./digitalstrom-mqtt -mode=get-api-key -host 192.168.1.x -username=dssadmin -password=XXX
```

Just copy the API key spilled out in the console in your config file. Be sure to save the key, you want be able to see
it again and you will have to create another key.
The key will then be visible in the digitalSTROM web api under System -> Access Authorization. You can also remove it
from there if you want to.

To see all available option, you can do:

```shell    
./digitalstrom-mqtt -h
```

From docker you can run this:

```shell
docker run --rm gaetancollaud/digitalstrom-mqtt -mode=get-api-key -host 192.168.1.x -username=dssadmin -password=XXX
```

## Minimal config file

config.yaml

```yaml
DIGITALSTROM_HOST: 192.168.1.x
DIGITALSTROM_API_KEY: XXX
MQTT_URL: tcp://192.168.1.X:1883
```

### MQTT topic format

The topic format is as follows for the devices:

`{prefix}/devices/{deviceName}/{channel}/{commandState}`

The topic format is as follows for the meterings:

`{prefix}/meterings/{deviceName}/{channel}/state`

The server status topic is

`{prefix}/server/status`

## How to run

### Using the binary

Go to [Releases](https://github.com/gaetancollaud/digitalstrom-mqtt/releases), download and unzip the latest version for
your OS. Create the config file as shown above.

Start the executable

```shell
./digitalstrom-mqtt
```

### Using docker

```shell
docker run \
  -e DIGITALSTROM_HOST=192.168.1.x \
  -e DIGITALSTROM_API_KEY=XXX \
  -e MQTT_URL=tcp://192.168.1.X:1883 \
  gaetancollaud/digitalstrom-mqtt
```

### Home automation integration examples

* [Home Assistant](./docs/home-assistant/README.md)
* [OpenHAB](./docs/openhab/README.md)

### MQTT-Explorer

We recommend using https://mqtt-explorer.com/ if you want a simple interface for MQTT.

## Topics

### GE devices (lights)

```
digitalstrom/devices/DEVICE_NAME/brightness/state
digitalstrom/devices/DEVICE_NAME/brightness/command
```

### GR devices (blinds)

```
digitalstrom/devices/DEVICE_NAME/shadePositionOutside/state
digitalstrom/devices/DEVICE_NAME/shadePositionOutside/command
digitalstrom/devices/DEVICE_NAME/shadeOpeningAngleOutside/state
digitalstrom/devices/DEVICE_NAME/shadeOpeningAngleOutside/command
```

### dSS20 (controllers)

```
digitalstrom/meterings/chambres/consumptionW/state
digitalstrom/meterings/chambres/energyWs/state
```

### dS-Weather

The dSS apartment status exposes weather measurements as one apartment-wide source, including when multiple weather stations are configured.

```
digitalstrom/weather_station_sensors/ds_weather/temperature/state
digitalstrom/weather_station_sensors/ds_weather/illuminance/state
digitalstrom/weather_station_sensors/ds_weather/wind_speed_10min_average/state
digitalstrom/weather_station_sensors/ds_weather/wind_gust/state
digitalstrom/weather_station_sensors/ds_weather/rain/state
```

## Tested devices

digitalSTROM-MQTT was tested successfully with these devices:

* dSM12
* dSS20
* GE-KM200
* GE-TKM210
* GE-UMV200 (see [#22](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/22))
* GE-KL200 (see [#23](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/23))
* SW-TKM200
* SW-TKM210
* GR-KL200
* GR-KL210
* GR-KL220
* GN-KM200 (see [#21](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/21))
* dS-Weather (tested with the Theben version)

Some devices are known to have issues or limitations:

* BL-KM300 (
  see [#7](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/7) [#19](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/19))

Feel free to create an issue or to directly edit this file if you have tested this software with your devices.

## Development

See [CONTRIBUTION.md](./CONTRIBUTION.md)

## Contributors

digitalstrom-mqtt

digitalstrom-mqtt 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

digitalstrom-mqtt

digitalstrom-mqtt 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README