DSS Scripting: Getting Started¶

The dSS can be extended by means of JavaScript scripts that are executed within the dSS. There's some theory on this on Scripting inside the dSS.

Preparation¶

In order to have some code called from the dSS; we need to register it via data/subscription.xml. Modify your data/subscription.xml to include the subscription XML node as shown here:

<?xml version="1.0"?>
<subscriptions version="1">
...
  <subscription event-name="callScene" handler-name="javascript">
    <parameter>
      <parameter name="filename">data/example.js</parameter>
    </parameter>    
    <filter match="all">
      <property-filter type="matches" value="0" property="zoneID" />
    </filter>
  </subscription>
...
</subscription>

This fragment registers the example.js script for all callScene events sent to zone ID 0. We could filter by means of sceneID/groupID in the very same way.

Step 1: Hello world¶

Next up, create a file called example.js in the data directory, with the following line:

print("Hello, digitalSTROM world!");

After that, start the dSS which will register the subscription on startup. In order to trigger a callScene call, run the ds3 shell script from the tools directory, like this:

$ ./ds3 apartment callScene 5 1

This will tranform into a callScene call with zoneID = 0, sceneID = 5, groupID = 1

When you watch the output of the dSS, you should now see the following (date/time will of course be different):

[2010-03-10 14:59:29][Debug] [Apartment] OnGroupCallScene: group-id '1' in Zone '0' scene: 5
[2010-03-10 14:59:29][Info] EventInterpreter: Got event from queue: 'callScene'
[2010-03-10 14:59:29][Debug] EventInterpreter:  Parameter 'zoneID' = '0'
[2010-03-10 14:59:29][Debug] EventInterpreter:  Parameter 'groupID' = '1'
[2010-03-10 14:59:29][Debug] EventInterpreter:  Parameter 'sceneID' = '5'
[2010-03-10 14:59:29][Debug] EventInterpreter: Subscription 'callScene_javascript' matches event
[2010-03-10 14:59:29][Debug] EventInterpreter: Found handler 'javascript' calling...
[2010-03-10 14:59:29][Debug] EventInterpreterPluginJavascript::handleEvent: setting parameter zoneID to 0
[2010-03-10 14:59:29][Debug] EventInterpreterPluginJavascript::handleEvent: setting parameter groupID to 1
[2010-03-10 14:59:29][Debug] EventInterpreterPluginJavascript::handleEvent: setting parameter sceneID to 5
[2010-03-10 14:59:29][Debug] JS: Hello, digitalSTROM world!
[2010-03-10 14:59:29][Debug] EventInterpreter: called.
[2010-03-10 14:59:29][Info] EventInterpreter: Done processing event 'callScene'

The most interesting line is the third to last line, where we see the "Hello, digitalSTROM world!" message. If you see this, you've successfully ran javascript code within the dSS!

Step 2: Getting some basic information on the event¶

Now, printing a "Hello, world" message is not too interesting, so let's print some information on the event which triggered us. To do so, visit Scripting inside the dSS where you'll see the event parameters that are available. From this, we derive the following printouts which seem interesting (just append them to data/example.js:

print("  event name:        ", raisedEvent.name);
print("  parameter zoneID:  ", raisedEvent.parameter.zoneID);
print("  parameter groupID: ", raisedEvent.parameter.groupID);
print("  parameter sceneID: ", raisedEvent.parameter.sceneID);

Obviously, just printing them is not too interesting, however these can of course be used in any logic you'd like to implement in your dSS server scripts.

Note: It's not needed to restart the dSS when a script is modified. Just save the new content on run the ds3 call as in step 1.

Step 3: Listing device information¶

A more practical example would be to iterate over all devices attached to the dSS. On Scripting inside the dSS, we see that there's a getDevices() method which sounds rather interesting. Since this returns a Set of devices, let's have a look at the Set methods to find that there's a perform() method that runs another JavaScript function for each device. Combining these two, we can write the following code to list all devices' DSIDs and function IDs:

var devices = getDevices();
print("  devices: [dsid -> functionID]");
devices.perform(function (device) {
                  print("    ", device.dsid, " -> ", device.functionID);
                });

When triggered (again, just use ds3 to trigger the callScene event) you should see a list of DSIDs and function IDs of all attached devices.

Step 4: A practical example¶

In this example, we call a device method with the sceneID as parameter to a subset of the devices, filtered by an imaginary function ID:

var dsLinkDevices = getDevices().byFunctionID(0xCAFE);
dsLinkDevices.perform(function (device) {
                        device.turnOn();
                      });