Exchange ase.exchange.driver

Setup

User: device-driver-user

Permissions: the device driver user can create an exclusive queue that starts with "ase.queue.driver." (with a unique suffix) and bind it to the ase.exchange.driver (headers) exchange specifying which headers/arguments to bind with (x-match=all or x-match=any). This user can only subscribe and consume/get messages. This is a mechanism for core services to publish messages to the driver with specific targeting.

The headers to be used for binding and targeting as follows.

Incoming Messages

These messages come in on the unique queue bound to the exchange.

Response Messages

The following are response messages to the incoming messages. Note that the messages are published to different exchanges or queues. The queue is the "replyTo" property of the AMQP message.

The responses to the incoming messages related to discovery ("upload" and "reportStatus" responses) are described on the "Exchange Core" page.

The reponse to the requestAPIregistration message is done by publishing a message to the "Exchange API" as described on the "Register API" page.

Action Message Processing

Let's use an example of a device that has an Action called "activate" defined on its Thing description (schema) and an Event, with the same name, as follows:

    "uid": "453AEP18F901FRJK8J1MJ10ZYR",
    "actions": {
        "activate": {
            "title": "Activate",
            "description": "Activate the device",
            "input": {
                "properties": {
                    "address": {
                        "type": "string"
                    },
                    "secure_key": {
                        "type": "string"
                    }
                },
                "type": "object"
            }
        }
    },
    "events": {
        "activate": {
            "title": "Activate request is done",
            "description": "Response of activate request",
            "data": {
                "type": "object"
            }
        }
    }

When the user request this Action through an API call (using Studio or direct), the following AMQP message is published to all queues on the ase.exchange.driver exchange bound with header thingID=453AEP18F901FRJK8J1MJ10ZYR as follows:

AMQP headers:

messageType=requestAction
thingID=453AEP18F901FRJK8J1MJ10ZYR
action=activate
actionID=6CTAX0F1M01FRJKZ1DJXG5T3ZS

AMQP message body:

{
    "activate": {
        "input": {
            "address": "f1110197",
            "secure_key": "e4eb6ff6281bea9e568236802dcf4e0a"
        }
    }
}

When the third party service receives this Action request it should first publish an actionStatus message to the ase.exchange.telemetry exchange as follows:

AMQP headers:

messageType=actionStatus
publishTag=raw
thingID=453AEP18F901FRJK8J1MJ10ZYR

AMQP message body:

{
    "thingId": "453AEP18F901FRJK8J1MJ10ZYR",
    "timestamp": 1645421436,
    "data": {
        "activate" {
            "href": "/things/453AEP18F901FRJK8J1MJ10ZYR/actions/activate/6CTAX0F1M01FRJKZ1DJXG5T3ZS",
            "timeRequested": "2022-02-21T05:30:36Z",
            "status": "received"
        }
    }
}

The href item is required for further processing by the core services of the ECP and is constructed as follows: /things/<thingID>/actions/<action>/<actionID>.

The status item will update the state of the action request. When the third party service has received an action request this status should be updated to received.

With the action completed successfully, an actionStatus message needs to be published with status=completed to the ase.exchange.telemetry exchange as follows:

AMQP headers:

messageType=actionStatus
publishTag=raw
thingID=453AEP18F901FRJK8J1MJ10ZYR

AMQP message body:

{
    "thingId": "453AEP18F901FRJK8J1MJ10ZYR",
    "timestamp": 1645421439,
    "data": {
        "activate" {
            "href": "/things/453AEP18F901FRJK8J1MJ10ZYR/actions/activate/6CTAX0F1M01FRJKZ1DJXG5T3ZS",
            "timeRequested": "2022-02-21T05:30:36Z",
            "timeCompleted": "2022-02-21T05:30:39Z",
            "status": "completed"
        }
    }
}

However, if the action was not successful, the event should not be published and the final actionStatus message should be sent with status=failed instead.

Property Message Processing

    "uid": "RJK8J1453AEP18F901FMJ10ZYR",
    "properties: {
        "pollSeconds": {
            "title": "Poll Seconds",
            "type": "integer",
            "readOnly": false
        }
    }