Two way agent communication specifications with MQTT

Welcome to the Facilio Two Way Agent MQTT messages documentation!

Using the certificate files & private key obtained from Facilio for your organization, establish a MQTT connection to Facilio’s AWS MQTT server. Please refer AWS IoT SDK

Set proper LastWillMessage while establishing the connection itself.

Endpoint, clientId, topic to establish a MQTT connection will be available in faciio.config file provided along with the certificate files. If multiple agents are going to co-exist, the clientId should be unique and share the new clientId with Facilio Inc to authorize the same. Use client id as agent name.

Enums

Publish Types

Enum	Publish Type
0	CUSTOM
1	ACK
2	AGENT
3	COV
4	DEVICE_POINTS
5	EVENTS
6	TIMESERIES
7	CONTROLLERS
8	AGENT_EVENTS

Connection Status

Enum	Connection Status
0	CONNECTION_LOST
1	CONNECTED
2	SUBSCRIBED
3	DISCONNECTED
4	CONNECTION_ACTIVE

Controller Types

Enum	Controller Type
0	MISC
1	BACNET_IP
2	BACNET_MSTP
3	NIAGARA
4	MODBUS_IP
5	MODBUS_RTU
6	OPC_XML_DA
7	OPC_UA
8	LON_WORKS
9	KNX
10	CUSTOM
11	REST

Connection

Birth and Last Will:

Sample Birth Message

{
    "agent":"agent-name",
    "status":1,
    "msgid":"1001",
    "publishType":2
}

Sample Subscribtion Success Message

{
    "agent":"agent-name",
    "status":2,
    "msgid":"1001",
    "publishType":2
}

Sample Last Will Message

{
    "agent":"agent-name",
    "status":0,
    "msgid":"1002",
    "publishType":2
}

When an agent is connected for the first time it responds with two acknowledgement messages one acknowledging the connection establishment (BirthJSON/CONNECTED ack) and the next acknowledging the subscription (SUBSCRIBED ack) to the topic,only if the agent supports two way communication.

On the abrupt disconnection of the agent from the facilio mqtt broker, the broker DISCONNECTED ack/LastWillMessage.

The last will message will be set during the connection establishment itself.

Status codes

Connection Status	Codes
CONNECTION_LOST	0
CONNECTED	1
SUBSCRIBED	2
DISCONNECTED	3
CONNECTION_ACTIVE	4

Commands, Responses and Acknowledgements:

Sample Command Received ACK

{
    "agent": "agent-name",
    "publishType": 1,
    "msgid": 1725,
    "command": 255,
    "status": 120,
    "timestamp": 1598451824244
}

Sample Command Processing ACK

{
    "agent": "agent-name",
    "publishType": 1,
    "msgid": 1725,
    "command": 255,
    "status": 130,
    "timestamp": 1598451824244
}

Sample Command Executed ACK

{
    "agent": "agent-name",
    "publishType": 1,
    "msgid": 1725,
    "command": 255,
    "status": 140,
    "timestamp": 1598451824244
}

Sample Command Execution Failed ACK

{
    "agent": "agent-name",
    "publishType": 1,
    "msgid": 1725,
    "command": 255,
    "status": 150,
    "timestamp": 1598451824244
}

Commands are JSON messages originated from the server, targeting a specific agent. On receiving the command, a two way agent will receive, process and respond accordingly. Once a command is received ,it should respond with a MESSAGE_RECEIVED acknowledgement. Then with a MESSAGE_PROCESSING acknowledgement. If the processing is successful, it should respond with an appropriate RESPONSE and MESSAGE_PROCESSING_SUCCESS acks. If unsuccessful it should respond with a MESSAGE_PROCESSING_UNSUCCESSFUL ack

Command List

Command	Code
PING	110
SHUTDOWN	112
UPGRADE	114
PROPERTY	116
THREAD_DUMP	118
STATS	119
DISCOVER_CONTROLLERS	151
ADD_CONTROLLER	152
EDIT_CONTROLLER	153
DISCOVER_POINTS	251
CONTROLLER_STATUS	253
CONFIGURE	255
REMOVE	257
RESET	259
GET	331
SET	333
SUBSCRIBE	335
UNSUBSCRIBE	337

ACK List

ACK	Code
MESSAGE_SENT	110
MESSAGE_RECEIVED	120
MESSAGE_PROCESSING	130
MESSAGE_PROCESSING_SUCCESS	140
MESSAGE_PROCESSING_FAILED	150
MESSAGE_DUPLICATE	160
MESSAGE_INVALID	170

