1. Home
  2. Docs
  3. User Guides
  4. Avimesa Group API (AMQP)

Avimesa Group API (AMQP)

last updated 2019-Mar-21

Introduction

This project contains the Avimesa Group API documentation. The purpose of this documentation is to describe the API available for the Avimesa Group clients. The Group API (AMQP) in general can be seen as a JSON based protocol that uses Avimesa-configured RabbitMQ for messaging and provides the ability to interface with the Avimesa system.

Table of Contents

The following lists larger API updates. See github for complete changelog of the smaller changes.

API Version Change
0.10 Initial release on github
0.11 – Changed CMD 1XXX responses. Instead of a generic “message” arrary of strings, the response is now a JSON object that is easier to consume

1. Summary

1.1 Overview

The Group API supports the following:

Direct Device Interaction – Ability to consume/subscribe to device data (raw/notification) – Queue based data access – Ability to actuate devices (i.e. send commands that elicit a device action)

Device Management and Provisioning – Ability provision and remove devices – Ability to set a device script and configuration – Ability to reset device authentication keys – Ability to list devices/device files

Device and System Administration – update device firmware (support for Avimesa 1000, but in general provides agnostic DFU style operations) – view system logs

Security – TLS1.2 – Group Level Authentication (128-bit ID/128-bit Auth Key)

1.2 Client Examples

Client examples showing various use cases are available in source code form are located here:

1.3 References

Document Summary
Avimesa_RMQ_Design.pdf Detailed information about the RabbitMQ configuration and interface, target audience being a developer. Can be used in conjunction with this document when building an Infrastructure client.
Avimesa_DialTone_Protocol.pdf Detailed information about the DialTone protocol

Table 1

1.4 Terminology

Term Meaning
Group A term that is typically used to represent a single customer, it’s a logical grouping of Devices for an end user, and can be represented with a single Group ID
Device Typically a system in the field that communicates with the Device Cloud.
vhost Virtual Host – a data isolation mechanism that allows Groups to be isolated from each other (i.e. customer X can’t access customer Y’s data). Other uses include an Infrastructure interface.
Core Architecture In this scope, represents a collection of hardware and software that facilitates Device to Device Cloud communications and messaging.
Infrastructure Architecture In this scope, represents software systems that facilitate account creation, maintenance and accounting bookkeeping of Device to Device Cloud transactions.

Table 2

Top

2. Components

2.1 Avimesa Core Architecture

In general, the Avimesa architecture can be viewed as follows for the scope of this document.

fig1
Figure 1

2.1.1 Devices

In the scope of this document, a device is something that provides data that the Group wants to know about, is uniquely identified and authenticated against, and is configured via the Group vhost. The Device’s data will make its way through the system and will be available to the client application.

2.1.2 Device Cloud Servers

In the scope of this document, the Device Cloud server manage all device communications, device authentication and hosting of the device runtimes.

2.1.3 Script Engine

A JavaScript program is executed on each device transaction (connection) by a Device Driver Script Engine. It provides the ability to send data to the Group vhosts data queues. In the scope of this document, it should be known that if the script does not manipulate the data models, than the default Avimesa DialTone formatted JSON can be expected in the data queues.

The script can also pull device actuations out of the Device’s queue and relay to the device. In general, the script provides:

  • a JavaScript runtime for business logic
  • Access to the device’s data/state
  • Access to write to data queues (raw/notification)
  • Access to Read from device’s actuation queue
  • Some file I/O for hysteresis

The script allows for the data models to be manipulated and thus can be considered a data adapter.

In general, it’s easy to think of this script as a filtering and priority setting mechanism for data.

2.1.4 Group vhosts

A “Group vhost” is created per Group (customer). This vhost provides the end user access to their device data, device configuration and administration. In the context of this document, a Group vhost should be considered the bridge between a customer application and their devices. The customer’s application is responsible for connecting to the Group vhost using the various RMQ clients available (or writing their own). Avimesa has examples in various languages. The credentials to connect to the Group vhost are configured at the time of Group creation, which as of now is an Avimesa internal service.

2.1.5 Group vhost Client

An application that interfaces with the Group vhost needs to use (or build) a RabbitMQ client using AMQP 0-9-1. The thought is this document provides the necessary information to assist in designing a Group client.

Top

3. Recommended Client Usage

The following is provided to give an overall sense of the Group API’s usage. When the Avimesa Infrastructure API is used to create a new Group (Customer), the Group’s vhost is created, the end user is given credentials, and the API is available for use.

