Merge pull request #45 from gaetancollaud/feature/new-digitalstrom-api

Version 2.0 with new DigitalSTROM API

.github/workflows/build.yml

@@ -1,13 +1,13 @@
 name: Golang CI
 
-on: [ push, pull_request ]
+on: [push, pull_request]
 
 jobs:
   build:
     strategy:
       matrix:
-        go-version: [ 1.16.x ]
-        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        go-version: [1.18.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     env:
       GOPATH: ${{ github.workspace }}
@@ -32,3 +32,5 @@ jobs:
           path: ${{ env.GOPATH }}/src/github.com/${{ github.repository }}
       - name: Build
         run: go build -o dist/digitalstrom-mqtt-${{matrix.os}} ./main.go
+      - name: Test
+        run: go test -v ./...

.github/workflows/release.yml

@@ -3,25 +3,22 @@ name: Release
 on:
   push:
     tags:
-      - '*'
+      - "*"
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      -
-        name: Login to Docker Registry
+      - name: Login to Docker Registry
         run: |
           echo "${{ secrets.DOCKERHUB_TOKEN }}" | \
           docker login  -u gaetancollaud --password-stdin \
           && docker info
-      -
-        name: Checkout
+      - name: Checkout
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
-      -
-        name: Set up Go
+      - name: Set up Go
         uses: actions/setup-go@v2
         with:
           go-version: 1.19

.gitignore

@@ -3,5 +3,9 @@ vendor/
 dist/
 tests/
 
+digitalstrom-mqtt
+
+docs/docker/homeassistant
 .env
-config.yaml
+/config.yaml
+*.private.env.json

README.md

@@ -6,19 +6,24 @@ You can set the output values using the command topic and get the current value
 
 ![](./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, but it’s not that easy to use since there are a lot of different concepts (scenes,
-groups, areas, …). There is also an event endpoint, so you can react to some events. Unfortunately it’s pretty limited (
-for example you don’t have an event when a device output is changed).
+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.
+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
 
@@ -30,46 +35,65 @@ it.
 
 ### Technical
 
-This app use the `json/device/` api to set the values, `json/property` to get the cached output value (digitalSTROM
-takes 1-2s per call if you ask the actual value from the device) and `json/event/` to be notified when a scene change.
-
-Since we don’t have an event when an output value changes we have to work around this limitation. Any push of a button (
-for example) will trigger a scene. DigitalSTROM provides an event when a scene is called. We can then get the state of
-the devices in this scene. This overfetch a bit too much data (since we ask for all devices in a zone) but narrows the
-update state request, so we don’t have to ask for all the devices in the system.
+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, so I had to browser various forum and discussion groups to
+find all the relevant information.
 
 ## 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_USERNAME | Username for digitalstrom | | dssadmin |
-| * | DIGITALSTROM_PASSWORD | Password for digitalstrom | | 9TyVg74e5S |
-| * | 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 | false | |
-|   | 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 |  |
-|   | HOME_ASSISTANT_DISCOVERY_ENABLED | Whether or not publish MQTT Discovery messages for Home Assistant | false | |
-|   | 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)"`
+| 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           |                             |
+|          | 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)"`          
+
+## 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_USERNAME: dssadmin
-DIGITALSTROM_PASSWORD: XXX
+DIGITALSTROM_API_KEY: XXX
 MQTT_URL: tcp://192.168.1.X:1883
 ```
 
@@ -79,27 +103,13 @@ The topic format is as follows for the devices:
 
 `{prefix}/devices/{deviceName}/{channel}/{commandState}`
 
-The topic format is as follows for the circuits:
-
-`{prefix}/circuits/{deviceName}/{channel}/state`
+The topic format is as follows for the meterings:
 
-The topic format is as follows for the scenes:
-
-`{prefix}/scenes/{zoneName}/{sceneName}/event`
+`{prefix}/meterings/{deviceName}/{channel}/state`
 
 The server status topic is
 
-`{prefix}/server/state`
-
-| variable | description | example |
-| --- | --- | --- |
-| {prefix} |  | Defined by `MQTT_TOPIC_PREFIX` |
-| {deviceType} |  | `circuit` or `device` |
-| {deviceName} | Device or Circuit name | `light_bathroom` |
-| {channel} | DS channel |  |
-| {commandState} |  | `command` or `state` |
-| {zoneName} | Zone name | `bathroom` |
-| {sceneName} | Scene name | `double_press` |
+`{prefix}/server/status`
 
 ## How to run
 
@@ -119,8 +129,7 @@ Start the executable
 ```shell
 docker run \
   -e DIGITALSTROM_HOST=192.168.1.x \
-  -e DIGITALSTROM_USERNAME=dssadmin \
-  -e DIGITALSTROM_PASSWORD=XXX \
+  -e DIGITALSTROM_API_KEY=XXX \
   -e MQTT_URL=tcp://192.168.1.X:1883 \
   gaetancollaud/digitalstrom-mqtt
 ```
@@ -152,11 +161,11 @@ digitalstrom/devices/DEVICE_NAME/shadeOpeningAngleOutside/state
 digitalstrom/devices/DEVICE_NAME/shadeOpeningAngleOutside/command
 ```
 
-### dSS20 (circuits)
+### dSS20 (controllers)
 
 ```
-digitalstrom/circuits/chambres/consumptionW/state
-digitalstrom/circuits/chambres/EnergyWs/state
+digitalstrom/meterings/chambres/consumptionW/state
+digitalstrom/meterings/chambres/energyWs/state
 ```
 
 ## Tested devices
@@ -178,7 +187,8 @@ digitalSTROM-MQTT was tested successfully with these devices:
 
 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))
+* BL-KM300 (
+  see [#7](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/7) [#19](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/19))
 * GE-UMv200 (see [#22](https://github.com/gaetancollaud/digitalstrom-mqtt/issues/22))
 
 Feel free to create an issue or to directly edit this file if you have tested this software with your devices.

config.yaml.example

@@ -1,5 +1,4 @@
-DIGITALSTROM_HOST: 192.168.1.X
-DIGITALSTROM_USERNAME: dssadmin
-DIGITALSTROM_PASSWORD: XXX
-MQTT_URL: tcp://192.168.1.X:1883
-REFRESH_AT_START: false
+digitalstrom_host: 192.168.1.X
+digitalstrom_api_key: XXX
+mqtt_url: tcp://192.168.1.X:1883
+refresh_at_start: false