Discover Controllers

Command Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "command": {
      "type": "integer",
      "description": "Command enum",
      "const": 151
    },
    "msgid": {
      "type": "integer",
      "description": "Message ID , will be used to send the ACKs"
    },

    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 4
    }
  },
  "required": [
    "agent",
    "command",
    "msgid",
    "type",
    "publishType"
  ]
}

Command Sample

{
  "agent": "agent-name",
  "command": 151,
  "msgid": 1000,
  "type":1
}

Agent Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
            "properties": {
                "controller": {
                    "type": "string",
                    "description": "controller object of the specific controller type"
                }
            },
            "required":["controller","controllerType"   ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 7
    }
  },
  "required": [
    "agent",
    "data",
    "controllerType",
    "publishType"
  ]
}

Agent Response Sample

{
    "agent": "agent-name",
    "data": [
        {
            "controller": {"name": "controller-name-1"},
            "controllerType": 0
        },
        {
            "controller": {"name": "controller-name-2"},
            "controllerType": 0
        }
    ],
    "publishType": 7
}

This command discovers available controllers in the agent and publishes it to the cloud. Some protocols don't support controller discovery. Instead they can be added by add controller command.

Discover Points

Command Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "command": {
      "type": "integer",
      "description": "Command enum",
      "const": 251
    },
    "msgid": {
      "type": "integer",
      "description": "Message ID , will be used to send the ACKs"
    },
    "controller": {
      "type": "object",
      "description":"This object depends on the type of the controller",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        },
        "required":["name"]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    }
  },
  "required": [
    "agent",
    "command",
    "controller",
    "controllerType"
  ]
}

Command Sample

{
  "agent": "agentName",
  "command": 251,
  "controller": {
      "name": "controller-name-1"
    },
  "controllerType": 0
}

Agent Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description":"Name of the agent"
    },
"controller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },"required": ["name"]
},
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description":"This object depends on the controller type",
          "properties": {
            "name": {
              "type": "string","description":"Name of the point"
            },
            "path": {
                "type": "string","description":"path of the point. If there is no path, name can be used here"
            }
          },
          "required":["name"]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description":"Controller Type enum",
      "const":0
    },
    "publishType": {
      "type": "integer",
      "description":"Publish Type enum",
      "const":4
    }
  },
  "required": [
    "agent",
    "controller",
    "data",
    "controllerType",
    "publishType"
  ]
}

Agent Response Sample

{
    "agent": "agent-name",
    "controller": {
        "name": "controller-name-1"
    },
    "data": [
    {
        "name": "point-name-1"
    },
    {
        "name": "point-name-2"
    }
],
    "controllerType": 0,
    "publishType": 4
}

This command discovers all the data points under a controller and responds with a list of all found data points. Can discover points for only one controller at a time.

Configure Points

Command Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "command": {
      "type": "integer",
      "description": "Command enum",
      "const": 255
    },
    "msgid": {
      "type": "integer",
      "description": "Message ID , will be used to send the ACKs"
    },
    "controller": {
      "type": "object",
      "description":"This Object depends on the type of controller"
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      "required": [
        "name"
      ]
    },
    "points": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description":"The point object depends on the controller type",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the point"
            }
          },
          "required": [
              "name"
          ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 4
    }
  },
  "required": [
    "agent",
    "command",
    "msgid",
    "controllerType",
    "points",
    "publishType"
  ]
}

Command Sample

{
  "agent": "agent-name",
  "controllerType": 1,
  "msgid": 1720,
  "command": 255,
  "controller": {
    "name": "controller-name-1"
  },
  "points": [
    {
      "name": "point-name-1"
    },
    {
      "name": "point-name-2"
    }
  ],
   "timestamp": 1598440113417,
}

Agent Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "controller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },
      "required": [
        "name"
      ]
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description":"The data array should have only one item consisting for points names as keys and boolean as configure status"
          },
          "required": [
            "instanceNumber",
            "instanceType"
          ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 1
    }
  },
  "required": [
    "agent",
    "controller",
    "data",
    "controllerType",
    "publishType"
  ]
}

Agent Response Sample

{
  "controller": {
    "name": "controller-name-1"
  },
  "agent": "rmzbangalore",
  "data": [
    {
      "point-name-1": true,
      "point-name-2": true
    }
  ],
  "publishType": 1,
  "controllerType": 0
}

