MQTT API Reference

Objective

The below document details the steps involved to connect a custom agent with Facilio cloud.

Prerequisites

  1. Obtain the certificate files & private key obtained from Facilio Inc specific to your Organization.
  2. Establish a MQTT connection to Facilio’s AWS MQTT server using the relevant AWS IoT SDK for your agent environment.
    1. Set proper WillMessage while establishing the connection itself.
  3. Endpoint, Clientid & Topic to establish a MQTT connection with the AWS cloud will be available in faciio.config file provided along with the certificate files.
  4. If multiple agents are going to co-exists for your Org, you can copy the same certificate, private key & facilio.config files for all the agents.
    1. As the clientId should be unique for each agent. You need to modify only the clientId in the facilio.config to a unique one in each agent.
    2. Share the new (modified) ClientId(s) with Facilio Inc., to authorize the same to push the data.

Agent Types

The custom agents can be one way or two way communication agents.

1.One Way Agent’s Workflow

  1. In one way communication agents, data will be pushed only from the Agent to the cloud.
  2. After successful MQTT connection, push the Agent JSON / Birth JSON as the first JSON to the cloud. May be from the onConnectionSuccess().
  3. After that ,Controller JSON should be pushed 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. This can also be done only once.
  4. After that, 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.
  5. To push a change in value of a point to the cloud, the COV JSON should be used.This need not be in regular time interval, it can be pushed then & there i.e immediately.
  6. To push an Alarm/Alert condition to the cloud, the Event JSON should be used. This JSON also, need not be in regular time interval, it should be pushed immediately.

2.Two way Agent’s Workflow

 

  1. In two way communication agents, data will be pushed from the Agent to the cloud and the commands will be pushed from the cloud to the Agent.
  2. After successful MQTT connection, push the Agent JSON / Birth JSON as the first JSON to the cloud
  3. In case of two way communication, the agent should listen for the messages & commands from the cloud.
  4. To listen to those messages, the agent should perform a MQTT subscription to a topic : topic/msgs
    For example, if your initial connection topic is “xyz”, then you have to subscribe to a new topic “xyz/msgs” to listen to the messages and commands from the cloud.
  5. After successful subscription to the cloud, push the Subscribed JSON to the cloud.
  6. Now the Agent is capable of listening to the cloud’s command & messages.
  7. Once the agent is subscribed/listening to the cloud, the workflow will be different from the one way. Here it will be mostly command from the cloud & and the response from the agent.
  8. Here as well the agent should send all the available controllers using the Controller JSON, but the points array will be empty initially.
  9. Once the cloud receive all the controllers, it will be listed under the Agent Configuration > Controllers page under the specific Agent. 
  10. From the controllers page, select the configuration menu from the horizontal menu of a specific controller or go to configuration page directly and select the agent, type as misc & required controller from drop down.
  11. After selecting the controller you can see two tabs viz. Configured & Un-Configured with no data.
  12. Click on the Discover Points for that controller.
Discover Points Command
  1. On clicking Discover Points, it will send a ping command to the agent.  Refer this note before handling the commands in the agent.
  2. For the ping command the agent has to send the ping response.
  3. After receiving the ping command response the cloud will send  Discover Points command
  4. For the Discover Points command, the agent should send response as follows 
    1. Processing JSON with publish type as ack (Acknowledgement) and with message as Processing, before starting the processing itself. This is to inform the cloud that the agent has received the message.
    2. Response JSON with publish type as devicepoints and points array filled with points.
    3. Completed JSON with publish type as ack and with message as Executed.
  5. Once the response JSON with points array filled reaches the cloud, the list of points will appear in the Un-Configured tab.

Configure Points Command

  1. The above Discover points command will fetch all the points in a controller, but in reality we may not need periodic data (timeseries) for all the points.
  2. To filter those points, the required points need to be selected from the Un-Configured tab and then click on the Configure button
  3. On clicking Configure, it will also send a ping command to the agent. Refer this note before handling the commands in the agent.
  4. For the ping command the agent has to send the ping response.
  5. After receiving the ping command response the cloud will send Configure Points Command.
  6. For the Configure Points command, the agent should send response as follows

Was this article helpful?