217 lines
9.3 KiB
Markdown
217 lines
9.3 KiB
Markdown
---
|
|
id: digitalstrom
|
|
label: digitalSTROM
|
|
title: digitalSTROM - Bindings
|
|
type: binding
|
|
description: "The openHAB digitalSTROM binding allows interaction with digitalSTROM devices."
|
|
source: https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.digitalstrom/README.md
|
|
since: 1x
|
|
logo: images/addons/digitalstrom.png
|
|
install: manual
|
|
---
|
|
|
|
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
|
|
|
|
{% include base.html %}
|
|
|
|
# digitalSTROM Binding
|
|
|
|
The openHAB digitalSTROM binding allows interaction with digitalSTROM devices.
|
|
|
|
<!-- MarkdownTOC depth=1 -->
|
|
|
|
- [Prerequisites](#prerequisites)
|
|
- [Binding Configuration](#binding-configuration)
|
|
- [Item Configuration](#item-configuration)
|
|
- [Examples](#examples)
|
|
- [Notes](#notes)
|
|
|
|
<!-- /MarkdownTOC -->
|
|
|
|
There is also a binding specifically for openHAB 2 [here](http://docs.openhab.org/addons/bindings/digitalstrom/readme.html).
|
|
|
|
|
|
## Prerequisites
|
|
|
|
### digitalSTROM server add-on
|
|
|
|
- Unzip [DigitalSTROM_OPENHAB_ADD-ON.zip](https://github.com/openhab/openhab/raw/master/bundles/binding/org.openhab.binding.digitalstrom/DigitalSTROM_OPENHAB_ADD-ON.zip)
|
|
- copy "openhab/openhab.js" to your dss server "/usr/share/dss/add-ons/"
|
|
- copy "openhab.xml" to your dss server "/usr/share/dss/data/subscriptions.d/"
|
|
|
|
### digitalSTROM server certificate
|
|
|
|
The digitalSTROM JSON service interface is limited to the https protocol.
|
|
For security reasons, creating a self signed cetificate with correct given hostname is requird.
|
|
Follow these steps:
|
|
|
|
1. openssl genrsa -out privkey.pem 1024
|
|
1. chmod 400 privkey.pem
|
|
1. openssl req -new -key privkey.pem -out certreq.csr
|
|
|
|
Enter your details:
|
|
|
|
Country Name (2 letter code) [AU]: DE // not important
|
|
|
|
State or Province Name (full name) [Some-State]: NRW // not important
|
|
|
|
Locality Name (eg, city) []: Gummersbach // not important
|
|
|
|
Organization Name (eg, company) [Internet Widgits Pty Ltd]: dss.local // network name of your dss, important
|
|
|
|
Organizational Unit Name (eg, section) []: dss.local // network name of your dss, important
|
|
|
|
Common Name (eg, YOUR name) []: dss.local // network name of your dss, important
|
|
|
|
Email Address []: // not important
|
|
|
|
Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: // not important, press enter
|
|
|
|
An optional company name []: // not important, press enter
|
|
|
|
1. openssl x509 -req -days 9000 -in certreq.csr -signkey privkey.pem -out dsscert.pem
|
|
1. cat privkey.pem >> dsscert.pem
|
|
|
|
Copy the newly generated certificate onto your digitalSTROM server and
|
|
import it to java trusted store of your openHAB server by using java keytool.
|
|
|
|
Keytool usage:
|
|
|
|
$JAVA_HOME/bin/keytool -importcert -alias <some descriptive name> -keystore <path to keystore> -file <certificate file>
|
|
|
|
Keytool usage example (OS X):
|
|
|
|
sudo keytool -importcert -alias DSS -keystore /System/Library/Java/Support/CoreDeploy.bundle/Contents/Home/lib/security/cacerts -file dss.local.pem
|
|
|
|
### loginToken
|
|
|
|
- To obtain a loginToken, point your browser to https://dss.local:8080/json/system/requestApplicationToken?applicationName=openHAB
|
|
- Store the result in openhab.cfg file
|
|
- After receiving the application token you need to enable it in your digitalSTROM configurator under System -> Zugriffsberechtigung
|
|
|
|
|
|
## Binding Configuration
|
|
|
|
The binding can be configured in the file `services/digitalstrom.cfg`.
|
|
|
|
| Property | Default | Required | Description |
|
|
|-----------------|---------|:--------:|-------------|
|
|
| uri | | Yes | The hostname and port of the digitalSTROM server (dSS); eg. https://dss.local:8080
|
|
| connectTimeout | 4000 | No | The connect timeout (in milliseconds)
|
|
| loginToken | | No | A token to allow login without a username and password; required if `user` and `password` settings are not specified
|
|
| password | dssadmin| No | The username to use for login; required if `loginToken` setting is not specified
|
|
| readTimeout | 10000 | No | The read timeout (in milliseconds)
|
|
| refreshinterval | 1000 | No | The refresh interval (in milliseconds)
|
|
| user | dssadmin| No | The password to use for login; required if `loginToken` setting is not specified
|
|
|
|
Note: if the `loginToken`, `user`, and `password` settings are all specified, the `loginToken` will be used for login.
|
|
|
|
## Item Configuration
|
|
|
|
Item bindings must conform to the following format:
|
|
|
|
digitalstrom="<key1>:<value1>[#<keyN>:<valueN>]"
|
|
|
|
See examples below.
|
|
|
|
The following keys are supported:
|
|
|
|
dsid // digitalSTROM device id; the shorter dsid, known as S.N: xxxxxxxx (8 letters), is also supported
|
|
dsmid // digitalSTROM meter id (dSM)
|
|
consumption // optional for metering
|
|
timeinterval // timeinterval to initiate a metering job
|
|
context // in some cases use context:
|
|
zoneid // only in combination with a NumberItem or StringItem for apartment or zone calls
|
|
groupid // only in combination with a NumberItem or StringItem for apartment or zone calls
|
|
|
|
The following are the supported values for the `consumption` key:
|
|
|
|
ACTIVE_POWER // in use with a device or meter -> current power consumption (w)
|
|
OUTPUT_CURRENT // only in use with a device -> amperage (mA)
|
|
ELECTRIC_METER // only in use with a meter (wh)
|
|
|
|
The following are the supported values for the `context` key:
|
|
|
|
slat // important if it's a roller shutter: to have a item to control the slats
|
|
awning // important for roller shutter: if it's a marquee/awning to show the right icon -> open-close
|
|
apartment // in combination with a NumberItem or StringItem to make apartment calls
|
|
zone // in combination with a NumberItem or StringItem to make zone calls
|
|
|
|
|
|
## Examples
|
|
|
|
### Items
|
|
|
|
Switch Light_GF_Corridor_Ceiling "Ceiling" {digitalstrom="dsid:3504175fe000000000000001"}
|
|
Dimmer Light_GF_Living_Table "Table" {digitalstrom="dsid:3504175fe000000000000001"}
|
|
|
|
### Rollershutter
|
|
|
|
Rollershutter Shutter_GF_Living "Livingroom" {digitalstrom="dsid:3504175fe000000000000001"}
|
|
|
|
In case of marquee/awning add the `context` key with a value of `awning`:
|
|
|
|
Rollershutter Shutter_GF_Living "Livingroom" {digitalstrom="dsid:3504175fe000000000000001#context:awning"}
|
|
|
|
### Jalousie
|
|
|
|
For up and down use:
|
|
|
|
Rollershutter Shutter_GF_Living_UP_DOWN "Livingroom UP/DOWN" {digitalstrom="dsid:3504175fe000000000000001"}
|
|
|
|
Add the `context` key with a value of `slat` to adjust the slats:
|
|
|
|
Rollershutter Shutter_GF_Living_UP_DOWN "Livingroom UP/DOWN" {digitalstrom="dsid:3504175fe000000000000001#context:slat"}
|
|
|
|
### Scenes
|
|
|
|
To call apartment or zone scenes use NumberItems or StringItems:
|
|
|
|
Number|String Apartment_Scene "Apartment Scene" {digitalstrom="context:apartment"}
|
|
Number|String All_Apartment_Lights "All lights" {digitalstrom="context:apartment#groupid:1"} //optional add groupid
|
|
|
|
Number|String Zone_Scene "Room Scene" {digitalstrom="context:zone#zoneid:65535"}
|
|
Number|String All_Zone_Lights "All room lights" {digitalstrom="context:zone#zoneid:65535#groupid:1"} //optional add groupid
|
|
|
|
And add mappings in the .sitemap file:
|
|
|
|
Selection item=Apartment_Scene label="Apartment Scene Selection" mappings=[65=Panik, 72=Gehen] // here you have to use a valid sceneID
|
|
Switch item=Zone_Scene label="Room Scene" mappings=[14=On, 13=Off] // here you have to use a valid sceneID
|
|
|
|
### Consumption
|
|
|
|
To poll and/or persist/visualize the curent power consumption (ACTIVE_POWER), use StringItems or NumberItems.
|
|
|
|
#### Device consumption
|
|
|
|
Number Power_Consumption_TV "TV [%d W]" {digitalstrom="dsid:3504175fe000000000000001#consumption:ACTIVE_POWER#timeinterval:60000"} // read device power consumption every 60 seconds
|
|
|
|
Be aware that the system will work very slow on sensor reading.
|
|
|
|
The [digitalSTROM Basic Concepts document](http://developer.digitalstrom.org/Architecture/ds-basics.pdf) (p. 36) says:
|
|
|
|
Rule 8 "Application processes that do automatic cyclic reads or writes of
|
|
device parameters are subject to a request limit: at maximum one request
|
|
per minute and circuit is allowed."
|
|
|
|
Rule 9 "Application processes that do automatic cyclic reads of measured
|
|
values are subject to a request limit: at maximum one request per minute
|
|
and circuit is allowed."
|
|
|
|
#### Circuit consumption
|
|
|
|
Number Consumption_dSM "dSM [%d W]" {digitalstrom="dsmid:3504175fe000001000000001#consumption:ACTIVE_POWER#timeinterval:3000"} // read power consumption every 3 seconds (it 'works' because here we read cached values)
|
|
|
|
#### Apartment consumption
|
|
|
|
Number Consumption_House "Total house consumption [%s W]" {digitalstrom="dsmid:ALL#consumption:ACTIVE_POWER#timeinterval:3000"}
|
|
|
|
#### General metering/consumption note
|
|
|
|
- The timeinterval only initiates a metering job; there is no guarantee that the worker will start it in this time!
|
|
- It is better to read the consumption of meters (dSMs) instead of devices.
|
|
|
|
## Notes
|
|
|
|
At first the system is slow while it learns how to react on specific scene calls (sensor reading). But after some time it will work fast!
|