Experimenting with the external device API

The external device API can be experimented easily with by connecting via telnet, then pasting an init message and then simulating some I/O.

The following paragraphs show this for different device types. Please also refer to the sample code in different languages contained in the external_devices_samples folder of the vdcd project.

Light button simulation

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) a simple init message defining a light button:

{'message':'init','protocol':'simple','uniqueid':'experiment42','buttons':[{'buttontype':1,'group':1,'element':0}]}

The vdcd responds with:

OK

Now, the vdcd has created a light button device. If this is the vdcd of a P44-DSB, you can see the device in the P44-DSB web interface, and if the vdcd is connected to a Digital Strom system, a new button device will appear in the dSS. By default, it will be in the default room for the "external devices" vdc, but you can drag it to an existing room with Digital Strom light devices.

Now you can switch lights by simulating a button click (250ms active) with

B0=250

For dimming, the button can be held down...

B0=1

...and later released

B0=0

Light dimmer simulation

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) a simple init message defining a dimmer output:

{'message':'init','protocol':'simple','uniqueid':'experiment42b','output':'light'}

The vdcd responds with:

OK

Now, the vdcd has created a light dimmer device. If this is the vdcd of a P44-DSB, you can see the device in the P44-DSB web interface, and if the vdcd is connected to a Digital Strom system, a new light device will appear in the dSS

Now you can call scenes in the room that contains the light device (or use the sprocket button in the P44-DSB web interface to directly change the brightness). You will see channel value changes reported from the external device API:

C0=3.120000
C0=8.190000
C0=14.040000
C0=21.840000
C0=30.810000
C0=40.950000
C0=56.160000
C0=63.960000
C0=69.810000
C0=78.000000
C0=79.950000
C0=78.000000
C0=65.130000
C0=53.040000
C0=42.120000
C0=33.150000
C0=26.910000
C0=40.950000
C0=53.040000
C0=58.110000
C0=63.180000

Temperature sensor simulation

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) a simple init message defining a temperature sensor:

{'message':'init','protocol':'simple','group':3,'uniqueid':'experiment42c','sensors':[{'sensortype':1,'usage':1,'group':48,'min':0,'max':40,'resolution':0.1}]}

The vdcd responds with:

OK

Now, the vdcd has created a temperature sensor device.

Now you can simulate temperature changes with

S0=22.5

e.g. to report a room temperature of 22.5 degree celsius.

A light dimmer and a button sharing one API connection

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) two init messages packaged into a JSON array, defining the dimmer and the button device:

[{'message':'init', 'tag':'DIMMER', 'protocol':'simple', 'group':3, 'uniqueid':'experiment42d', 'output':'light'}, {'message':'init', 'tag':'BUTTON', 'uniqueid':'experiment42e', 'buttons':[{'buttontype':1, 'group':1, 'element':0}]} ]

The vdcd responds with:

OK

Now simulate a button click (250ms active) with

BUTTON:B0=250

As both dimmer and button are initially in the same room, the button acting (by default) as a room button will switch on the light, so you will see:

DIMMER:C0=100.000000

A single device (simple kettle) with some actions, a state, some events and a property

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) two init messages packaged into a JSON array, defining the simple kettle single device:

{ 'message':'init', 'iconname':'kettle', 'modelname':'kettle', 'protocol':'json', 'uniqueid':'my-kettle', 'name':'virtual kettle', 'output':'action', 'noconfirmaction':true, 'actions': { 'stop':{'description':'stop heating'}, 'heat':{'description':'heat water','params': {'temperature': {'type':'numeric','siunit':'celsius','min':20,'max':100,'resolution':1,'default':100} } } }, 'states': { 'operation':{ 'type':'enumeration', 'values':['!ready','heating','detached'] } }, 'events': { 'started':null, 'stopped':null, 'aborted':null, 'removed':null }, 'properties':{ 'currentTemperature':{ 'readonly':true,'type':'numeric', 'siunit':'celsius', 'min':0, 'max':120, 'resolution':1 },'mode':{ 'type':'enumeration', 'values':['!normal','boost'] } }, 'autoaddstandardactions':true, 'standardactions':{ 'std.warmup':{ 'action':'heat', 'params':{ 'temperature':60 } } } }