Top

3.1 Example

Complete examples of a simple client usage are located here:

Top

3.2 Data Consumer Worker

fig3
Figure 3

  • The Avimesa queues should be considered ‘temporary’ storage and ‘offloaded’ on a periodic basis to a data store
  • A worker should subscribe or consume data from the raw and notification data queues The data in the raw and notification queue can be populated via the Device’s script through the JavaScript API
  • The format of the JSON data will be Avimesa’s DialTone unless it is re-formatted via the Device’s script, in which is can be anything the user desires (in JSON)

Top

3.3 Device Actuation Process

fig4
Figure 4

  • A Device Actuation Process should be considered as something that can generate commands for specific devices based upon the DialTone JSON protocol
  • Device’s can be ‘actuated’ (commands sent to have an action take place on the device) by having an application send the JSON command to the Device’s queue via the actuation exchange
  • The Device may obtain the JSON command via the Device’s script through the JavaScript

Top

3.4 Syslog Consumer Worker

fig5
Figure 5

  • The Avimesa queues should be considered ‘temporary’ storage and ‘offloaded’ on a periodic basis to a data store
  • A worker should subscribe or consume data from the system log queues
  • The information in this queue should be viewed as system log type information, error conditions, etc.
  • The format of the JSON data will be Avimesa’s DialTone

Top

3.5 Admin Worker Process

Summary

fig6
Figure 6

Most of the Group API can be seen as a client sending ‘admin’ commands to the system, and processing the response to these commands. In general, messages are sent to the admin_in_q queue via the admin.dx exchange with a routing key of in. The client can check for the response in two ways, described below.

Remote Procedure Call (RPC)

The RPC approach is clean and allows for clients to easily get responses only to the commands it sends. This is useful for ‘multi-tenant’ use cases.

In general, this is the usage model, with a source code example available here, please see the sendAdminCmd function.

  • a connection is created (channel)
  • create a random correlationId (request ID) (I use a random 32 bit number in string form)
  • create a new temporary queue; nameless, exclusive, 60 second expiration, autodelete
  • begin to consume on that new queue (subscribe)
  • publish the message to admin.dx exchange, routing key = in, set options on the message to have the replyTo property set to the temporary queue name and correlationID to ID created above. The temporary queue will have a name like “amq.gen-“
  • Once you receive the response in the temporary queue, close the connection, and the temporary queue should go away.

Note: the admin_out_q is not used at all in this usage model.

Single Consumer Usage

It may suffice to have a single consumer of all admin command responses.

  • An Admin Worker process is responsible for both generating and sending admin commands following the DialTone JSON format and processing the responses via a response in a queue
  • This function is asynchronous in nature and should use the DialTone’s request ID to process the response
  • JSON requests are sent to the admin exchange (admin.dx) with a routing key (in) following the DialTone JSON format to perform actions on the system
  • The responses to the requests are available to be subscribed to or consumed from the admin out queue (admin_out_q)

Top

4. Group API

Top

4.1 General Data Flow

4.1.1 AMQP Permissions

The default Group API permissions are as follows, which allow resources to be configured if they follow the ‘nameless’ pattern, and full read/write access.

"amq.gen-.*" ".*" ".*"

For the RabbitMQ specifics, please reference Avimesa_RMQ_Design.pdf.

4.1.2 Command Requests (Admin In)

Requests are sent to a RMQ Exchange via the following RMQ settings:

vhost Provided to user
Host rmqserv001.avimesa.com
Port 5671
Credentials Provided to user
Exchange Name = “admin.dx”, Type = Direct, Passive = True
Routing Key “in” (for admin in)

4.1.3 Command Response (Admin Out)

Responses are available by default via the following RMQ settings. It should be noted that a nice RPC style approach can be used instead where a temporary response queue is created and used for the commands response. See

vhost Provided to user
Host rmqserv001.avimesa.com
Port 5671
Credentials Provided to user
Queue Name = admin_out_q, Passive = True, Durable = True

4.1.4 Raw Data Subscription

Raw data records are published and can be subscribed to. The consumer should acknowledge the message once consumed.

vhost Provided to user
Host rmqserv001.avimesa.com
Port 5671
Credentials Provided to user
Queue Name = raw_q, Passive = True, Durable = True

4.1.5 Notification Data Subscription

Notification data records are published and can be subscribed to. The consumer should acknowledge the message once consumed.

vhost Provided to user
Host rmqserv001.avimesa.com
Port 5671
Credentials Provided to user
Queue Name = not_q, Passive = True, Durable = True

