RPC

From ago control wiki
(Difference between revisions)
Jump to: navigation, search
m (JSON-RPC interface)
(Javascript)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= RPC Interface =
+
= JSON-RPC Interface =
ago control provides a RPC interface. It is implemented in the agorpc daemon. It is written in C++ and uses the [http://code.google.com/p/mongoose/ mongoose embedded web server] to provide an HTTP interface on port 8008 by default. Be sure that the RPC service is running else start it:
+
ago control provides a JSON-RPC interface. It is implemented in the agorpc daemon. It is written in C++ and uses the [http://code.google.com/p/mongoose/ mongoose embedded web server] to provide an HTTP(S) interface on ports 8008 and 8009 (SSL) by default. You can adjust these by specifying a ports option in the RPC config section:
systemctl start agorpc.service
+
== HTTP GET requests  ==
+
The following calls are supported:
+
=== Inventory ===
+
The inventory can be fetched as JSON structure with the following command request:
+
http://x.y.z:8008/command?command=inventory
+
  
=== Send commands ===
+
  [rpc]
Other commands work the same, e.g. to switch on a lamp:
+
  ports=8008,8009s
  http://x.y.z:8008/command?command=on&uuid=91926587-03c6-4cfa-898c-4d5ad75fc494
+
Set level for a dimmer:
+
  http://x.y.z:8008/command?command=setlevel&uuid=c2467e36-817e-4b63-a274-0cc23e550965&level=50
+
Fetch the electronic program guide from a Dreambox/Engima2:
+
http://x.y.z:8008/command?command=getepg&uuid=4a79ce72-7cfe-4b12-bfc5-dfd30bb297f4
+
  
=== Receive Events ===
+
The "s" is no typo, it specifies that this port is used for SSL.
This GET request will stay open and stream any incoming event:
+
http://x.y.z:8008/update
+
== JSON-RPC interface ==
+
agorpc also implements a JSON-RPC interface. The JSON parsing is done with [http://jsoncpp.sourceforge.net/index.html jsoncpp]. You can find more information regarding JSON-RPC here: [http://www.jsonrpc.org/specification Specification]
+
  
The interface is accessible via HTTP transport. The path is "/jsonrpc". Please be aware that batches don't work yet.  
+
All JSON-RPC calls are made towards the endpoint "/jsonrpc".
=== Methods ===
+
The JSON parsing is done with [http://jsoncpp.sourceforge.net/index.html jsoncpp]. You can find more information regarding JSON-RPC here: [http://www.jsonrpc.org/specification Specification]
 +
 
 +
 
 +
A basic JSON-RPC request will always have these fields:
 +
<pre>
 +
{"jsonrpc" : "2.0",
 +
  "method" : "some-method",
 +
  "params" : {....},
 +
  "id":1
 +
}
 +
</pre>
 +
 
 +
== Methods ==
 
The following methods are implemented:
 
The following methods are implemented:
==== message ====
+
 
 +
=== message ===
 
The message method will send an AMQP message to ago control with "content" as content. This example will switch off a specific uuid:  
 
The message method will send an AMQP message to ago control with "content" as content. This example will switch off a specific uuid:  
  {"jsonrpc" : "2.0", "method" : "message", "params" : {"content":{"command":"off", "uuid":"0962f27e-99ce-43a4-872b-97d75d61f464"}}, "id":1 }
+
 
 +
<pre>
 +
  {"jsonrpc" : "2.0",  
 +
  "method" : "message",  
 +
  "params" : {
 +
    "content":{
 +
      "command":"off",
 +
      "uuid":"0962f27e-99ce-43a4-872b-97d75d61f464"
 +
    }
 +
  },  
 +
  "id":1
 +
}
 +
</pre>
 +
 
 
This call will fetch the inventory from the [[Resolver]]:
 
This call will fetch the inventory from the [[Resolver]]:
  {"jsonrpc" : "2.0", "method" : "message", "params" : {"content":{"command":"inventory"}}, "id":2 }
+
<pre>
 +
  {"jsonrpc" : "2.0",  
 +
  "method" : "message",  
 +
  "params" : {
 +
    "content":{
 +
      "command":"inventory"
 +
    }
 +
  },  
 +
  "id":1
 +
}
 +
</pre>
 +
 
 +
The response format is described in [[MessageFormat]]
 +
 
 +
 
 +
 
 
To send an event also add a "subject" parameter to "params".
 
To send an event also add a "subject" parameter to "params".
 +
 +
=== subscribe ===
 +
Subscriptions are used to listen to broadcasted events on the Agocontrol message bus.
 +
 +
This will create a subscription and provide a uuid for it. You can use the getevent call afterwards to fetch any events that did occur.
 +
 +
==== Request ====
 +
<pre>
 +
{
 +
    "method": "subscribe",
 +
    "id": 1,
 +
    "jsonrpc": "2.0"
 +
}
 +
</pre>
 +
 +
==== Response ====
 +
<pre>
 +
{
 +
    "jsonrpc": "2.0",
 +
    "result": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec",
 +
    "id": 1
 +
}
 +
</pre>
 +
 +
 +
=== getevent ===
 +
The getevent method will fetch an event from the queue. If no event is in the queue, this call will block until the next event occurs.
 +
<pre>
 +
{
 +
    "method": "getevent",
 +
    "params": {
 +
        "uuid": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec"
 +
    },
 +
    "id": 2,
 +
    "jsonrpc": "2.0"
 +
}
 +
</pre>
 +
 +
==== Response ====
 +
<pre>
 +
{
 +
    "jsonrpc": "2.0",
 +
    "result": {
 +
        "event": "event.environment.timechanged",
 +
        "day": 2,
 +
        "hour": 22,
 +
        "minute": 10,
 +
        "month": 1,
 +
        "second": 0,
 +
        "weekday": 3,
 +
        "yday": 1,
 +
        "year": 2013
 +
    },
 +
    "id": 2
 +
}
 +
</pre>
 +
 +
=== unsubscribe ===
 +
If you don't want to fetch events anymore you need to unsubscribe:
 +
 +
==== Request ====
 +
<pre>
 +
{
 +
    "method": "unsubscribe",
 +
    "params": {
 +
        "uuid": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec"
 +
    },
 +
    "id": 3,
 +
    "jsonrpc": "2.0"
 +
}
 +
</pre>
 +
 +
 +
 +
= Examples =
 +
== Javascript ==
 +
Note: if developing in the Agocontrol Web UI, you never need to deal with lowlevel code like this. Instead use the sendCommand methods (TODO: Document)
 +
 +
<pre>
 +
var url = "/jsonrpc";
 +
 +
function displayEvent(response) {
 +
if (response.result) {
 +
console.log(response.result)
 +
}
 +
getevent();
 +
}
 +
 +
function getevent() {
 +
var request = {};
 +
request.method = "getevent";
 +
request.params = {};
 +
request.params.uuid = "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec";
 +
request.id = 1;
 +
request.jsonrpc = "2.0";
 +
 +
$.post(url, JSON.stringify(request), displayEvent, "json");
 +
 +
}
 +
</pre>

Latest revision as of 09:42, 11 April 2015

Contents

[edit] JSON-RPC Interface

ago control provides a JSON-RPC interface. It is implemented in the agorpc daemon. It is written in C++ and uses the mongoose embedded web server to provide an HTTP(S) interface on ports 8008 and 8009 (SSL) by default. You can adjust these by specifying a ports option in the RPC config section:

[rpc]
ports=8008,8009s

The "s" is no typo, it specifies that this port is used for SSL.

All JSON-RPC calls are made towards the endpoint "/jsonrpc". The JSON parsing is done with jsoncpp. You can find more information regarding JSON-RPC here: Specification


A basic JSON-RPC request will always have these fields:

{"jsonrpc" : "2.0",
  "method" : "some-method",
  "params" : {....},
  "id":1
}

[edit] Methods

The following methods are implemented:

[edit] message

The message method will send an AMQP message to ago control with "content" as content. This example will switch off a specific uuid:

 {"jsonrpc" : "2.0", 
  "method" : "message", 
  "params" : {
    "content":{
      "command":"off",
      "uuid":"0962f27e-99ce-43a4-872b-97d75d61f464"
    }
  }, 
  "id":1
}

This call will fetch the inventory from the Resolver:

 {"jsonrpc" : "2.0", 
  "method" : "message", 
  "params" : {
    "content":{
      "command":"inventory"
    }
  }, 
  "id":1
}

The response format is described in MessageFormat


To send an event also add a "subject" parameter to "params".

[edit] subscribe

Subscriptions are used to listen to broadcasted events on the Agocontrol message bus.

This will create a subscription and provide a uuid for it. You can use the getevent call afterwards to fetch any events that did occur.

[edit] Request

{
    "method": "subscribe",
    "id": 1,
    "jsonrpc": "2.0"
}

[edit] Response

{
    "jsonrpc": "2.0",
    "result": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec",
    "id": 1
}


[edit] getevent

The getevent method will fetch an event from the queue. If no event is in the queue, this call will block until the next event occurs.

{
    "method": "getevent",
    "params": {
        "uuid": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec"
    },
    "id": 2,
    "jsonrpc": "2.0"
}

[edit] Response

{
    "jsonrpc": "2.0",
    "result": {
        "event": "event.environment.timechanged",
        "day": 2,
        "hour": 22,
        "minute": 10,
        "month": 1,
        "second": 0,
        "weekday": 3,
        "yday": 1,
        "year": 2013
    },
    "id": 2
}

[edit] unsubscribe

If you don't want to fetch events anymore you need to unsubscribe:

[edit] Request

{
    "method": "unsubscribe",
    "params": {
        "uuid": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec"
    },
    "id": 3,
    "jsonrpc": "2.0"
}


[edit] Examples

[edit] Javascript

Note: if developing in the Agocontrol Web UI, you never need to deal with lowlevel code like this. Instead use the sendCommand methods (TODO: Document)

var url = "/jsonrpc";

function displayEvent(response) {
	if (response.result) { 
		console.log(response.result)
	}
	getevent();
}

function getevent() {
	var request = {};
	request.method = "getevent";
	request.params = {};
	request.params.uuid = "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec";
	request.id = 1;
	request.jsonrpc = "2.0";

	$.post(url, JSON.stringify(request), displayEvent, "json");

}
Personal tools