openhab-docs/_addons_bindings/digitalstrom1

id	label	title	type	description	source	since	logo	install
digitalstrom	digitalSTROM	digitalSTROM - Bindings	binding	The openHAB digitalSTROM binding allows interaction with digitalSTROM devices.	https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.digitalstrom/README.md	1x	images/addons/digitalstrom.png	manual

{% include base.html %}

digitalSTROM Binding

The openHAB digitalSTROM binding allows interaction with digitalSTROM devices.

• Prerequisites
• Binding Configuration
• Item Configuration
• Examples
• Notes

There is also a binding specifically for openHAB 2 here.

Prerequisites

digitalSTROM server add-on

• Unzip 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

2. chmod 400 privkey.pem

3. 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

4. openssl x509 -req -days 9000 -in certreq.csr -signkey privkey.pem -out dsscert.pem

5. 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 (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!