4.1.6 System Log Data Subscription

System log data records are published and can be subscribed to. The consumer should acknowledge the message once consumed.

vhost Provided to user
Host rmqserv001.avimesa.com
Port 5671
Credentials Provided to user
Queue Name = sys_log_q, Passive = True, Durable = True

Top

4.2 List Devices – Command 1002

Summary

Requests to list the Devices in the Group.

Request Example (1002)

{
   "api_maj": 0,
   "api_min": 11,
   "cmd_id": 1002,
   "req_id": 123456
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response

Response Example (1003)

{
    "api_maj": 0, 
    "api_min": 11,
    "cmd_id": 1003,
    "req_id": 123456,
    "response": {
        "error": 0,
        "message": {
            devices : [
                "20010db80000000053d371fffe53dc33",
                "20010db80000000053d371fffe53dc34",
                "20010db80000000053d371fffe53dc35" 
            ]
        }
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object Yes (see next section)
Name Type Required Notes
devices Arrary Yes An array of “Device ID” strings

Top

4.3 Add a Device – Command 1004

Summary

Requests to add a Device to the Group.

Request Example (1004)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1004,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6"
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID to add

Response Example (1005)

{
    "api_maj": 0, 
    "api_min": 11, 
    "cmd_id": 1003, 
    "req_id": 123456, 
    "response": {
        "error": 0,
        "message": {
            "device_id" : "20010db800000000f7706ffffe1e34c6"
            "auth_key" : "2ff87d3a0d064d278ecff756aa57ebf6"
        }
    }
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object Yes (see next section)
Name Type Required Notes
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID to added
auth_key String Yes The Authentication Key

Top

4.4 List a Device’s Files – Command 1006

Summary

Requests to list a Device’s files.

Request Example (1006)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1006,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6"
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID to add

Response Example (1007)

{
    "api_maj": 0, 
    "api_min": 11, 
    "cmd_id": 1007, 
    "req_id": 123456,
    "response": {
        "error": 0, 
        "message": {
            "files" : [
                {
                    "path" : "/scripts/script.js",
                    "size" : 590,
                    "time" : 1536350169
                },
                {
                    "path" : "/config/config.js",
                    "size" : 1169,
                    "time" : 1536350193
                }
            ]
        }
    }
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object Yes (see next section)
Name Type Required Notes
files Array Yes Will contain an array of “file” strings with the path, size (bytes) and upload time (Linux time)

Top

4.5 Upload a Device Driver Script File – Command 1008

Summary

Requests to upload a Device Drive Script file.

Request Example (1008)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1008,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6",
    “file_buf”: "ewogICJkZXZpY2VzIiA6IDEwLAogICJtb2RlIiA6IDEsCiAgInJ
        tcV9pcF9hZGRyZXNzIiA6ICIyMDcuMzYuNDYuMjEiLAogICJybXFfcG9ydCIgOiA1 NjcyLAogICJybXFfdmhvc3QiIDogIlRlc3RHcm91cCIsCiAgInJtcV91c2VyIiA6ICJhdmltZXNhX2 FkbWluIiwKICAicm1xX3Bhc3N3b3JkIiA6ICJaV 1V5TXpFNVpEUmxaVFV3TVRsbVptUTRaR0U1WlRWaiIKfQ=="
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID
file_buf String Yes Base64 encoded version of the file contents

Response Example (1009)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1009,
    "req_id": 123456,
    "response": {
        "error": 0, 
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object No (see next section)
Name Type Required Notes
status String Yes Contains status message or error message

Top

4.6 Upload a Device Configuration File – Command 1010

Summary

Request Example (1010)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1010,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6",
    “file_buf”: "ewogICJkZXZpY2VzIiA6IDEwLAogICJtb2RlIiA6IDEsCiAgInJ
        tcV9pcF9hZGRyZXNzIiA6ICIyMDcuMzYuNDYuMjEiLAogICJybXFfcG9ydCIgOiA1 NjcyLAogICJybXFfdmhvc3QiIDogIlRlc3RHcm91cCIsCiAgInJtcV91c2VyIiA6ICJhdmltZXNhX2 FkbWluIiwKICAicm1xX3Bhc3N3b3JkIiA6ICJaV 1V5TXpFNVpEUmxaVFV3TVRsbVptUTRaR0U1WlRWaiIKfQ=="
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID
file_buf String Yes Base64 encoded version of the file contents

Response Example (1011)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1011,
    "req_id": 123456,
    "response": {
        "error": 0, 
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object No (see next section)
Name Type Required Notes
status String Yes Contains status message or error message

Top

4.7 Remove a Device – Command 1012

Summary

Requests to add a Remove to the Device (and its container/files/access to the Device Cloud)

Request Example (1012)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1012,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6"
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID to remove

Response Example (1013)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1011,
    "req_id": 123456,
    "response": {
        "error": 0, 
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object No (see next section)
Name Type Required Notes
status String Yes Contains status message or error message

Top

4.8 Update a Device’s Authentication Key – Command 1014

Summary

Requests to reset to update Device authentication key. NOTE for devices like the Avimesa 1000, you’ll need to update the authentication key on the device in order for it to communicate again with the Device Cloud.

Request Example (1014)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1014,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6"
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID to update

Response Example (1015)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1015,
    "req_id": 123456,
    "response": {
        "error": 0,
        "message": {
            "device_id" : "20010db800000000f7706ffffe1e34c6"
            "auth_key" : "2ff87d3a0d064d278ecff756aa57ebf6"
        }
    }
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object Yes (see next section)
Name Type Required Notes
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID updated
auth_key String Yes The Authentication Key

Top

4.9 Upload a Device Firmware Update Package – Command 1020

Summary

Requests to upload a Device Firmware Update Pakcage file.

Currently supports:

  • Avimesa 1000 (nRF52382)

Request Example (1020)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1020,
    "req_id": 123456,
    "dev_id": "20010db800000000f7706ffffe1e34c6",
    “file_buf”: "ewogICJkZXZpY2VzIiA6IDEwLAogICJtb2RlIiA6IDEsCiAgInJ
        tcV9pcF9hZGRyZXNzIiA6ICIyMDcuMzYuNDYuMjEiLAogICJybXFfcG9ydCIgOiA1 NjcyLAogICJybXFfdmhvc3QiIDogIlRlc3RHcm91cCIsCiAgInJtcV91c2VyIiA6ICJhdmltZXNhX2 FkbWluIiwKICAicm1xX3Bhc3N3b3JkIiA6ICJaV 1V5TXpFNVpEUmxaVFV3TVRsbVptUTRaR0U1WlRWaiIKfQ=="
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Client generated Request ID to track back to a response
dev_id String, 32 char lowercase, 0-9, a-f Yes The Device ID
file_buf String Yes Base64 encoded version of the file contents

Response Example (1021)

{
    "api_maj": 0,
    "api_min": 11,
    "cmd_id": 1021,
    "req_id": 123456,
    "response": {
        "error": 0, 
    }
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
cmd_id Number, uint32 Yes Command ID
req_id Number, uint32 Yes Echoed client generated Request ID to track back to a response
response Object Yes (see next section)
Name Type Required Notes
error Number, uint32 Yes 0 for success, non-zero for error
message Object No (see next section)
Name Type Required Notes
status String Yes Contains status message or error message

Top

4.10 Actuation

Top

4.10.1 Summary

The command ID’s shift from the 1000’s series to a hexadecimal flavor. This helps distinguishing Group API commands with Device commands.

Requests are sent to a RMQ Exchange via the following RMQ settings:

vhost Provided to user
Host rmqserv001.avimesa.com
Port 5671
Credentials Provided to user
Exchange Name = “actuation.dx”, Type = Direct, Passive = True
Routing Key The Device’s ID, 32 character, lower case

Responses are provided by the device but must be forwarded by the script to a queue if you would like to act upon an ACK

Top

4.10.2 Set GPIO State – Command 0xB102

Summary

Requests to set GPIO state of the device

Request Example (0xB102)

{
    "api_maj":0,
    "api_min":11,
    "dts":1539090421,
    "dev": {
        "dev_id":"000102030405060708090A0B0C0D0E0F", 
        "dev_cmd":{
            "dev_cmd_id":45314,
            “req_id”:12345,
            "state":1,
            "mask":1
        } 
    }
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
dts Number, uint32 Yes Linux timestamp (used for filtering, can be 0…)
dev Object Yes See next section
Name Type Required Notes
dev_id String Yes The Device’s ID, 32 character, lower case
dev_cmd Object Yes See next section
Name Type Required Notes
dev_cmd_id Number, uint32 Yes he Command ID, represented in base 10
req_id Number, uint32 Yes The Request ID, used to track request to the response
state Number, uint32 Yes See below
mask Number, uint32 Yes See below

4.10.2.1 State
  • Supports up to 32 pins in the 32 bit value
  • When bit is 0 GPIO is off, when bit is 1 GPIO is on
  • For example, 0x00000003 would enable GPIO 0 and 1

4.10.2.2 Mask
  • Bit wise flags, 0 – ignore, 1 – don’t ignore.
  • For example, a mask of 0x00000001 on state of 0x00000003 Flags above would inform device to enable. GPIO 0 but not GPIO 1. This allows us to prevent disabling GPIO (e.g. request doesn’t need to have system state)

Response Example (0xB103)

NOTE: Device Driver Script needs to relay the ACK to a queue

{
    "api_maj" : 0,
    "api_min" : 11,
    "dts" : 0,
    "dev" : {
        "dev_cmd" : {
            "dev_cmd_id" : 45315,
            "req_id" : 123456, 
            }
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
dts Number, uint32 Yes Linux timestamp (used for filtering, can be 0…)
dev Object Yes See next section
Name Type Required Notes
dev_cmd Object Yes See next section
Name Type Required Notes
dev_cmd_id Number, uint32 Yes The Command ID, represented in base 10
req_id Number, uint32 Yes The Request ID, used to track request to the response

Top

4.10.3 Soft Reset – Command 0xF002

Summary

Requests to a soft reset of device

Request Example

{
    "api_maj" : 0,
    "api_min" : 11,
    "dts" : 0,
    "dev" : {
        "dev_id": “cafebabecafebabecafebabecafebabe”,
        "dev_cmd" : {
            "dev_cmd_id" : 61442,
            "req_id" : 123456 
        }
    }
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
dts Number, uint32 Yes Linux timestamp (used for filtering, can be 0…)
dev Object Yes See next section
Name Type Required Notes
dev_id String Yes The Device’s ID, 32 character, lower case
dev_cmd Object Yes See next section
Name Type Required Notes
dev_cmd_id Number, uint32 Yes The Command ID, represented in base 10
req_id Number, uint32 Yes The Request ID, used to track request to the response

Response Example

NONE IN CURRENT API

Top

4.10.4 Firmware Update Trigger – Command 0xF008

Summary

Requests to start Device Firmware Update process

Request Example (0xF008)

{
    "api_maj" : 0,
    "api_min" : 11,
    "dts" : 0,
    "dev" : {
        "dev_id": “cafebabecafebabecafebabecafebabe”, 
        "dev_cmd" : {
            "dev_cmd_id" : 61448,
            "req_id" : 123456
        }
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
dts Number, uint32 Yes Linux timestamp (used for filtering, can be 0…)
dev Object Yes See next section
Name Type Required Notes
dev_id String Yes The Device’s ID, 32 character, lower case
dev_cmd Object Yes See next section
Name Type Required Notes
dev_cmd_id Number, uint32 Yes The Command ID, represented in base 10
req_id Number, uint32 Yes The Request ID, used to track request to the response

Response Example (0xF009)

NOTE: Device Driver Script needs to relay the ACK to a queue

{
    "api_maj" : 0,
    "api_min" : 11,
    "dts" : 0,
    "dev" : {
        "dev_cmd" : {
            "dev_cmd_id" : 61449,
            "req_id" : 123456, 
            }
    } 
}
Name Type Required Notes
api_maj Number, uint16 Yes API major version (provided by Avimesa)
api_min Number, uint16 Yes API minor version (provided by Avimesa)
dts Number, uint32 Yes Linux timestamp (used for filtering, can be 0…)
dev Object Yes See next section
Name Type Required Notes
dev_cmd Object Yes See next section
Name Type Required Notes
dev_cmd_id Number, uint32 Yes The Command ID, represented in base 10
req_id Number, uint32 Yes The Request ID, used to track request to the response

Top

4.11 System Log

4.11.1 Summary

The System Log is accessed through the sys_loq_q queue. It’s very similar to the Raw (raw_q) and Notification (not_q) queues, but will generally contain system events and errors in JSON form.

4.11.2 JSON Format

{
    “evt_id” : 65539, 
    “dts” : 1539383229, 
    “dev_id” : “0e8155d8559543860000000000000001", 
    “msg” : “Encoding dev_out to JSON failed”}
}
Name Type Required Notes
evt_id Number, uint32 Yes The event ID (see below)
dts Number, uint32 Yes Linux time of event
dev_id String No The device ID that created the event (if any)
msg String Yes Additional text for the message

4.11.3 System Log Event IDs

API Events Overview – 0x00010000 (65536)
Event ID (base 16/10) Origin Notes
0x00010000 (65537) API (AMQP) General API Event
0x00011000 (69632) API (AMQP) General Infrastructure API Event
0x00012000 (73728) API (AMQP) General Group API Event
Group API Events – 0x00012000 (73728)
Event ID (base 16/10) Origin Notes
0x00012000 (73728) API (AMQP) General Group API Event
0x00012001 (73729) API (AMQP) Unknown Command Error
0x00012002 (73730) API (AMQP) Command Parsing Error
0x00012010 (73744) API (AMQP) CMD 1000 – Success
0x00012011 (73745) API (AMQP) CMD 1000 – Error
0x00012012 (73746) API (AMQP) CMD 1002 – Success
0x00012013 (73747) API (AMQP) CMD 1002 – Error
0x00012014 (73748) API (AMQP) CMD 1004 – Success
0x00012015 (73749) API (AMQP) CMD 1004 – Error
0x00012016 (73750) API (AMQP) CMD 1006 – Success
0x00012017 (73751) API (AMQP) CMD 1006 – Error
0x00012018 (73752) API (AMQP) CMD 1008 – Success
0x00012019 (73753) API (AMQP) CMD 1008 – Error
0x0001201a (73754) API (AMQP) CMD 1010 – Success
0x0001201b (73755) API (AMQP) CMD 1010 – Error
0x0001201c (73756) API (AMQP) CMD 1012 – Success
0x0001201d (73757) API (AMQP) CMD 1012 – Error
0x0001201e (73758) API (AMQP) CMD 1014 – Success
0x0001201f (73759) API (AMQP) CMD 1014 – Error
0x00012020 (73760) API (AMQP) CMD 1020 – Success
0x00012021 (73761) API (AMQP) CMD 1020 – Error
Device Cloud Events – 0x00020000 (131072)
Event ID (base 16/10) Origin Notes
0x00020001 (131073) Device Cloud Device Input parsing error
0x00020002 (131074) Device Cloud Device Driver Engine error
0x00020003 (131075) Device Cloud Device Output parsing error
0x00020004 (131076) Device Cloud Device Firmware Update (DFU) Start Event
0x00020005 (131077) Device Cloud Device Firmware Update (DFU) Progress Update
0x00020006 (131078) Device Cloud Device Firmware Update (DFU) Complete Event
0x00020007 (131079) Device Cloud Device Firmware Update (DFU) Error Event

Top

5. DialTone QuickStart

5.1 Summary

Please refer to the document Avimesa_DialTone_Protocol.docx for details

5.2 Typical Device Data

The following is provided to give an idea of what typical device data may look like when unaltered and sent from the Device runtime to the queues.

{  
   "api_maj":0,
   "api_min":11,
   "dts":1536783776,
   "dev":{  
      "dev_id":"000102030405060708090a0b0c0d0e0f",
      "dev_data":{  
         "dev_type":1,
         "fw":1,
         "hw_rev":48,
         "bat":100.00,
         "rssi":0,
         "temp":25.00,
         "dev_sts":1
      },
      "chans":[  
         {  
            "ch_idx":0,
            "ch_data":[  
               {  
                  "data_idx":0,
                  "units":1,
                  "val":0.003
               }
            ]
         },
         {  
            "ch_idx":1,
            "ch_data":[  
               {  
                  "data_idx":0,
                  "units":10,
                  "val":5.0
               }
            ]
         },
         {  
            "ch_idx":2,
            "ch_data":[  
               {  
                  "data_idx":0,
                  "units":11,
                  "val":1112014848
               }
            ]
         }
      ]
   }
}

5.3 Typical Device Configuration

The following is provided to give an idea of what typical device configuration may look like when unaltered.

{
    "api_maj": 0,
    "api_min": 11,
    "dts": 0,
    "dev": {
        "dev_id": "20010DB800000000026c01fffe5e8584",
        "dev_cfg": {
            "heartbeat": 3
        },
        "chans": [ 
            {
            "ch_idx": 0,
            "ch_cfg": {
                "ch_type": 1,
                "en": 1,
                "sched": 1,
                "sensor": {
                    "settling_time": 10
                }
            }
        }, 
        {
            "ch_idx": 8,
            "ch_cfg": {
                "ch_type": 256,
                "en": 1,
                "sched": 1,
                "sensor": {
                    "sens_flags ": 1
                }
            }
        }]
    }
}

Top