Not every point that is discovered needs to push data to Facilio. Configure points command is used to select only the points for which the data should be pushed. For protocols that do not support discovery of points, configuring points means just adding points. The command just passes all the parameters about points and gets back all the configured points as response.

Time Series

Timeseries Schema

    {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "controller": {
      "type": "object",
      "description": "This object depends on the controller type",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },
      "required": [
        "name"
      ]
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description": "The data array has only one element containing point name and its value as key value pairs"
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 6
    },
    "timestamp": {
      "type": "integer",
      "description": "timestamp in milliseconds"
    }
  },
  "required": [
    "agent",
    "controller",
    "data",
    "controllerType",
    "publishType",
    "timestamp"
  ]
}

Timseries Sample

    {
      "agent": "agent-name",
      "controller":{
            "name": "controller-name-1"
      },
      "data":[
               { 
                   "point-name-1":10.0,
                   "point-name-2":0
                }
       ],
      "controllerType": 0,
      "timestamp": 1592837420,
      "publishType": 6
}

This is the message that should be published in regular intervals from the agent to Facilio cloud. It contains live data with point names and values as key value pairs and has publish type 6

Set Value

Command Schema


{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "command": {
      "type": "integer",
      "description": "Command enum",
      "const": 333
    },
    "msgid": {
      "type": "integer",
      "description": "Message ID , will be used to send the ACKs"
    },
    "controller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },
      "required": [
        "name"
      ]
    },
    "points": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the point"
            },
            "value": {
              "type": "object",
              "description": "Value of the point"
            },
          },
          "required": [
            "name",
            "value"
          ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 4
    }
  },
  "required": [
    "agent",
    "command",
    "msgid",
    "controllerType",
    "points",
    "publishType"
  ]
}

Command Sample

{
  "agent": "agent-name",
  "command": 333,
  "msgid": 72,
  "controllerType":4,
  "controller": {
      "name": "controller-name-1"
   },
  "points": [
    {
      "name": "point-name-1",
      "value": 100,
    }
  ],
  "publishType": 4
}

Agent Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "controller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },
      "required": [
        "name"
      ]
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the point"
            },
            "value": {
              "type": "object",
              "description": "Value of the point"
            },
          },
          "required": [
            "name",
            "value"
          ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 4
    }
  },
  "required": [
    "agent",
    "controller",
    "points",
    "controllerType",
    "publishType"
  ]
}

Agent Response Sample

{
  "agent": "agent-name",
  "controller": {
    "name": "controller-name-1"
  },
  "controllerType": 0,
  "publishType": 3,
  "data": [
    {
      "value": 100,
      "name": "point-name-1"
    }
  ]
}

This command sets a value to the point/set of points and responds with the current value of the point.

In addition to above commands, the concept of COV can be implemented with subscribe/unsubscribe points command. If a point in agent is subscribed, values for that point must be published only when there occured any change in its value. It will be helpful in real time monitoring, as the point value is pushed instantly to the cloud on change, instead of regular intervals.

Command Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "command": {
      "type": "integer",
      "description": "Command enum. 355 for subscribe, 357 for unsubscribe",
      "enum": [335,337]
    },
    "msgid": {
      "type": "integer",
      "description": "Message ID , will be used to send the ACKs"
    },
    "controller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },
      "required": [
        "name"
      ]
    },
    "points": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description":"This object depends on the controller type",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the point"
            },
            "path": {
              "type": "string",
              "description": "Name of the point"
            }
          },
          "required": [
            "name","path"
          ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 4
    }
  },
  "required": [
    "agent",
    "command",
    "msgid",
    "controllerType",
    "points",
    "publishType"
  ]
}

Command Sample

{
  "agent": "agent-name",
  "command": 335,
  "msgid": 1007,
  "controllerType": 0,
  "controller": {}
      "name": "spinfo_23"
  }, 
  "points": [
    {
      "name": "point-name-1",
      "path": "path/of/the/point1
    },
    {
      "name": "point-name-2",
      "path": "path/of/the/point2
    }
  ],
  "publishType": 4
}

Agent Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "controller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      "required": [
        "name"
      ]
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the point"
            },
            "path": {
              "type": "string",
              "description": "path of the point"
            },
            "subscribed": {
              "type": "boolean",
              "description": "true if subscribed/false if unsubscribed"
            }
          },
          "required": [
            "name","path","subscribe"
          ]
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 1
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 4
    }
  },
  "required": [
    "agent",
    "controller",
    "data",
    "controllerType",
    "publishType"
  ]
}

