MQTT

OpenGate provides an MQTT connector that lets devices exchange messages with the platform using a single TCP connection: publish collected data, receive operation requests, send operation responses and ask for pending operations. The following sections describe how to connect, the default OpenGate topics, and how to handle data collection and operations over MQTT.

Subsections of MQTT

Data collection

MQTT data collection

This section shows how to use OpenGate MQTT connector for data collection.

Using MQTT, your devices only need one TCP connection to exchange messages with the platform: publish collected data, receive operation requests, send operation responses, ask for pending operations, etc.

How to connect to OpenGate MQTT connector

These are the parameters to establish a MQTT connection with OpenGate:

  • Host: api.opengate.es
  • Port: 1883
  • User: your-device-id
  • Password: your-api-key

Obtaining your API key

  1. Login onto the OpenGate web interface
  2. Click on the cogs that are at the top-right of the OpenGate home page
  3. Click on the User option
  4. Click on the “Click to show” link

Collecting data using mosquitto CLI tool

mosquitto is an open source MQTT client and server. The following example shows how to connect and publish data using OpenGate MQTT connector:

mosquitto_pub \
    -h api.opengate.es -p 1883 \
    -t odm/iot/your-device-id \
    -u your-device-id -P your-api-key \
    -m 'your-datastreams-as-json'

OpenGate default MQTT topics

  • To publish collected data: odm/iot/your-device-id
  • To subscribe to incoming operations from OpenGate: odm/request/your-device-id
  • To publish operation responses: odm/response/your-device-id

You have to replace your-device-id with the OpenGate unique identifier of your device.

Data collection payload

The payload definition in the section HTTP integration to collect data is entirely valid. You only have to add a "device": "your-device-id" field, filled with your OpenGate device unique identifier, at the top level of the JSON document with the collected values.

See the following example:

Publish to odm/iot/your-device-id topic this JSON:

{
  "version": "1.0.0",
  "device": "your-device-id",
  "datastreams": [
    {
      "id": "temperature",
      "datapoints": [{ "value": 24.1 }]
    }
  ]
}

Operations

MQTT operations

OpenGate default MQTT topics for operations

  • To subscribe to incoming operations from OpenGate: odm/request/your-device-id
  • To publish operation responses: odm/response/your-device-id

Replace your-device-id with the OpenGate unique identifier of your device.

Subsections of Operations

Examples

MQTT operation examples

Each example shows the complete flow of an operation over MQTT: the North API request that creates the operation job, the request message the device receives on its odm/request/your-device-id topic, and the response message the device publishes on its odm/response/your-device-id topic.

Subsections of Examples

Refresh info

Send the operation request to OpenGate

The following request creates the operation job that sends the operation to your device.

curl 'https://api.opengate.es/north/v80/operation/jobs' \
  -H 'X-ApiKey: your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  --data '{
  "job": {
    "request": {
      "operationParameters": {
        "timeout": 90000,
        "retries": 0,
        "retriesDelay": 0
      },
      "name": "REFRESH_INFO",
      "schedule": {
        "stop": {
          "delayed": 120000
        }
      },
      "parameters": {},
      "target": {
        "append": {
          "entities": [
            "your-device-id"
          ]
        }
      },
      "active": true
    }
  }
}'

Receiving operation request into a device

You must be connected to OpenGate MQTT connector as a subscriber to topic odm/request/your-device-id, if so, then you’ll receive an operation request like this:

{
  "operation": {
    "request": {
      "timestamp": 1614239125800,
      "name": "REFRESH_INFO",
      "parameters": {},
      "id": "9ac30d2d-1401-4c2b-996f-e55882b6c5c4"
    }
  }
}

Answering the operation

Your device must publish a message to the topic odm/response/your-device-id to let OpenGate know it’s going to answer the operation:

{
  "operation": {
    "response": {
      "name": "REFRESH_INFO",
      "timestamp": 1614239127235,
      "resultDescription": "Success",
      "steps": [
        {
          "timestamp": 1614239127235,
          "description": "",
          "name": "REFRESH_INFO",
          "result": "SUCCESSFUL"
        }
      ],
      "deviceId": "your-device-id",
      "resultCode": "SUCCESSFUL",
      "id": "9ac30d2d-1401-4c2b-996f-e55882b6c5c4"
    }
  },
  "version": "1.0"
}

Fulfill the operation

Because this operation requests a full info refresh to your device, it must publish a new message with all the requested information to the topic odm/iot/your-device-id the message:

{
  "device": "your-device-id",
  "datastreams": [
    {
      "id": "device.serialNumber",
      "datapoints": [{ "value": "F71SL16NHG9G" }]
    },
    {
      "id": "device.model",
      "datapoints": [
        {
          "value": {
            "name": "OpenGateMqtt",
            "manufacturer": "OpenGate"
          }
        }
      ]
    },
    {
      "id": "device.birthDate",
      "datapoints": [{ "value": "2021-02-25 08:21:32" }]
    },
    {
      "id": "device.operationalStatus",
      "datapoints": [{ "value": "NORMAL" }]
    },
    {
      "id": "device.upTime",
      "datapoints": [{ "value": "1614237191" }]
    },
    {
      "id": "device.clock",
      "datapoints": [
        {
          "value": {
            "date": "2021-02-25",
            "time": "12:32:01"
          }
        }
      ]
    },
    {
      "id": "device.software",
      "datapoints": [
        {
          "value": [
            {
              "type": "FIRMWARE",
              "name": "v1.0.0"
            }
          ]
        }
      ]
    },
    {
      "id": "device.temperature.value",
      "datapoints": [{ "value": 19 }]
    },
    {
      "id": "device.communicationModules[].subscription.identifier",
      "datapoints": [{ "value": "346xxxxxxxx" }]
    },
    {
      "id": "device.communicationModules[].subscription.mobile.signalStrength",
      "datapoints": [{ "value": -80 }]
    },
    {
      "id": "device.communicationModules[].subscription.mobile.signalStrengthStatus",
      "datapoints": [{ "value": "NORMAL" }]
    },
    {
      "id": "device.communicationModules[].subscription.mobile.ratType",
      "datapoints": [{ "value": "LTE" }]
    }
  ],
  "version": "1.0.0"
}

Reboot equipment

Send the operation request to OpenGate

The following request creates the operation job that sends the operation to your device.

curl 'https://api.opengate.es/north/v80/operation/jobs' \
  -H 'X-ApiKey: your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  --data '{
  "job": {
      "request": {
          "operationParameters": {
              "timeout": 90000,
              "retries": 0,
              "retriesDelay": 0
          },
          "name": "REBOOT_EQUIPMENT",
          "schedule": {
              "stop": {
                  "delayed": 120000
              }
          },
          "parameters": {
              "type": "HARDWARE"
          },
          "target": {
              "append": {
                  "entities": [
                      "649843"
                  ]
              }
          },
          "active": true
      }
  }
}'

Receiving operation request into a device

You must be connected to OpenGate MQTT connector as a subscriber to topic odm/request/your-device-id, if so, then you’ll receive an operation request like this:

{
  "operation": {
    "request": {
      "timestamp": 1614253699108,
      "name": "REBOOT_EQUIPMENT",
      "parameters": {
        "type": "HARDWARE"
      },
      "id": "05d17fb4-b2a8-49d8-8461-cda0d24f852b"
    }
  }
}

Answering the operation

Your device must publish a message to the topic odm/response/your-device-id to let OpenGate know it’s going to answer the operation:

{
  "operation": {
    "response": {
      "name": "REBOOT_EQUIPMENT",
      "timestamp": 1614253700835,
      "resultDescription": "Success",
      "steps": [
        {
          "timestamp": 1614253700835,
          "description": "The system will be rebooted",
          "name": "REBOOT_EQUIPMENT",
          "result": "SUCCESSFUL"
        }
      ],
      "deviceId": "649843",
      "resultCode": "SUCCESSFUL",
      "id": "05d17fb4-b2a8-49d8-8461-cda0d24f852b"
    }
  },
  "version": "1.0"
}

Equipment diagnostic

Send the operation request to OpenGate

The following request creates the operation job that sends the operation to your device.

curl 'https://api.opengate.es/north/v80/operation/jobs' \
  -H 'X-ApiKey: your-api-key' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  --data '{
  "job": {
    "request": {
      "operationParameters": {
        "timeout": 90000,
        "retries": 0,
        "retriesDelay": 0,
        "retryResultList" : []
      },
      "name": "EQUIPMENT_DIAGNOSTIC",
      "schedule": {
        "stop": {
          "delayed": 120000
        }
      },
      "parameters": {
        "type": "HARDWARE"
      },
      "target": {
        "append": {
          "entities": [
            "649843"
          ]
        }
      },
      "active": true
    }
  }
}'

Receiving operation request into a device

You must be connected to OpenGate MQTT connector as a subscriber to topic odm/request/your-device-id, if so, then you’ll receive an operation request like this:

{
  "operation": {
    "request": {
      "timestamp": 1614238879802,
      "name": "EQUIPMENT_DIAGNOSTIC",
      "parameters": {
        "type": "HARDWARE"
      },
      "id": "14502149-99f9-4348-93f1-23aea495811b"
    }
  }
}

Answering the operation

Your device must publish a message to the topic odm/response/your-device-id to let OpenGate know it’s going to answer the operation:

{
  "operation": {
    "response": {
      "name": "EQUIPMENT_DIAGNOSTIC",
      "timestamp": 1614238881241,
      "resultDescription": "Success",
      "steps": [
        {
          "timestamp": 1614238881241,
          "description": "System is OK",
          "name": "EQUIPMENT_DIAGNOSTIC",
          "result": "SUCCESSFUL"
        }
      ],
      "deviceId": "649843",
      "resultCode": "SUCCESSFUL",
      "id": "14502149-99f9-4348-93f1-23aea495811b"
    }
  },
  "version": "1.0"
}