RPC

From ago control wiki
(Difference between revisions)
Jump to: navigation, search
m (RPC Interface)
m (subscribe)
Line 30: Line 30:
 
     "result": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec",
 
     "result": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec",
 
     "id": 1
 
     "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": {
 +
        "day": 2,
 +
        "event": "event.environment.timechanged",
 +
        "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>
 
</pre>

Revision as of 23:23, 2 January 2013

Contents

RPC Interface

ago control provides a 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 interface on port 8008 by default. Be sure that the RPC service is running else start it:

systemctl start agorpc.service

JSON-RPC interface

agorpc also implements a JSON-RPC interface. The JSON parsing is done with jsoncpp. You can find more information regarding JSON-RPC here: Specification

The interface is accessible via HTTP transport. The path is "/jsonrpc". Please be aware that batches don't work yet.

Methods

The following methods are implemented:

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":2 }

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

subscribe

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
{
    "method": "subscribe",
    "id": 1,
    "jsonrpc": "2.0"
}
Response
{
    "jsonrpc": "2.0",
    "result": "2d28cb85-5be0-4ccb-bc21-33bf94ed04ec",
    "id": 1
}

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"
}
Response
{
    "jsonrpc": "2.0",
    "result": {
        "day": 2,
        "event": "event.environment.timechanged",
        "hour": 22,
        "minute": 10,
        "month": 1,
        "second": 0,
        "weekday": 3,
        "yday": 1,
        "year": 2013
    },
    "id": 2
}

unsubscribe

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

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

HTTP GET requests (OBSOLETE! This might be removed in future versions)

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

Other commands work the same, e.g. to switch on a lamp:

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

This GET request will stay open and stream any incoming event:

http://x.y.z:8008/update
Personal tools