Project

General

Profile

Modules ยป

XML-RPC Server

DomotiGa has a minimal XML-RPC server included. The implemented methods are described below. They are used by various web clients, and the DomotiGa GUI in client mode.

No new methods will be added to the The XML-RPC server
It is highly recommended to use the JSON-RPC server instead

Porting

The xml-rpc is just too inflexible, so work is underway to port things to JSON-RPC. Only the following "apps" is still using XML-RPC and is planned to be moved to JSON-RPC.

List of currently implemented methods.

$ xmlrpc localhost:9009 system.listMethods
Result:

Array of 84 items:
  Index  0 String: 'system.listMethods'
  Index  1 String: 'system.methodHelp'
  Index  2 String: 'system.methodSignature'
  Index  3 String: 'system.program_uptime'
  Index  4 String: 'system.program_version'
  Index  5 String: 'system.hostname'
  Index  6 String: 'system.pid'
  Index  7 String: 'api.version'
  Index  8 String: 'data.newmessages'
  Index  9 String: 'data.sunmoon'
  Index 10 String: 'mode.get_housemode'
  Index 11 String: 'mode.get_mutemode'
  Index 12 String: 'set.housemode'
  Index 13 String: 'set.mutemode'
  Index 14 String: 'globalvar.list'
  Index 15 String: 'globalvar.save'
  Index 16 String: 'globalvar.get'
  Index 17 String: 'globalvar.set'
  Index 18 String: 'globalvar.del'
  Index 19 String: 'device.list'
  Index 20 String: 'device.listswitch'
  Index 21 String: 'device.listdim'
  Index 22 String: 'device.setdevice'
  Index 23 String: 'device.updatedevice'
  Index 24 String: 'device.getstate'
  Index 25 String: 'location.list'
  Index 26 String: 'send.email'
  Index 27 String: 'send.tweet'
  Index 28 String: 'send.sms'
  Index 29 String: 'set.alarmpin'
  Index 30 String: 'set.alarmmode'
  Index 31 String: 'module.restart'
  Index 32 String: 'play.sound'
  Index 33 String: 'voicetext.speak'
  Index 34 String: 'display.ledmessage'
  Index 35 String: 'pachube.list'
  Index 36 String: 'serverstats.updategraphs'
  Index 37 String: 'rrdtool.createrrds'
  Index 38 String: 'rrdtool.listgraphs'
  Index 39 String: 'rrdtool.updategraphs'
  Index 40 String: 'rrdtool.updategraph'
  Index 41 String: 'av.setcontrol'
  Index 42 String: 'av.getcontrol'
  Index 43 String: 'squeezebox.setvolumeplayer'
  Index 44 String: 'squeezebox.getvolumeplayer'
  Index 45 String: 'squeezebox.stopplayer'
  Index 46 String: 'squeezebox.playplayer'
  Index 47 String: 'squeezebox.nextnumberplayer'
  Index 48 String: 'squeezebox.prevnumberplayer'
  Index 49 String: 'squeezebox.getcurrentnumberplayer'
  Index 50 String: 'squeezebox.getalbums'
  Index 51 String: 'squeezebox.getmodeplayer'
  Index 52 String: 'squeezebox.getplayerid'
  Index 53 String: 'squeezebox.getplayername'
  Index 54 String: 'squeezebox.getisplayer'
  Index 55 String: 'squeezebox.clearplaylistplayer'
  Index 56 String: 'squeezebox.addalbumtoplaylistplayer'
  Index 57 String: 'squeezebox.getcurrentartistplayer'
  Index 58 String: 'squeezebox.getplayerisconnectedtoserver'
  Index 59 String: 'zwave.removenodes'
  Index 60 String: 'zwave.createnode'
  Index 61 String: 'zwave.setids'
  Index 62 String: 'zwave.setvalue'
  Index 63 String: 'zwave.allqueried'
  Index 64 String: 'zwave.removenode'
  Index 65 String: 'razberry.updatesready'
  Index 66 String: 'cmdr.culsimulate'
  Index 67 String: 'cmdr.culqueuecommand'
  Index 68 String: 'cmdr.plcbustxcommand'
  Index 69 String: 'thermostat.listscenario'
  Index 70 String: 'thermostat.getscenario'
  Index 71 String: 'thermostat.getscenarios'
  Index 72 String: 'thermostat.getheating'
  Index 73 String: 'thermostat.setscenario'
  Index 74 String: 'thermostat.createheating'
  Index 75 String: 'thermostat.derogateheating'
  Index 76 String: 'thermostat.getderogateheating'
  Index 77 String: 'thermostat.setsecondary'
  Index 78 String: 'events.list'
  Index 79 String: 'events.runactions'
  Index 80 String: 'events.runaction'
  Index 81 String: 'events.changestate'
  Index 82 String: 'calendar.setplanning'
  Index 83 String: 'calendar.getplanning'

