JSON-RPC

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

JSON-RPC is the protocol used between the DomotiGa client and server[*] so using JSON-RPC you should be able to do everything that is normally done through the client including retrieving device values and switching devices. Note that almost all configuration actions are not done through the JSON-RPC interface but using SQL on the database.

So to get the DomotiGa version:

$ curl -sS -X POST -H "Content-Type: application/json" -H "Accept: application/json" \
 -d '{"jsonrpc": "2.0", "method": "domotiga.version", "id": 1}' localhost:9090

Note that the command is split using the \ continuation character to improve readability.

This produce the following output:

{"jsonrpc": "2.0", "result": "1.0.023", "id": 1}

And to set device 52, value 1 to Off:

$ json='application/json'
$ params='"params": {"device_id": 52, "valuenum": 1, "value": "Off"}'
$ request='{"jsonrpc": "2.0", "method": "device.set", '${params}', "id": 1}'
$ curl -sS -X POST -H "Content-Type: $json" -H "Accept: $json" -d "$request" localhost:9090

For more examples, see Test-Tools.

[*] There is still some support for XML-RPC but that is being phased out.

Requirements

JSON-RPC has the following requirements:
  • DomotiGa 1.0.012 or higher


Available Methods

Method Description
system.listMethods Return all available JSON-RPC methods
system.hostname Get the hostname of the DomotiGa system
system.ipaddress Get the IP address(es) of the DomotiGa system
api.version The DomotiGa JSON-RPC API version
domotiga.pid Get the DomotiGa PID (Program Identifier)
domotiga.version DomotiGa version
domotiga.uptime How long DomotiGa is running
astro.get Retrieves sunset, sunrise, longitude, etc
data.newmessage Retrieves the new emails, calls and voicemails
housemode.list Retrieves the list of available House Modes
housemode.get Retrieves the current House Mode
housemode.set Sets the House Mode
sound.list List all available audio files
sound.play Plays an audio file
voicetext.speak Speaks the text
globalvar.list Retrieves the list of GlobalVar with their values
globalvar.get Get 1 GlobalVar value
globalvar.set Sets a GlobalVar value
globalvar.del Deletes a GlobalVar value
plugin.list Retrieves the list of Plugins with their state
plugin.restart Restart a Plugin, also applies for stopping
device.list Retrieves the list of devices
device.get Retrieves 1 device
device.set Sets a device on, off or dim
value.get Gets a value or log history values
value.set Sets a value
location.list Retrieves the list of locations
event.list Retrieves the list of events
event.set Sets a event
action.run Runs a action
action.list Retrieves the list of actions
scene.list Retrieves the list of scenes
scene.run Runs a scene
email.send Sends an email
twitter.send Post a tweet
sms.send Sends a SMS
nma.send Sends a Notify My Android notification
prowl.send Sends a Prowl notification
pushover.send Sends a Pushover notification
squeezebox.get Retrieves SqueezeBox/Server information
squeezebox.set Sets SqueezeBox/Server items
razberry.updatesready trigger from z-way-server that updates are ready to be fetched
tools.openzwave.get Retrieves OpenZWave information
tools.openzwave.set Set OpenZWave items
tools.rfxcom.get Retrieves RFXCom information
tools.rfxcom.set Set RFXCom items
tools.serialport.get Retrieves serialport information


Implementation

DomotiGa support JSON-RPC 2.0 over HTTP. The following applies:

  • JSON-RPC 1.0
  • JSON-RPC 2.0 (preferred)
  • HTTP/1.0 and 1.1
  • HTTP POST only
  • HTTPS supported
  • No authentication implemented YET (on the TODO list)

JSON-RPC Request in Body

On how to generate JSON-RPC Request for debugging, see JSON-RPC below.

Example of a HTTP POST request:

POST /jsonrpc HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:9090
Accept: */*
Content-Type: application/json
Content-Length: 57

{"jsonrpc": "2.0", "method": "domotiga.version", "id": 1}

Example of a HTTP response:

HTTP/1.1 200 OK
Connection: close
Content-Length: 48
Content-Type: application/json
Server: Gambas RPC Server

{"jsonrpc": "2.0", "result": "1.0.023", "id": 1}

JSON-RPC Request in URL

Example of a HTTP POST, request in the URL:

POST /jsonrpc?request=%7B%22jsonrpc%22%3A%20%222.0%22%2C%20%22method%22%3A%20%22domotiga.version%22%2C%20%22id%22%3A%201%7D HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost:9090
Accept: */*
Content-Type: application/json

Example of a HTTP response:

HTTP/1.1 200 OK
Connection: close
Content-Length: 48
Content-Type: application/json
Server: Gambas RPC Server

{"jsonrpc": "2.0", "result": "1.0.023", "id": 1}

See "Test Tools" below for an example of how to call the api using curl.


API Changes

v0.01 Initial Version
v0.02 Device values1-4 converted to dynamic number. The values aren't in "valueX" variables, but in a JSON array named "values".
v0.03 Device.set supports valuenum 2 and higher now
v1.01 Added 'value.get', JSON-RPC 1.0, HTTPS

System Methods

system.listMethods

Description: Retrieves the list of available JSON-RPC methods in the DomotiGa JSON-RPC server
Method: system.listMethods
Parameters: None
Returns: JSONArray of String

Example:

-> {"jsonrpc": "2.0", "method": "system.listMethods", "id": 1}
<- {"jsonrpc": "2.0", "result": ["system.listMethods", "system.hostname", "api.version", "domotiga.pid"], "id": 1}

system.hostname

Description: Retrieves the hostname from the system. This hostname is not FQDN
Method: system.hostname
Parameters: None
Returns: String

Example:

-> {"jsonrpc": "2.0", "method": "system.hostname", "id": 1}
<- {"jsonrpc": "2.0", "result": "domotiga", "id": 1}


API Methods

api.version

Description: Retrieves the DomotiGa JSON-RPC API version number. This version will be incremented if any changes are done, but we try to be always backwards compatible with the existing Methods
Method: api.version
Parameters: None
Returns: String

Example:

-> {"jsonrpc": "2.0", "method": "api.version", "id": 1}
<- {"jsonrpc": "2.0", "result": "1.00", "id": 1}


Domotiga Methods

domotiga.pid

Description: Get the DomotiGa PID (Program Identifier)
Method: domotiga.pid
Parameters: None
Returns: Integer

Example:

-> {"jsonrpc": "2.0", "method": "domotiga.pid", "id": 1}
<- {"jsonrpc": "2.0", "result": 48801, "id": 1}

domotiga.uptime

Description: Retrieves how long DomotiGa is running, reported in humanily readable format
Method: domotiga.pid
Parameters: None
Returns: String

Example:

-> {"jsonrpc": "2.0", "method": "domotiga.uptime", "id": 1}
<- {"jsonrpc": "2.0", "result": {"uptime": 353851, "uptime_str": "4 days, 2 hrs, 17 mins, and 31 secs."}, "id": 1}

domotiga.version

Description: Retrieve the DomotiGa version.
Method: domotiga.version
Parameters: None
Returns: String

Example:

-> {"jsonrpc": "2.0", "method": "domotiga.version", "id": 1}
<- {"jsonrpc": "2.0", "result": "1.0.023", "id": 1}


Astro Methods

astro.get

Description: Retrieve astrological information
Method: astro.get
Parameters: None
Returns: JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "astro.get", "id": 1}
<- {"jsonrpc": "2.0", "result": {"sunrise": "08:21", "sunset": "17:51", "sunrise_twilight": "07:44", "sunset_twilight": "18:27", "latitude": 52.8167, "longitude": -5.7667, "timezone": 1, "timezonename": "CET"}, "id": 1}


Data Methods

data.newmessage

Description: Retrieve new messages information
Method: data.newmessage
Parameters: None
Returns: JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "data.newmessage", "id": 1}
<- {"jsonrpc": "2.0", "result": {"email": 2, "call": 0, "voicemail": 0}, "id": 1}


Mode Methods

housemode.list

Description: Retrieve the list of House Modes
Method: housemode.list
Parameters: None
Returns: JSONArray of String

