Revision as of 14:43, 9 April 2015

Agocontrol applications communicate using broadcasted requests, which shall produce a single reply (Request-reply pattern), and broadcasted events. These are sent on the Qpid/AMQP messaging bus.

Draft

The commandHandler response is a map. Depending on success or failure, it has the following structure:

Success

Mandatory fields

"identifier" - hold a success identifier string value. Defaults to "success".

Optional fields

"message" - holds an optional verbose success message.

"data" - holds a map of arbitrary data which will be returned by the command handler. Examples are different maps returned by components (e.g the scenario map for the getscenario command of the scenario component)

JSON-RPC encapsulation

When a success result is being sent over JSON-RPC transport (via agorpc), the map is passed 1:1 as "result" key in JSON-RPC. So it looks like the following:

{
    jsonrpc: 2.0,
    id: null,
    result: {
        identifier: "success",
        message: "the command did success, happy hippos",
        data: {
            agorpc: {
                ucpu: 0
                scpu: 0
                ...
            },
            agolua: {
                ucpu: 0
                scpu: 0
                ...
            },
            ...
        }
    }
}

Error

Mandatory fields

"identifier" - holds an error identifier string which is used for translation (e.g. "error.subsystem.badthingshappened"). These should be kept generic to facilitate translation and keep effort low. "message" - descriptive error message string in english language (e.g. "something really bad happened when trying to do stuff").

Optional fields

"data" - holds optional map data

JSON-RPC encapsulation

When an error result is being sent over JSON-RPC transport (via agorpc), the result map is passed 1:1 as "data" key of the error struct in JSON-RPC. "code" is set to our application specific code -31999. Message is set to "command returned error". So it looks like the following:

{
    jsonrpc: 2.0,
    id: null,
    error: {
        code: -31999,
        message: "command returned error", 
        data: {
            identifier: "error.subsystem.badthingshappened",
            message: "something really bad happened when trying to do stuff",
            data: {
                agorpc: {
                    ucpu: 0
                    scpu: 0
                    ...
                },

            },
        }
    }
}

DRAFT END

INTENTIONALLY LEFT BLANK

Event

An event can be sent at any time from a device, either externally triggered or triggered by a Agocontrol request. If triggered by previous request, a “ref” field shall always be set. This can also be used to indicate failure to execute the request.

• “uuid”, the originating device
• “event”, event string code, OR
• “error”, an error-map in case we failed to execute a command (“ref” required)
• optionally “data”, event-specific parameters, only if “event” is set
• optionally “ref”, if set this shall be a previously issued “event-ref”

TODO: update above

Request-reply

Request

One request gives one reply, which is sent to a temporary reply-queue. The message content is a Variant map with the following fields:

• “uuid” - String which contains targets device uuid
• “command” which tells the command (string)
• optional “data” map with parameters to the command [new]

Reply

• “result”, containing a result-map
• “error”, containing an error-map

Error map

Sent as part of a Reply or an Event. The format

• “message”, a standardized code in the format “error.<describing string>”, re-use is encouraged, will be translated and used as error message.
• "data", an optional map with more specific error information.

The only reserved key in the "data" map is:

• “description”, an optional human readable debug message in english.

Result map

Sent as part of a Reply

• “identifier”, a standardized code in the format “success.<describing string>”, re-use is encouraged, will be translated and used as informative notice, if appropriate
• “description”, an optional human readable debug message in english.

Examples

successful with follow-up event

> {uuid:"1234xxx", command: "setlevel", data: {"level": 50}}
< {result: {identifier: "success.queued"}, "event-ref": "99random99"}

* {uuid: "1234xxx", event:"event.device.statechanged", "data": {"level": "50", "unit": ""}, 
"ref":"99random99"}

immediately failed:

> {command: "setlevel", uuid:"1234xxx", data: {"level": 50}}
< {error: {message: "error.unknown.command", data: { description: "Command disabled for this device"} } }}

successful with failed follow-up event:

> {command: "setlevel", uuid:"1234xxx", data: {"level": 50}}
< {result: {identifier: "success.queued"}, "event-ref": "99random99"}

* {uuid: "1234xxx", error: {"identifier": "error.call.failed"}, "ref":"99random99"}

externally triggered change:

* {uuid: "1234xxx", event:"event.device.statechanged", "data": {"level": "255", "unit": ""}}

Used codes

• success
• error.cannot.send.SMS
• error.parameter.missing
• error.command.invalid
• error.command.missing
• error.security.housemodechange
• error.security.invalidpin
• error.security.housemodenotset
• error.security.alarmthreadfailed
• error.security.alarmthreadcancelfailed
• error.security.invalidmap
• error.security.setzones
• error.device.invalid

Redacted

This was moved from Reply... to be decided if we want and how:

TODO

• optionally “data” with extra reply data (only allowed together with “result”)
• optionally “event-ref” with a random string, used for any subsequent events triggered by this request