DomotiGa XML-RPC API Documentation

V0.19 Changes

The following XML-RPC calls are deprecated and should not be used:
globalvar.save - DomotiGa automatic saves the globalvar into the DB
zwave.removenodes - The domozwave wrapper uses JSON-RPC now
zwave.createnode - The domozwave wrapper uses JSON-RPC now
zwave.setids - The domozwave wrapper uses JSON-RPC now
zwave.setvalue - The domozwave wrapper uses JSON-RPC now
zwave.allqueried - The domozwave wrapper uses JSON-RPC now
zwave.removenode - The domozwave wrapper uses JSON-RPC now

V0.18 Changes

razberry.updatesready
trigger from z-way-server that updates are ready to be fetched. Should not be used by another application
param: null

V0.17 Changes

location.list
returns all defined locations
param: null

rrdtool.updategraph
update rrdtool graph images for device with id param1 and range param2 (1h, 2h, ...)

events.list
returns a list of known events with their values
param: null

events.runactions
run all actions from event with id param1
param1 is now a string instead of integer (V0.12)

events.changestate
enable/disable event named param1 with state param2 (True/False)

thermostat.createheating
update or create a heating
name = param1, sensor = param2, device= param3, deviceInverted=param4, deviceLatency=param5, regulator=param6, regulatorInverted=param7
description=param8, deviceOffsetTop=param9, regulatorOffsetTop=param10, deviceOffsetBottom=param11, regulatorOffsetBottom=param12"

thermostat.getheating
returns heatings from scenario with id param1

thermostat.getscenarios
returns all scenarios and their heatings
param: null

V0.16 Changes

serverstats.updategraphs
update serverstats graph images for range param1

V0.15 Changes

squeezebox.setvolumeplayer
set volume param2 for player with id param1

squeezebox.getvolumeplayer
get volume from player with id param1

squeezebox.stopplayer
stop player with id param1

squeezebox.playplayer
start player with id param1

squeezebox.nextnumberplayer
play next number on player with id param1

squeezebox.prevnumberplayer
play previous number on player with id param1

squeezebox.getcurrentnumberplayer
get current number from player with id param1

squeezebox.getalbums
get albums from squeezeserver

squeezebox.getmodeplayer
get mode player from player with id param1

squeezebox.getplayerid
get player id for player param1

squeezebox.getplayername
get player name for player param1

squeezebox.getisplayer
get player type from player with id param1

squeezebox.clearplaylistplayer
clear playlist player for player with id param1

squeezebox.addalbumtoplaylistplayer
add album param2 to playlist for player with id param1

squeezebox.getcurrentartistplayer
get current artist for player with id param1

squeezebox.getplayerisconnectedtoserver
is player with id param1 connected to server

V0.14 Changes

calendar.setplanning
set occupancy planning

calendar.getplanning
get occupancy planning

V0.13 Changes

zwave.basicreport
this method doesn't exist anymore and is renamed to zwave.setvalue

zwave.setvalue
set zwave device value, param1 = homeid, param2 nodeid, param3 = instanceid, param4 = value_no, param5 = value

device.getstate
returns device state (same as Value1 like On/Off/Dim xx/Temp etc) of device with name in param1

V0.12 Changes

events.runactions
run all actions from event with id param1

events.runaction
run action with id param1

V0.11 Changes

Added methods for thermostat functions.

thermostat.listscenario
thermostat list all scenarios.

thermostat.getscenario
thermostat get active scenario.

thermostat.setscenario
thermostat set scenario param1.

thermostat.derogateheating
thermostat increase or decrease 0.5 degrees requested temperature for a heating scenario, param1 = scenarioId, param2 = heatingId, param3 = + or - symbol.

V0.10 Changes

globalvar.del
delete global variable param1.

V0.09 Changes

cmdr.culsimulate
cmdr inject cul packet in simulator.

cmdr.culqueuecommand
cmdr queue cul command.

cmdr.plcbustxcommand
cmdr plcbus queue command.

V0.08 Changes

Added methods for open-zwave wrapper.

zwave.removenodes
zwave - remove all nodes

zwave.createnode
zwave - create node.

zwave.setids
zwave - set ids.

zwave.basicreport
see zwave.basicreport in 0.13 changes

