MessageFormat

From ago control wiki
Revision as of 16:11, 9 April 2015 by Hari (Talk | contribs)

Jump to: navigation, search

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.

Contents

commandHandler response

The commandHandler response is a map. Depending on success or failure, it either contains a "result" or an "error" map, which has the following structure:

Result

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 result 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 error 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
                    ...
                },

            },
        }
    }
}

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)
  • "event-ref" - optional reference for resulting events
  • optional data fields with names different from the fields above

Reply

Map according to |commandHandler response


Used identifiers

  • 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

Examples

TODO: check if examples match the current definition

successful with follow-up event

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

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

immediately failed:

> {uuid:"1234xxx", command: "setlevel", "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": ""}}


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
Personal tools