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"
}