Agent Response Sample

{
  "agent": "agent-name",
  "controller": {
      "name":"controller-name-1"
  }
  "controllerType": 0,
  "publishType": 4,
  "data": [
    {
      "name": "point-name-1",
      "path": "path/of/the/point1",
      "subscribed": true
    },
    {
      "name": "point-name-2",
      "path": "path/of/the/point2",
      "subscribed": false
    }
  ]
}

This command subscribes/unsubscribes any point/points in a controller.

COV Message

COV Schema

 {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Name of the agent"
    },
    "controller": {
      "type": "object",
      "description": "This object depends on the controller type",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the controller"
        }
      },
      "required": [
        "name"
      ]
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description": "The data array has only one element containing point name and its value as key value pairs"
        }
      ]
    },
    "controllerType": {
      "type": "integer",
      "description": "Controller Type enum",
      "const": 0
    },
    "publishType": {
      "type": "integer",
      "description": "Publish Type enum",
      "const": 3
    },
    "timestamp": {
      "type": "integer",
      "description": "timestamp in milliseconds"
    }
  },
  "required": [
    "agent",
    "controller",
    "data",
    "controllerType",
    "publishType",
    "timestamp"
  ]
}

COV Sample

{
      "agent": "agent-name",
      "controller":{
            "name": "controller-name-1"
      }
      "data":[
               { 
                   "point-name-1":10.0
                }
       ],
      "controllerType": 0,
      "timestamp": 1592837420,
      "publishType": 3
}

As mentioned above if a point is subscribed it pushes data only when the value gets changed. It uses the publish type 3. Agent publishes this message whenever there is a change in the value.

One way agent communication specification with Rest API

Data can be pushed to Facilio IoT platform via Rest API too. Please get the API KEY from Facilio before pushing any data via REST API.

For the timeseries data to get mapped into any asset in the platform, iot points and controllers should be created in the agent. This can be achieved either by manual onboarding or pushing appropriate data through the REST API.

Add Controllers

Push the controllers list through this to create controllers in the platform.

Endpoint

  POST  /api/v3/iot/data/push

Schema of body

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "payload": {
            "type": "object",
            "properties": {
                "agent": {
                    "type": "string",
                    "description": "Name of the agent"
                },
                "data": {
                    "type": "array",
                    "items": [
                        {
                            "type": "object",
                            "properties": {
                                "controller": {
                                    "type": "string",
                                    "description": "controller object of the specific controller type"
                                }
                            },
                            "required": [
                                "controller",
                                "controllerType"
                            ]
                        }
                    ]
                },
                "controllerType": {
                    "type": "integer",
                    "description": "Controller Type enum",
                    "const": 0
                },
                "publishType": {
                    "type": "integer",
                    "description": "Publish Type enum",
                    "const": 7
                }
            },
            "required": [
                "agent",
                "data",
                "controllerType",
                "publishType"
            ]
        }
    },
    "required": [
        "payload"
    ]
}

Body Sample

{
    "payload": {
        "agent": "agent-name",
        "data": [
            {
                "controller": {
                    "name": "controller-name-1"
                },
                "controllerType": 0
            },
            {
                "controller": {
                    "name": "controller-name-2"
                },
                "controllerType": 0
            }
        ],
        "publishType": 7
    }
}

Add Points

After adding the controllers, push the point list of each controller. The controller name should match with the name in 'add controller' message which was pushed previously.

Endpoint

  POST  /api/v3/iot/data/push

Schema of body

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "payload": {
            "type": "object",
            "properties": {
                "agent": {
                    "type": "string",
                    "description": "Name of the agent"
                },
                "controller": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Name of the controller"
                        }
                    },
                    "required": [
                        "name"
                    ]
                },
                "data": {
                    "type": "array",
                    "items": [
                        {
                            "type": "object",
                            "description": "This object depends on the controller type",
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "description": "Name of the point"
                                },
                                "path": {
                                    "type": "string",
                                    "description": "path of the point. If there is no path, name can be used here"
                                }
                            },
                            "required": [
                                "name",
                                "path"
                            ]
                        }
                    ]
                },
                "controllerType": {
                    "type": "integer",
                    "description": "Controller Type enum",
                    "const": 0
                },
                "publishType": {
                    "type": "integer",
                    "description": "Publish Type enum",
                    "const": 4
                }
            },
            "required": [
                "agent",
                "controller",
                "data",
                "controllerType",
                "publishType"
            ]
        }
    },
    "required": [
        "payload"
    ]
}

