1. Home
  2. Facilio MQTT- Push Json format

Facilio MQTT- Push Json format

The below document details the JSON format for pushing the data to the Facilio cloud through MQTT protocol.

Work Flow

  1. 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
    1. Set proper LastWillMessage while establishing the connection itself.
  2. 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-exists, the clientId should be unique and share the new clientId with Facilio Inc to authorize the same.
  3. After successful MQTT connection, publish the Birth JSON as the first JSON to the cloud.
  4. Then ,Controller JSON should be publish to the cloud with all the points json belong to that controller. If more controllers are there, make sure to push a Controller JSON for each controller.
  5. Then, Data JSON should be pushed to the cloud with the points and their values.The Data JSON can push data for points belonging to multiple controller at one also. If needed they can also be pushed as separate JSON. This Data JSON should be pushed in regular time intervals (15 mts ) with the latest values for the points.
  6. Note: If the controllers are other than Bacnet,OPC or Modbus use controllerType 0 in the following messages wherever required.

Birth JSON

  1. This is the JSON which needs to be sent after establishing every MQTT connection with the cloud.
  2. Publish type should be set to 2(which denotes connection message).

JSON Schema

{
  “$schema”: “http://json-schema.org/draft-07/schema#”,
  “type”: “object”,
  “properties”: {
    “publishType”: {
      “type”: “integer”,
      “description”:“Publish type enum”,
      “const”:2
    },
    “agent”: {
      “type”: “string”,
      “description”:“Name of the agent”
    },
    “timestamp”: {
      “type”: “integer”,
      “description”:“Timestamp in milliseconds”
    },
    “status”: {
      “type”: “integer”,
      “description”:“status enum”,
      “const”:1
    },
“version”: {
      “type”: “string”,
      “description”:“Version of the agent”
    },
“systemProps”: {
      “type”: “object”,
      “description”:“Environment and runtime information as JSON object”
    },
  },
  “required”: [
    “publishType”,
    “agent”,
    “timestamp”,
    “status”
  ]
}

 

Sample Birth JSON

{
          “agent”:“agent-name”,
          “publishType”:2,
          “interval”:15,
          “status”:1,
          “timestamp”:1579853177553
}

 

Controller JSON

  1. This is the JSON type which needs to be published to the cloud after the birth JSON.
  2. The purpose of this message is to notify the server about all the controllers in the network.
  3. This JSON can be sent once during the first time connection establishment for the discovery/identification of the controller or if there are any changes in it’s properties. 
  4. This JSON data need not be pushed at regular intervals or for every restart or reconnection of the agent.
  5. “publishType” should be set to 7 (which denotes controllers).

JSON Schema

{
  “$schema”: “http://json-schema.org/draft-07/schema#”,
  “type”: “object”,
  “properties”: {
    “agent”: {
      “type”: “string”
    },
    “data”: {
      “type”: “array”,
      “items”: [
        {
          “type”: “object”,
          “properties”: {
            “controller”: {
              “type”: “object”,
“properties”:{

“name”: {
“type”: “string”,”description”:”Name of the controller”}
},
“required”: [
“name”
]

            }
          },
          “required”: [
            “controller”,
“controllerType”
        
          ]
        }
      ]
    },
    “publishType”: {“type”: “integer”,“const”: 7},
“controllerType”: {
“type”: “integer”,
“description”:”controller type of the controllers”
},

    “timestamp”: {
      “type”: “integer”,
      “description”:“Timestamp in milliseconds”
    }
  },
  “required”: [
    “agent”,
    “data”,
    “publishType”,
    “timestamp”
  ]
}

 

Sample Controller JSON

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

Points JSON

  1. This message is used to notify the facilio cloud about the points in each of its controller.
  2. It has to be sent if any new points are added or if configurations of the point have changed.
  3. Note the “publishType” should be 4 (which denotes points).

JSON 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. 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”
  ]
}

Sample Points JSON

{
“agent”: “agent-name”,
“controller”: {
“name”: “controller-name-1”
},
“data”: [
{
“name”: “point-name-1”,
“path”: “path/of/point-name-1”
},
{
“name”: “point-name-2”,
“path”: “path/of/point-name-2”
}
],
“controllerType”: 0,
“publishType”: 4
}

Data JSON

  1. This is the JSON which needs to be pushed at regular intervals(say 15 mts), which contains the name & value of the points.
  2. Each controller has to publish one time series json containing all the point names and values.
  3. “publishType” should be set to 6 (which denotes timeseries message).

JSON 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 has only one element containing point name and its value as key value pairs”
        }
      ]
    },
    “controllerType”: {
      “type”: “integer”,
      “description”: “Controller Type enum”,
      “enum”: 5
    },
    “publishType”: {
      “type”: “integer”,
      “description”: “Publish Type enum”,
      “const”: 6
    },
    “timestamp”: {
      “type”: “integer”,
      “description”: “timestamp in milliseconds”
    }
  },
  “required”: [
    “agent”,
    “controller”,
    “data”,
    “controllerType”,
    “publishType”,
    “timestamp”
    ]
 }

 

Sample Data JSON

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

Last Will Message

  1. This message will be pushed by the mqtt broker if the agent losts connection with the broker. This last will message should be set during the connection establishment. 
  2. The cloud will use this Last Will Message to generate alert(s),when there is a connection loss between the agent and the cloud.

JSON schema

{
  “$schema”: “http://json-schema.org/draft-07/schema#”,
  “type”: “object”,
  “properties”: {
    “publishType”: {
      “type”: “integer”,
      “description”:“Publish type enum”,
      “const”:2
    },
    “agent”: {
      “type”: “string”,
      “description”:“Name of the agent”
    },
    “timestamp”: {
      “type”: “integer”,
      “description”:“Timestamp in milliseconds”
    },
    “status”: {
      “type”: “integer”,
      “description”:“status enum 0 denotes connection lost”,
      “const”:0
    }
  },
  “required”: [
    “publishType”,
    “agent”,
    “timestamp”,
    “status”
  ]
}

 

Sample Last Will JSON

{
          “agent”:“agent-name”,
          “publishType”:2,
          “interval”:15,
          “status”:0,
          “timestamp”:1579853177553
}

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

Was this article helpful?