digitalSTROM Binding

Documentation of the digitalSTROM binding bundle

Introduction

digitalSTROM binding bundle is available as a separate (optional) download. If you want to let openHAB communicate with digitalSTROM DSS11 server, please place this bundle in the folder ${openhab_home}/addons and add binding information to your configuration.

For installation of the binding, please see Wiki page Bindings.

Preliminaries

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

DigitalSTROM JSON service interface is limited to HTTPS protocol. For security reason, we need to create a self signed cetificate with correct given hostname. To do so, 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

digitalSTROM Binding Configuration

openhab.cfg

The following config params are used for the digitalSTROM binding.

• (optional) digitalstrom:refreshinterval Refresh interval (defaults to 1000 ms)
• digitalstrom:uri Hostname / IP address and port of the digitalSTROM server (dSS)
• (optional) digitalstrom:connectTimeout Connect timeout (defaults to 4000 ms)
• (optional) digitalstrom:readTimeout Connect timeout (defaults to 10000 ms)
• digitalstrom:loginToken To login without a user and password; loginToken must be enabled once
• digitalstrom:user
• digitalstrom:password To login with username and password; default username and password is dssadmin If you have loginToken and username with password the loginToken will be prefered by default

Obtaining 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

Example

################################ digitalSTROM Binding #################################

# Refresh interval (defaults to 1000 ms)
digitalstrom:refreshinterval=1000

# Hostname / IP address and port of the digitalSTROM server (dSS)
digitalstrom:uri=https://dss.local:8080

# Connect timeout (defaults to 4000 ms)
digitalstrom:connectTimeout=4000

# Connect timeout (defaults to 10000 ms)
digitalstrom:readTimeout=10000

# to login without a user and password; loginToken must be enabled once
digitalstrom:loginToken=

# to login with username and password; default user is dssadmin and default password is dssadmin
# if you have loginToken and username with password the loginToken will be prefered by default
digitalstrom:user=dssadmin
digitalstrom:password=dssadmin

Generic Item Binding Configuration

Syntax

In order to bind an item to a digitalSTROM device you need to provide configuration settings. The simplest way is:

digitalstrom="dsid:<digitalSTROM device id>" //device with example dsid (You can also use the shorter dsid, known as S.N: xxxxxxxx (8 letters) )

Thats it! It's enough to control a device.

Example

Switch Light_GF_Corridor_Ceiling    "Ceiling"       {digitalstrom="dsid:3504175fe000000000000001"}
Dimmer Light_GF_Living_Table        "Table"         {digitalstrom="dsid:3504175fe000000000000001"}

Rollershutter Shutter_GF_Living     "Livingroom"    {digitalstrom="dsid:3504175fe000000000000001"}

All syntax keywords for the digitalSTROM are explained here:

symbols:	
    :               // to refer a value to a key
    #               // separator for the next key-value pair

keys:	
    dsid            // digitalSTROM device id
    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

context:
    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 Number- or StringItem to make apartment calls
    zone            // in combination with a Number- or StringItem to make zone calls

consumption:	
    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)

Further examples

Rollershutter

Rollershutter Shutter_GF_Living     "Livingroom"    {digitalstrom="dsid:3504175fe000000000000001"}

in case of marquee/awning add context param "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 second item to adjuste the slats (use the same dsid)

Rollershutter Shutter_GF_Living_UP_DOWN     "Livingroom UP/DOWN"    {digitalstrom="dsid:3504175fe000000000000001#context:slat"}

Scenes

To call apartment or zone scenes use number- or string item in the .items file:

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 in .sitemap add mappings: Selection item=Apartment_Scene label="Apartment Scene Selection" mappings=[65=Panik, 72=Gehen] // here you have to use the right (a valid) sceneID

Switch item=Zone_Scene          label="Room Scene"                  mappings=[14=On, 13=Off]        // here you have to use the right (a valid) sceneID

Consumption

To poll and e.g. persist/visualize the curent power consumption (ACTIVE_POWER) you should use string- or number items.

= 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! Your system will work very slow on sensor reading!

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."(digitalSTROM: [p.36)

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."(digitalSTROM: http://developer.digitalstrom.org/Architecture/ds-basics.pdf p.36)

= 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 meterenig/consumption note =

• The timeinterval only initiates a metering job, but you don't have the guarantee that the worker will start it in this time!

• You should better not read the consumption of a device, but of meters(dSMs).

= Other important note =

In the first time the system learns, how to react on specific scene calls (sensor reading). But after some time it will work fast!