zwave.allqueried
zwave - all queried.

V0.07 Changes

rrdtool.createrrds
create rrdtool database for device id param1

V0.06 Changes

av.setcontrol
set audio/video param1 with command param2, value param3, address param4

av.getcontrol
get audio/video param1 setting param2, address param3

V0.05 Changes

display.ledmessage
display message param2 on display with id param1

V0.04 Changes

rrdtool.listgraphs
get list of rrdtool graph images in group param1

rrdtool.updategraphs
update rrdtool graph images in group param1 for range param2

V0.03 Changes

Added:

module.restart
reload config and restart module modulename
param: modulename (string)

Returns TRUE or FALSE.

Example response:

<methodResponse> 
<params> 
<param> 
<value><boolean>TRUE</boolean></value> 
</param> 
</params> 
</methodResponse>

send.email
send e-mail to address param1, with subject param2 and body param3

Returns TRUE or FALSE.

Example response:

<methodResponse> 
<params> 
<param> 
<value><boolean>TRUE</boolean></value> 
</param> 
</params> 
</methodResponse>

send.tweet
send tweet with param1 as contents

send.sms
send sms to param1, with param2 as contents

set.housemode
set house mode to param1

set.mutemode
set mute mode to param1

device.setdevice
"set device param1 with value param2

set.alarmpin
set alarm pin to param1

set.alarmmode
set alarm mode to param1

play.sound
play sound param1 with volume param2

voicetext.speak
speak text param1 with voice param2

pachube.list
get pachube device list in eeml

V0.02 Changes

Added:

system.program_uptime
returns the program uptime
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><string>6 days, 12 hrs, 1 min, and 28 secs.</string></value> 
</param> 
</params> 
</methodResponse>

V0.01

Method Description

system.listMethods
returns list of methods.
param: none

Example response:

<methodResponse> 
<params> 
<param> 
<value><array> 
<data> 
<value><string>system.listMethods</string></value> 
<value><string>system.methodHelp</string></value> 
<value><string>system.methodSignature</string></value> 
<value><string>system.program_version</string></value> 
<value><string>system.pid</string></value> 
<value><string>system.hostname</string></value> 
<value><string>data.newmessages</string></value> 
<value><string>data.sunmoon</string></value> 
<value><string>mode.get_housemode</string></value> 
<value><string>mode.get_mutemode</string></value> 
<value><string>globalvar.list</string></value> 
<value><string>device.list</string></value> 
<value><string>device.listswitch</string></value> 
<value><string>device.listdim</string></value> 
</data> 
</array></value> 
</param> 
</params> 
</methodResponse>

system.methodHelp
returns help for method.
param: method (string)

system.methodSignature
no function

system.program_version
returns version of domotiga
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><string>0.1.163</string></value> 
</param> 
</params> 
</methodResponse>

system.pid
returns process id of domotiga
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><string>6876</string></value> 
</param> 
</params> 
</methodResponse>

system.hostname
returns hostname of domotiga server
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><string>server</string></value> 
</param> 
</params> 
</methodResponse>

api.version
returns version of api
param: null

Example response:

<methodResponse>
<params> 
<param> 
<value><string>0.01</string></value> 
</param> 
</params> 
</methodResponse>

data.newmessages
returns new mails, calls and voicemails
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><array> 
<data> 
<value><string>0</string></value> 
<value><string>0</string></value> 
<value><string>0</string></value> 
</data> 
</array></value> 
</param> 
</params> 
</methodResponse>

data.sunmoon
returns sun and moon data
param:null

Note: currently only reports sunrise and sunset

Example response:

<methodResponse> 
<params> 
<param> 
<value><array> 
<data> 
<value><string>6:49</string></value> 
<value><string>18:50</string></value> 
</data> 
</array></value> 
</param> 
</params> 
</methodResponse>

mode.get_housemode
returns the house mode
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><string>vacation</string></value> 
</param> 
</params> 
</methodResponse>

mode.get_mutemode
returns the mute mode
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><boolean>1</boolean></value> 
</param> 
</params> 
</methodResponse>

globalvar.list
returns a list of global variables
param: null

Example response:

