MessageFormat

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.

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 provided by the command handler. Examples are different maps returned by components (e.g the scenario map for the getscenario command of the scenario component)

"event-ref" - optional ID string, if an event will be sent as a result of this command being executed, the event will have a matching "event-ref"

Example

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

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.

Example:

{
    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 and reuse is encouraged. These identifiers MAY also be used to alter application logic depending on error, thus be careful if you are changing existing error identifiers.

"message" - descriptive error message string in english language (e.g. "something really bad happened when trying to do stuff"), mainly to aid in debugging (the main error message shall be translated from the identifier)

Optional fields

"data" - holds optional map with arbitrary data

Example

{
    error: {
        identifier: "error.subsystem.badthingshappened",
        message: "something really bad happened when trying to do stuff",
        data: {
            faulty_data: 0,
            ...
        },
    }
}

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" value of the JSON-RPC error struct. "code" is set to our application specific code -31999. Message is set to "Command returned error".

Example:

{
    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: {
                faulty_data: 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 “event-ref” field shall always be set. This can also be used to indicate failure to execute the request.

Mandatory fields

• “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 “event-ref”, if set this shall be a previously issued “event-ref”

JSON-RPC Encapsulation

To obtain events through the JSON-RPC interface, the caller must use the subscription mechanism and poll the "getevent" method. For more details, see RPC#subscribe

Used identifiers

Successful

• success

Failed

• error.failed - Failed to execute the command
• error.unknown.command - The targeted device does not support this command
• error.parameter.missing - Bad call, parameter missing. Message shall indicate which parameter is missing
• error.parameter.invalid - Bad call, unacceptable parameter. Message shall indicate which parameter is invalid, and why

• error.device.invalid - ?? Can this ever be sent? If the device is not known, nothing will handle the command..?

• error.cannot.send.sms
• error.security.housemodechange
• error.security.invalidpin
• error.security.housemodenotset
• error.security.alarmthreadfailed
• error.security.alarmthreadcancelfailed
• error.security.invalidmap
• error.security.setzones