Body Sample

{
    "payload": {
        "agent": "agent-name",
        "controller": {
            "name": "controller-name-1"
        },
        "data": [
            {
                "name": "point-name-1"
            },
            {
                "name": "point-name-2"
            }
        ],
        "controllerType": 0,
        "publishType": 4
    }
}

Timeseries

Once controllers have been created successfully. Timeseries data can be pushed periodically. The controller name and the point names should match with the details pushed previously. i.e Add controllers and Add Points.

Endpoint

  POST  /api/v3/iot/data/push

Schema of body

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "payload": {
            "type": "object",
            "properties": {
                "agent": {
                    "type": "string",
                    "description": "Name of the agent"
                },
                "controller": {
                    "type": "object",
                    "description": "This object depends on the controller type",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Name of the controller"
                        }
                    },
                    "required": [
                        "name"
                    ]
                },
                "data": {
                    "type": "array",
                    "items": [
                        {
                            "type": "object",
                            "description": "The data array has only one element containing point name and its value as key value pairs"
                        }
                    ]
                },
                "controllerType": {
                    "type": "integer",
                    "description": "Controller Type enum",
                    "const": 0
                },
                "publishType": {
                    "type": "integer",
                    "description": "Publish Type enum",
                    "const": 6
                },
                "timestamp": {
                    "type": "integer",
                    "description": "timestamp in milliseconds"
                }
            },
            "required": [
                "agent",
                "controller",
                "data",
                "controllerType",
                "publishType",
                "timestamp"
            ]
        }
    },
    "required": [
        "payload"
    ]
}

Body Sample

{
    "payload": {
        "agent": "agent-name",
        "controller": {
            "name": "controller-name-1"
        },
        "data": [
            {
                "point-name-1": 10.0,
                "point-name-2": 0
            }
        ],
        "controllerType": 0,
        "timestamp": 1592837420,
        "publishType": 6
    }
}

Events

Events associated with any asset can be pushed. It should follow the given schema.

Endpoint

  POST  /api/v3/iot/data/push

Schema of body

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "payload": {
            "type": "object",
            "properties": {
                "agent": {
                    "type": "string",
                    "description": "Name of the agent"
                },
                "publishType": {
                    "type": "number",
                    "const": 8
                },
                "source": {
                    "type": "string",
                    "description": "Asset name"
                },
                "state": {
                    "type": "string",
                    "enum": [
                        "critical",
                        "major",
                        "minor",
                        "warning",
                        "clear"
                    ],
                    "description": "Severity of the event critical being highest and warning being lowest and clear represents normal"
                },
                "condition": {
                    "type": "string",
                    "description": "value to depict the exact entity/part of the asset.t"
                },
                "message": {
                    "type": "string",
                    "description": "short description of the event"
                },
                "timestamp": {
                    "type": "number",
                    "description": "timestamp of the data"
                }
            },
            "required": [
                "agent",
                "publishType",
                "source",
                "state",
                "message",
                "timestamp"
            ]
        }
    },
    "required": [
        "payload"
    ]
}

Body Sample

{
    "agent": "Win-A86F-4D3B-A6D7-C8B4",
    "publishType": 8,
    "source": "Block A-FLR-1-Printer-1",
    "state": "Major",
    "message": "No paper in Paper Rack",
    "condition": "Paper Rack",
    "timestamp": 1610355845268
}

Body Sample Without Condition

{
    "agent": "Win-A86F-4D3B-A6D7-C8B4",
    "publishType": 8,
    "source": "Block A-FLR-1-Printer-1-Paper Rack",
    "state": "Major",
    "message": "No paper in Paper Rack",
    "timestamp": 1610355845268
}

Two way agent communication specifications with MQTT

Enums

Publish Types

Connection Status

Controller Types

Connection

Birth and Last Will:

Status codes

Commands, Responses and Acknowledgements:

Command List

ACK List

Discover Controllers

Discover Points

Configure Points

Time Series

Set Value

Subscribe/Unsubscribe COV

COV Message

One way agent communication specification with Rest API

Add Controllers

Add Points

Timeseries

Events