<methodResponse> 
<params> 
<param> 
<value><array> 
<data> 
<value><string>Second</string></value> 
<value><string>Minute</string></value> 
<value><string>Hour</string></value> 
<value><string>Day</string></value> 
<value><string>Month</string></value> 
<value><string>Weekday</string></value> 
<value><string>Time_Of_Day</string></value> 
<value><string>Year</string></value> 
<value><string>Sunrise</string></value> 
<value><string>Sunset</string></value> 
<value><string>Sunrise_Twilight</string></value> 
<value><string>Sunset_Twilight</string></value> 
<value><string>Season</string></value> 
<value><string>House_Mode</string></value> 
<value><string>Mode_Set</string></value> 
<value><string>Last_User</string></value> 
<value><string>Mute</string></value> 
<value><string>Dark</string></value> 
<value><string>Weekend</string></value> 
</data> 
</array></value> 
</param> 
</params> 
</methodResponse>

device.list
returns a list of devices
param: null

Only devices which are enabled and have hide flag unset are displayed.
Returns select set of their fields.
Format is a struct with a string for each device, fields are separated with ';;'

Fields are returned in this order:

Device id
Icon (with current status)
Name
Location
Value1
Label1
Value2
Label2
Value3
Label3
Value4
Label4
Last seen

Example response:

<methodResponse> 
<params> 
<param> 
<value><struct> 
<member><name>Porch Light</name> 
<value><string>1;;light-off.png;;Porch Light;;Frontdoor;;Off;;;;;;;;;;;;;;;;13:05:40</string></value> 
</member> 
<member><name>Power Usage</name> 
<value><string>2;;energy.png;;Power Usage;;MeterCabinet;;5145563;;kWh;;120;;Watt;;;;;;;;;;15:22:27</string></value> 
</member> 
<member><name>Laundryroom Light</name> 
<value><string>3;;light-off.png;;Laundryroom Light;;Laundryroom;;Off;;;;;;;;;;;;;;;;2008-10-16 20:04:51</string></value> 
</member> 
</struct></value> 
</param> 
</params> 
</methodResponse>

device.listswitch
returns a list of devices which can be switched
param: null

Returns select set of values, will change for sure in the future!
Format is a struct with a string for each device, fields separated with ';;'

Fields are returned in this order:

Device id
Icon (with current status)
Name
Value1

Example response:

<methodResponse> 
<params> 
<param> 
<value><struct> 
<member><name>Porch Light</name> 
<value><string>1;;light-off.png;;Porch Light;;Off</string></value> 
</member> 
<member><name>DomotiGa Server</name> 
<value><string>34;;light-on.png;;DomotiGa Server;;On</string></value> 
</member> 
<member><name>Close-in Boiler</name> 
<value><string>35;;light-on.png;;Close-in Boiler;;On</string></value> 
</member> 
</struct></value> 
</param> 
</params> 
</methodResponse>

device.listdim
returns a list of devices which can be dimmed
param: null

Same as device.listswitch response.

Debugging XML-RPC

If the XMLRPC communication doesn't work make sure the server is listening on the XMLRPC port for commands (default is 9009)

$ netstat -an | grep 9009
tcp        0      0 0.0.0.0:9009            0.0.0.0:*               LISTEN

Also make sure that the client is configured to connect with the correct server ip address and port, check it's startup log.

2013/05/25 10:36:24 The XMLRPC server URL is 'http://localhost:9009/'

You can find these settings in the client under menu Setup => Client => GUI
If you have two separate systems you have to specify the ip address of the server machine here instead of localhost.

When it seems to run ok, check with a cli command if you get the correct response from the XMLRPC server. Install the command if needed.

$ xmlrpc
The program 'xmlrpc' is currently not installed. You can install it by typing:
sudo apt-get install libxmlrpc-core-c3-dev

Now check with this command to see if you get a list of implemented methods.
Replace 'localhost' with the ip address of the server if run from another system.

$ xmlrpc localhost:9009 system.listMethods
Result:

Array of 84 items:
  Index  0 String: 'system.listMethods'
  Index  1 String: 'system.methodHelp'
  Index  2 String: 'system.methodSignature'
  Index  3 String: 'system.program_uptime'
  Index  4 String: 'system.program_version'
  ...
  Index 83 String: 'calendar.getplanning'

Possible other responses:

Failed.  Call failed.  libcurl failed to execute the HTTP POST transaction, explaining:  Failed connect to localhost:9009; Connection refused.  (XML-RPC fault code -504)

Server is not running on system and port specified.

Failed.  Call failed.  RPC failed at server.  Unknown method.  (XML-RPC fault code 2)

The specified method is not known/implemented.

XML-RPC responses can also be debugged with the xml-rpc php debugger found here:
http://gggeek.raprap.it/debugger/
Download and use it in your on lan, because the public version will log the traffic.

Related Resources

    Updated by: Alexie, Updated over 4 years ago
    Access count: 75055 since 2011-08-25

    Attached Files

    Also available in: PDF HTML TXT