The vdcd responds with:

{ "message":"status","status":"ok"}

Now simulate state changes with

{ "message":"pushNotification","statechange":{ "operation":"heating" }, "events":["started"] }

{ "message":"pushNotification","statechange":{ "operation":"detached" }, "events":["aborted","removed"] }

Or a temperature change with

{ "message":"updateProperty","property":"currentTemperature", "value":42, "push":true }

When an action is invoked on the device, you will see something like:

{"message":"invokeAction","action":"heat","params":{"temperature":42.420000}}

When a property is changed in the device:

{"message":"setProperty","property":"mode","value":"boost"}

Button device with three configurations to switch between

This is for a device with two buttons that can be used as either a two-way (rocker) button or as two separate single buttons.

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) a init message defining the button in the two-way configuration:

{'message':'init','protocol':'json','group':1,'uniqueid':'multiConfigSample','buttons':[{'buttontype':2,'hardwarename':'down','element':1}, {'buttontype':2,'hardwarename':'up','element':2}],'currentConfigId':'twoWay','configurations':[{'id':'twoWay','description':'two-way rocker button'},{'id':'oneWay', 'description':'separate buttons'},{'id':'twoWayInverse','description':'two-way rocker button, direction inversed'}]}

The vdcd responds with:

{"message":"status","status":"ok"}

Now, the vdcd has created a two-way button, offering three configurations: "twoWay" (currently active), "twoWayInverse" and "oneWay".

Now, when the user changes the configuration to "oneWay", the device will receive the following message:

{"message":"setConfiguration","id":"oneWay"}

Now, the device implementation must disconnect the current device, and re-connect two devices with same uniqueid, but different subdeviceindex representing the new one-way configuration:

{'message':'bye'}
[{'message':'init','tag':'A','protocol':'json','group':1,'uniqueid':'multiConfigSample','subdeviceindex':0,'buttons':[{'buttontype':1,'hardwarename':'single','element':0}],'currentConfigId':'oneWay','configurations':[{'id':'twoWay','description':'two-way rocker button'},{'id':'oneWay', 'description':'separate buttons'},{'id':'twoWayInverse','description':'two-way rocker button, direction inversed'}]},{'message':'init','tag':'B','protocol':'json','group':1,'uniqueid':'multiConfigSample','subdeviceindex':1, 'buttons':[{'buttontype':1,'hardwarename':'single','element':0}],'currentConfigId':'oneWay','configurations':[{'id':'twoWay','description':'two-way rocker button'},{'id':'oneWay', 'description':'separate buttons'},{'id':'twoWayInverse','description':'two-way rocker button, direction inversed'}]}]

Similarily, when the sure changes the configuration back to "twoWay" or "twoWayInverse", both single buttons must disconnect and a init message for a two-way button must be sent.

Note that this is even the case when switching between "twoWay" or "twoWayInverse" - although the number of virtual devices does not change, the configuration (button modes, ids, names) does, so the device must be disconnected and re-connected.

Two button devices that can be combined (at dSS/vdSM level) to act as a single two-way button

Connect to the device API with telnet:

telnet localhost 8999

Now copy and paste (single line!!) the following array containing two_init_ messages, defining two buttons which have consecutive subdeviceindex and combinables set to 2:

[{"message":"init","protocol":"simple","tag":"up","uniqueid":"p44_dummy_button_23465","subdeviceindex":0,"buttons":[{"buttontype":0,"combinables":2,"hardwarename":"up","element":0}]},{"message":"init","protocol":"simple","tag":"down","uniqueid":"p44_dummy_button_23465","subdeviceindex":1,"buttons":[{"buttontype":0,"combinables":2,"hardwarename":"down","element":0}]}]

The vdcd responds with:

OK

Now, the vdcd has created two button devices with consecutive subdevice indices (last byte of dSUID) 0 and 1.

From the external device API side, these work like any other button, see other example.

For the dSS configurator however, the combinables==2 means that these two buttons can be paired to appear as a single two-way in the dSS.