Example:

-> {"jsonrpc": "2.0", "method": "housemode.list", "id": 1}
tbd

housemode.get

Description: Retrieve the House Mode of DomotiGa. Valid values are "normal", "work", "away" and "vacation"
Method: housemode.get
Parameters: None
Returns: JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "housemode.get", "id": 1}
<- {"jsonrpc": "2.0", "result": {"mode": "vacation", "mute": false}, "id": 1}

housemode.set

Description: Sets the House Mode. Valid values are "normal", "work", "away" and "vacation" (NO VALIDATION DONE AT THE MOMENT)
Method: housemode.set
Parameters:
Fieldname Description Datatype Mandatory
mode Housemode to be set, needs to be in the allowed list String Yes
mute Sound enabled or disabled Boolean Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "housemode.set", "params": {"mode": "vacation"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

-> {"jsonrpc": "2.0", "method": "housemode.set", "params": {"mute": true}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

-> {"jsonrpc": "2.0", "method": "housemode.set", "params": {"mode": "vacation", "mute": true}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Sound Methods

sound.list

Description: List the available audio files
Method: sound.list
Parameters: None
Returns: JSONArray of String

Example:

-> {"jsonrpc": "2.0", "method": "sound.list", "id": 1}
<- {"jsonrpc": "2.0", "result": ["911.wav", "click.wav", "arribba.wav"], "id": 1}

sound.play

Description: Plays the file on the DomotiGa (Server). The file is located in the ~/domotiga/sounds directory, and the file has to be in the wav format
Method: sound.play
Parameters:
Fieldname Description Datatype Mandatory
file filename of the to be played file String Yes
volume volume of the to be played file 0-100 Integer No

(1) file: <filename> (string), (2) volume: <0-100> (integer - optional)
Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "sound.play", "params": {"file": "click.wav"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

-> {"jsonrpc": "2.0", "method": "sound.play", "params": {"file": "click.wav", "volume": 100}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

voicetext.speak

Description: Plays the file on the DomotiGa (Server). The file is located in the ~/domotiga/sounds directory, and the file has to be in the WAV format
Method: voicetext.speak
Parameters:
Fieldname Description Datatype Mandatory
text to be spoken text String Yes
voice to be used voice name String No

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "voicetext.speak", "params": {"text": "this is a test message"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

-> {"jsonrpc": "2.0", "method": "voicetext.speak", "params": {"text": "this is a test message", "voice": "linda"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


GlobalVar Methods

globalvar.list

Description: Retrieves the GlobalVar (variables) list
Method: globalvar.list
Parameters: None
Returns: JSONArray of JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "globalvar.list", "id": 1}
<- {"jsonrpc": "2.0", "result": {"House_Mode": "vacation", "Program_Start": "11/03/2013 17:58:43.162", "Second": 28, "Minute": 5, "Program_Uptime": "0 days, 0 hrs, 6 mins, and 45 secs.", "Hour": 18, "Day": 3, "Month": 11, "Weekday": 0, "Time_Of_Day": "evening", "Year": 2013, "Sunrise": "08:21", "Sunset": "17:51", "Sunrise_Twilight": "07:44", "Sunset_Twilight": "18:27", "Season": "fall", "Tagline": "Genealogy. Tracing descent from someone who didn't.", "NextPlanning": "00:00:00", "Weekend": true, "Dark": true, "Mute": true}, "id": 1}

globalvar.get

Description: Retrieves 1 GlobalVar value
Method: globalvar.get
Parameters:
Fieldname Description Datatype Mandatory
name global variable name String Yes

Returns: String/Integer/Boolean

Example:

-> {"jsonrpc": "2.0", "method": "globalvar.get", "params": {"name": "Minute"}, "id": 1}
<- {"jsonrpc": "2.0", "result": 45, "id": 1}

globalvar.set

Description: Sets a GlobalVar
Method: globalvar.set
Parameters:
Fieldname Description Datatype Mandatory
name global variable name String Yes
value global variable value String/Integer/Boolean Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "globalvar.set", "params": {"name": "TestVar", "value": 50} , "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

globalvar.del

Description: Deletes GlobalVar value
Method: globalvar.del
Parameters:
Fieldname Description Datatype Mandatory
name global variable name String Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "globalvar.del", "params": {"name": "Newone"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Plugin Methods

plugin.list

Description: Lists all plugins, with their current status
Method: plugin.list
Parameters: None
Returns: JSONArray of JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "plugin.list", "id": 1}
<- {"jsonrpc": "2.0", "result": [{"name": "Asterisk", "instance_id": 1, "enabled": false}, {"name": "CTX35", "instance_id": 1, "enabled": true, "running": false, "error":  Cannot open serial port (#5)"}], "id": 1}

plugin.restart

Example:

-> {"jsonrpc": "2.0", "method": "plugin.restart", "params": {"name": "CTX35"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Device Methods

device.list

Description: Retrieves the list of devices
Method: device.list
Parameters:
Fieldname Description Datatype Mandatory
list enabled, disabled, visible, hidden, ext, switch, dim and/or sensor String No
groups JSONArray of String No
locations JSONArray of Integer No
fields JSONArray of String - see possible fields in the return field list No

Returns: JSONArray of JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "device.list", "id": 1}
<- {"jsonrpc": "2.0", "result": [{"device_id": 1, "name": "Porch Light", "icon": "light-on.png","lastseen": "2008-12-14 18:00:00", "enabled": true, "hide": false, "dimable": false, "switchable": true, "batterystatus": "", "location_id": 6, "locationname": "Frontdoor","values": [{"id": 1, "deviceid": 1, "valuenum": 1, "rawvalue": "2.475", "value": "2.475", "correction": "", "units": "", "log": false, "logdisplay": false, "logspeak": false, "rrd": false, "graph": false, "valuerrddsname": "", "valuerrdtype": "", "lastchanged": "21:01:58", "lastseen": "21:01:58"}, {"id": 2, "deviceid": 1, "valuenum": 1, "rawvalue": "Up", "value": "Up", "correction": "", "units": "", "log": false, "logdisplay": false, "logspeak": false, "rrd": false, "graph": false, "valuerrddsname": "", "valuerrdtype": "", "lastchanged": "21:00:58", "lastseen": "21:01:58"}]}, {"device_id": 2, "name": "Power Usage", "icon": "energy.png", "value1": "ERROR: Unknown symbol", "value2": "0", "label2": "Watt", "value3": "", "value4": "", "lastseen": "2008-12-14 21:53:01", "enabled": true, "hide": false, "dimable": false, "switchable": false, "location_id": 13, "locationname": "MeterCabinet"}], "id": 1}

device.get

Description: Retrieve 1 specific device
Method: device.get
Parameters:
Fieldname Description Datatype Mandatory
device_id The id of the device information to be retrieved Integer Yes
fields JSONArray of String - see possible fields in the return field list of the "device.list" method No

Returns: JSONObject (see the return list of the "device.list" method)

Example:

-> {"jsonrpc": "2.0", "method": "device.get", "params": {"device_id": 2}, "id": 1}
<- {"jsonrpc": "2.0", "result": {"device_id": 2, "name": "Power Usage", "address": "RFXMETER[512]M", "devicetype_id": 9, "locationid": 13, "onicon": "energy.png", "officon": "energy.png", "dimicon": "", "interface_id": 1, "firstseen": "2008-08-31 22:39:31", "lastseen": "2008-12-14 21:53:01", "enabled": true, "hide": false, "groups": "|Energy|", "batterystatus": "", "tampered": "", "comments": "Measures power usage.", "switchable": false, "dimable": false, "extcode": false, "x": 0, "y": 0, "floorplanid": 1, "lastchanged": "2008-12-14 21:53:01", "repeatstate": "", "repeatperiod": "", "reset": "", "resetperiod": "", "resetvalue": "", "poll": "", "locationname": "MeterCabinet", "floorplanname": "", "floorplanimage": "", "devicetypename": "RFXPwr Power", "interfacename": "RFXCom Receiver", "icon": "energy.png","values": [{"id": 1, "deviceid": 1, "valuenum": 1, "rawvalue": "2.475", "value": "2.475", "correction": "", "units": "", "log": false, "logdisplay": false, "logspeak": false, "rrd": false, "graph": false, "valuerrddsname": "", "valuerrdtype": "", "lastchanged": "21:01:58", "lastseen": "21:01:58"}, {"id": 2, "deviceid": 1, "valuenum": 1, "rawvalue": "Up", "value": "Up", "correction": "", "units": "", "log": false, "logdisplay": false, "logspeak": false, "rrd": false, "graph": false, "valuerrddsname": "", "valuerrdtype": "", "lastchanged": "21:00:58", "lastseen": "21:01:58"}]}, }, "id": 1}

device.set

Description: Turns on, off or dim a device
Method: device.set
Parameters:
Fieldname Description Datatype Mandatory
device_id device unique identifier Integer Yes
valuenum value number of the value Integer No
value to be set value, normally "On", "Off" or "Dim <0-100>" String Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "device.set", "params": {"device_id": 1, "valuenum": 1, "value": "Off"}, "id": 1}
<- {"jsonrpc": "2.0", "result": false, "id": 1}


Value Methods

value.get

Description: Gets a value or log history values
Method: value.get
Parameters:
Fieldname Description Datatype Mandatory
device_id device unique identifier Integer Yes
valuenum value number of the value Integer No
command 'value' or 'log'. Value retrieves current value and log returns the log history of this value String Yes
count If 'log' is used, return the last entries, limited by the this number of rows Integer No
timestamp If 'log' is used, return the rows from this timestamp. Format can be '2016-05-01 12:00:00' or '2016-06-01' String No

NOTE: If command 'log' is used and no count or timestamp is specified, only the last 100 entries are returned

Returns:

Example:

-> {"jsonrpc": "2.0", "method": "value.get", "params": {"device_id": 39, "valuenum": 1, "command": "value"}, "id": 1}
<- {"jsonrpc": "2.0", "result": {"valuenum": 1, "rawvalue": "18.00", "correction": "", "units": "°C", "log": false, "logdisplay": false, "logspeak": false, "rrd": false, "graph": false, "valuerrddsname": "", "valuerrdtype": "", "lastchanged": "2014-02-23 13:12:52", "lastseen": "2014-02-23 13:12:52", "description": "", "type_id": 0, "feedback": false, "control": false, "value": "18.00"}, "id": 1}

Example:

-> {"jsonrpc": "2.0", "method": "value.get", "params": {"device_id": 39, "valuenum": 1, "timestamp": "2016-04-01"}, "id": 1}
<- {"jsonrpc": "2.0", "result": [{"log_id": 5751, "value": "On", "rawvalue": "On", "lastchanged": "2016-04-01 07:24:36"}, {"log_id": 5752, "value": "On", "rawvalue": "Off", "lastchanged": "2016-04-01 07:25:06"}, {"log_id": 5753, "value": "On", "rawvalue": "On", "lastchanged": "2016-04-01 09:18:14"}, {"log_id": 5754, "value": "On", "rawvalue": "Off", "lastchanged": "2016-04-01 09:18:44"}, {"log_id": 5755, "value": "On", "rawvalue": "On", "lastchanged": "2016-04-01 09:19:40"}, {"log_id": 5756, "value": "On", "rawvalue": "Off", "lastchanged": "2016-04-01 09:20:10"}], "id": 1}

value.set

Description: Sets a value
Method: value.set
Parameters:
Fieldname Description Datatype Mandatory
device_id device unique identifier Integer Yes
valuenum value number of the value Integer No
value to be set value" String Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "value.set", "params": {"device_id": 1, "valuenum": 1, "value": "22.1"}, "id": 1}
<- {"jsonrpc": "2.0", "result": false, "id": 1}


Location Methods

location.list

Description: Retrieves the list of locations
Method: location.list
Parameters: None
Returns: JSONArray of JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "location.list", "id" : 1}
<- {"jsonrpc": "2.0", "result": [{"location_id": 1, "name": ""}, {"location_id": 2, "name": "Livingroom"}, {"location_id": 3, "name": "Bathroom"}, {"location_id": 4, "name": "Toilet"}, {"location_id": 5, "name": "Hallway"}, {"location_id": 6, "name": "Frontdoor"}, {"location_id": 7, "name": "Kitchen"}, {"location_id": 8, "name": "Garden"}, {"location_id": 9, "name": "Master Bedroom"}, {"location_id": 10, "name": "Serverroom"}, {"location_id": 11, "name": "Laundryroom"}, {"location_id": 12, "name": "Hobbyroom"}, {"location_id": 13, "name": "MeterCabinet"}, {"location_id": 15, "name": "Neighbours"}, {"location_id": 16, "name": "Mobile"}, {"location_id": 17, "name": "Boiler"}, {"location_id": 18, "name": "Test"}], "id": 1}


Event Methods

event.list

Description: Retrieves the list of available events
Method: event.list
Parameters:
Fieldname Description Datatype Mandatory
fields JSONArray of String - see possible fields in the return field list No

Returns: JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "event.list", "id": 1}
<- {"jsonrpc": "2.0", "result": [{"event_id": 1, "enabled": false, "name": "Frontdoor Light On", "log": true, "firstrun": "01/06/2009
 17:30:00", "lastrun": "03/05/2009 17:15:00", "comments": "Switch frontdoor light on at dawn", "trigger1": 1, "condition1": 0, "oper
and": "", "condition2": 0, "rerunenabled": false, "rerunvalue": 0, "reruntype": "gb.Second", "category": "", "actionlist": [{"action_
id": 1, "order": 0}]}], "id": 1}

event.set

Description: Sets a event
Method: event.set
Parameters:
Fieldname Description Datatype Mandatory
event_id The id of the event Integer Yes
enabled Event enabled or disabled Boolean Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "event.set", "params": {"event_id": 1, "enabled":  true}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


action.list

Description: Retrieves the list of available actions
Method: action.list
Parameters:
Fieldname Description Datatype Mandatory
fields JSONArray of String - see possible fields in the return field list No

Returns: JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "action.list", "id": 1}
<- {"jsonrpc": "2.0", "result": [{"action_id": 1, "name": "Switch Porch Light On", "type": 1, "description": "", "param1": "1", "param2": "1", "param3": "On", "param4": "", "param5": ""}, "id": 1}

action.run

Description: Runs a action
Method: action.run
Parameters:
Fieldname Description Datatype Mandatory
action_id The id of the action Integer Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "action.run", "params": {"action_id": 1}, "id": 1}
<- {"jsonrpc": "2.0", "result": false, "id": 1}


scene.list

Description: Retrieves the list of available scenes
Method: scene.list
Parameters:
Fieldname Description Datatype Mandatory
fields JSONArray of String - see possible fields in the return field list No

Returns: JSONObject

Example:

-> {"jsonrpc": "2.0", "method": "scene.list", "id": 1}
TBD

scene.run

Description: Runs a scene
Method: scene.run
Parameters:
Fieldname Description Datatype Mandatory
scene_id The id of the scene Integer Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "scene.run", "params": {"scene_id": 1}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Message Methods

email.send

Description: Send an email
Method: email.send
Parameters:
Fieldname Description Datatype Mandatory
msg The email body to be send String Yes
subject Subject of the email String Yes
to To whom the email to be send, if left blank, the default to field is taken from the email settings String No

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "email.send", "params": {"msg": "test msg\nline 1", "subject": "test subject"}, "id": 1}
<- {"jsonrpc": "2.0", "result": false, "id": 1}

twitter.send

Description: Post a tweet on twitter
Method: twitter.send
Parameters:
Fieldname Description Datatype Mandatory
msg The tweet to be posted String Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "twitter.send", "params": {"msg": "test tweet"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

sms.send

Description: Send a SMS
Method: sms.send
Parameters:
Fieldname Description Datatype Mandatory
msg The SMS message to send String Yes
to The telephonenumber to whom the SMS is send String Yes

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "sms.send", "params": {"msg": "test msg", "to": "31612345678"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

nma.send

Description: Send a Notify My Android notification
Method: nma.send
Parameters:
Fieldname Description Datatype Mandatory
msg The notification message String Yes
application application name String No
event event name String No

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "nma.send", "params": {"msg": "test nma"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

prowl.send

Description: Send a Prowl notification
Method: prowl.send
Parameters:
Fieldname Description Datatype Mandatory
msg The notification message String Yes
application application name String No
event event name String No

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "prowl.send", "params": {"msg": "test prowl", "event": "test-event"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

pushover.send

Description: Send a Pushover notification
Method: nma.send
Parameters:
Fieldname Description Datatype Mandatory
msg The notification message String Yes
device device name, if not specified, the default will be taken String No
priority message priority: allowed values are "normal", "low", "high" and "emergency" String No
sound sound name: allowed values are "bike", "bugle", "cashregister", "classical", "cosmic", "falling", "gamelan", "incoming", "intermission", "magic", "mechanical", "pianobar", "siren", "spacealarm", "tugboat", "alien", "climb", "persistent", "echo", "updown", "none" String No

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "pushover.send", "params": {"msg": "test pushover"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Squeezebox Methods

squeezebox.get

Description: Retrieve information from the SqueezeBox/Server
Method: squeezebox.get
Parameters:
Fieldname Description Datatype Mandatory
function volume, currentnumber, currentartist, albums, mode, playerid, playername, playertype, isconnected String Yes
player PlayerId, has to be in format like "02:00:00:00:00" String Yes

Returns:

Function Datype
volume Integer
currentnumber String
currentartist String
albums Array of String
mode String
playerid String
playername String
playertype String
isconnected String

Example:

-> {"jsonrpc": "2.0", "method": "squeezebox.get", "params": {"function": "volume", "player": "02:00:00:00:00:00"}, "id": 1}
<- {"jsonrpc": "2.0", "result": 50, "id": 1}

squeezebox.set

Description: Do an action on the SqueezeBox/Server
Method: squeezebox.set
Parameters:
Fieldname Description Datatype Mandatory
function volume, startplayer, stopplayer, nextnumber, prevnumber, clearplaylist, addalbumtoplaylist String Yes
player PlayerId, has to be in format like "02:00:00:00:00" String Yes
volume Volume to be set between 0-100, only mandatory for function=volume Integer No
album Album to add to the list, only mandatory for function=addalbumtoplaylist string No

Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "squeezebox.set", "params": {"function": "volume", "volume": 75, "player": "02:00:00:00:00:00"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

-> {"jsonrpc": "2.0", "method": "squeezebox.set", "params": {"function": "stopplayer", "player": "02:00:00:00:00:00"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}

-> {"jsonrpc": "2.0", "method": "squeezebox.set", "params": {"function": "addalbumtoplaylist", "album": "newartist", "player": "02:00:00:00:00:00"}, "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Razberry Methods

razberry.updatesready

Description: Trigger from z-way-server that updates are ready to be fetched
Method: razberry.updatesready
Parameters: None
Returns: Boolean (true: success, false: failed)

Example:

-> {"jsonrpc": "2.0", "method": "razberry.updatesready", "id": 1}
<- {"jsonrpc": "2.0", "result": true, "id": 1}


Test Tools

We look on the internet if there were any free and easy command line tools available, but we found none. For testing with the JSON-RPC we included a simple perl script using curl which does the job very nicely :)

The test tools can be found in the ~/domotiga/test-tools/json-rpc directory. Then just execute as follows:

$ cd ~/domotiga/development/json-rpc
$ ./json-rpc.pl

This will generate the request and response files named <method name>,json.txt

You can also test a single command from the command line by using "curl".
For example to get the domotiga version (using the method {"jsonrpc": "2.0", "method": "domotiga.version", "id": 1} ), you would execute the following curl command from the command line.

$ curl -sS -X POST -H "Content-Type: application/json" -H "Accept: application/json" \
 -d '{"jsonrpc": "2.0", "method": "domotiga.version", "id": 1}' localhost:9090

Note that the command is split using the \ continuation character to improve readability.

This produce the following output...

{"jsonrpc": "2.0", "result": "1.0.013", "id": 1}

An example with (input) parameters, get the current month:

$ curl -sS -X POST -H "Content-Type: application/json" -H "Accept: application/json" \
 -d '{"jsonrpc": "2.0", "method": "globalvar.get", "id" : 1, "params" : { "name" : "Month" } }"' localhost:9090
{"jsonrpc": "2.0", "result": 9, "id": 1}


Accessing JSON-RPC using other programming languages

PHP

DomotiYii accesses DomotiGa using JSON-RPC, so have a look at the DomotiYii code to see some examples to access JSON-RPC using PHP.
Some code scraped from existing DomotiYii code:

<?php

set_globalvar("Test", "Off");

   function set_globalvar($var, $value) {
        $json_res = doJsonRpc(array('jsonrpc' => '2.0', 'method' => 'globalvar.set', 'params' => array('name' => $var, 'value' => $value), 'id' => 1));
        if (isset($json_res->result)) {
           if ($json_res->result) {
              echo 'GlobalVar Set.';
           } else if (!$json_res->result) {
              echo 'Setting GlobalVar failed!';
           }
        }
    }

   function doJsonRpc($data = array()) {
        if(json_validate($data)) {
            $request = $data;
        } else {
            $request = json_encode($data);
        }

        $context = stream_context_create(
            array('http' =>
                array('method' => "POST",
                    'header' => "Content-Type: application/json\r\n" .
                    "Accept: application/json\r\n",
                    'content' => $request)));
        $file = @file_get_contents('http://localhost:9090', false, $context);
        if ($file === false) {
            // could not connect
            echo 'Cannot connect to JSON-RPC server!';
            return (object) array("jsonrpc" => "2.0", "result" => false, "id" => 1);
        } else {
            return @json_decode($file);
        }
    }

    function json_validate($string) {
        if (is_string($string)) {
            @json_decode($string);
            return (json_last_error() === JSON_ERROR_NONE);
        }
        return false;
    }

?>

Python

import json, requests, simplejson

def Domotiga_API(Method, Device_Id, Valuenum, Value):
    url = "http://localhost:9090" 
    data={'jsonrpc': '2.0', 'method': '' + Method + '', 'params': {'device_id': Device_Id, 'valuenum': '' + str(Valuenum) + '', 'value': '' + str(Value) + ''}, 'id': 1}
    headers = {'Content-type': 'application/json', 'Accept-Encoding': 'text/plain', 'Accept': 'text/plain'}
    r = requests.post(url, data=json.dumps(data), headers=headers)
    c = r.content
    result = simplejson.loads(c)
    print result

Debugging JSON-RPC

If the JSON-RPC communication doesn't work, make sure the server is listening on the JSON-RPC port for commands (default is 9090)

$ netstat -nap|grep 9090
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
tcp        0      0 0.0.0.0:9090            0.0.0.0:*               LISTEN      47782/gbr3

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

2013/11/10 10:36:24 The JSONRPC server URL is 'http://localhost:9090/'

Capturing traffic

Try tcpdump:

$ sudo tcpdump -i any -s 0 -w /tmp/jsonrpc.cap port 9090
$ sudo tcpdump -i lo -s 0 -w /tmp/jsonrpc.cap

You can use wireshark to have a look at the data.


Resources

  • Added by Samfox2 over 2 years ago

    A small python routine to set/update device values via JSON call:

    import json, requests, simplejson
    
    def Domotiga_API(Method, Device_Id, Valuenum, Value):
        url = "http://localhost:9090" 
        data={'jsonrpc': '2.0', 'method': '' + Method + '', 'params': {'device_id': Device_Id, 'valuenum': '' + str(Valuenum) + '', 'value': '' + str(Value) + ''}, 'id': 1}
        headers = {'Content-type': 'application/json', 'Accept-Encoding': 'text/plain', 'Accept': 'text/plain'}
        r = requests.post(url, data=json.dumps(data), headers=headers)
        c = r.content
        result = simplejson.loads(c)
        print result
    

Updated by: Alexie, Updated 12 months ago
Access count: 83778

Attached Files

Also available in: PDF HTML TXT