Operations

Introduction to the Power of OpenGate Operations

OpenGate’s Operations feature is a powerful tool for managing and interacting with remote devices. By leveraging this feature, you can seamlessly integrate and control a wide array of remote devices, enabling unparalleled efficiency and flexibility in your IoT ecosystem.

Key Benefits of OpenGate Operations

  1. Remote Configuration: OpenGate allows you to configure devices remotely, ensuring that settings and updates can be applied without physical access. This feature reduces downtime and operational costs while enhancing device performance and reliability.

  2. Action Requests: With OpenGate, you can issue commands and requests to remote devices in real time, putting you in control and ensuring a responsive system. Whether it’s initiating a firmware update, performing diagnostics, or executing specific tasks, OpenGate ensures that your devices respond promptly and accurately.

  3. Enhanced Integration: The Operations feature seamlessly integrates with your existing systems, respecting and utilizing your current setup. This provides a unified platform for device management, simplifying workflows and enhancing the overall efficiency of your operations.

By utilizing OpenGate’s Operations feature, you can remotely manage, configure, and interact with your devices. This empowers you to maintain optimal performance and achieve greater control over your IoT network. This capability transforms how you manage remote devices, making your operations more agile and responsive to changing needs.

Flexible Operation Control with OpenGate

OpenGate’s Operations feature provides the flexibility to initiate and control operations from both the OpenGate platform and the remote devices themselves. This dual capability ensures that you can maintain optimal control and responsiveness, regardless of your operational needs or the specific scenarios you encounter.

Operation Initiation

  • Platform-Driven Operations: Initiate and manage operations directly from the OpenGate platform, allowing centralized control over device configurations, updates, and actions.
  • Device-Driven Operations: Remote devices can also ask for pending operations, providing a decentralized approach that can be tailored to specific device requirements and conditions.

Additional Resources

For more detailed information on how to utilize these capabilities, please refer to the following links:

These resources offer comprehensive guidance on initiating and managing operations securely, ensuring that your interactions with remote devices are both efficient and safe. By following these guidelines, you can maximize the potential of OpenGate’s Operations feature while maintaining robust security standards.

Subsections of Operations

Operations driven by platform

Introduction

OpenGate initiates communication with the device, requesting the execution of a specific operation. Upon receiving this request, the device can respond in either a synchronous or asynchronous manner, utilising the HTTP protocol.

Devices can expose this endpoint so that OpenGate can request operation executions on them.

Synchronous

The entirety of the operation is driven by a single HTTP request and response: the device executes the operation and returns the result in the response body of the same exchange.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    OG->>+Dev: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    Note over Dev: executes the operation
    Dev-->>-OG: RESPONSE (HTTP RESPONSE) 201 Ok<br>Response Info (JSON)
    end

Asynchronous

In this instance, OpenGate transmits the operation to the device via an HTTP request, and the device responds with an acknowledgement through the utilisation of an HTTP response. Subsequently, OpenGate is capable of receiving one or multiple HTTP requests transmitted by the device. These HTTP requests can be employed by the device to convey the subsequent steps that the operation necessitates.

For further information on the endpoints exposed by OpenGate for the management of asynchronous operation communications, please refer to the section on operations driven by device.

Simple response

The device transmits a sole response message in order to respond to the request.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    OG->>+Dev: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    Dev-->>-OG: COMMAND ACK (HTTP RESPONSE) 201 Ok
    end

    Note over Dev: executes the operation

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device generated response
    Dev->>+OG: RESPONSE (HTTP REQUEST -> POST)<br>Response Info (JSON)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

Multiple responses

The device can transmit a number of partial responses and a final response at the conclusion of the sequence.

Partial responses carry no resultCode: that is what marks them as intermediate. The final response includes it, closing the operation.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    OG->>+Dev: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    Dev-->>-OG: COMMAND ACK (HTTP RESPONSE) 201 Ok
    end

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device generated partial response
    Dev->>+OG: PARTIAL RESPONSE (HTTP REQUEST -> POST)<br>Response Info (without resultCode)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

    Note over OG,Dev: one exchange per partial response

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device final response
    Dev->>+OG: RESPONSE (HTTP REQUEST -> POST)<br>Response Info (JSON)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

Operation structure

Simple request/response

The operation is comprised of a single request and a single response, which together constitute its entirety. There are no intermediate steps. It can be executed in either a synchronous or asynchronous manner, with the latter resulting in a simple response.

Multi-step response

In order to facilitate the monitoring of the operation, it is necessary to define a list of steps. The device is capable of providing information regarding these steps in a single response or in a series of partial responses until the final step is reached. The device can respond using either a synchronous or an asynchronous (simple or multiple responses) flow strategy.

Response structure

In regard to the JSON format, there is no distinction between synchronous and asynchronous responses.

  • Synchronous: The device incorporates the JSON payload into the HTTP response.
  • Asynchronous: The device incorporates the JSON payload into a new HTTP POST, which is initiated by the device itself.

API specification

Device HTTP ports

  • Unsecure (deprecated): 1123
  • Secure: 11235

Usage example

In this flow the device acts as the HTTP server: OpenGate sends the operation request to the endpoint exposed by the device. Request body sent by OpenGate:

{
  "operation": {
    "request": {
      "timestamp": 1614169437035,
      "name": "EQUIPMENT_DIAGNOSTIC",
      "parameters": {},
      "id": "27dfeb18-e13f-45eb-abcc-b8b215c30599"
    }
  }
}

Synchronous response body returned by the device with HTTP 201:

{
  "operation": {
    "response": {
      "id": "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
      "timestamp": 1432454278000,
      "deviceId": "device_1",
      "name": "EQUIPMENT_DIAGNOSTIC",
      "resultCode": "SUCCESS",
      "resultDescription": "No Error",
      "steps": [
        {
          "name": "MOTHER_BOARD",
          "timestamp": 1432454278000,
          "result": "SUCCESSFUL",
          "description": "Motherboard is Ok"
        }
      ]
    }
  }
}

Operations driven by device

Introduction

The typical use case is when the remote device, having been in a long sleep period, requests the pending operation requests stored in OpenGate.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device polls for pending operation
    Dev->>+OG: Retrieve Op. Request (HTTP POST)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    Dev->>+OG: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    OG-->>-Dev: COMMAND ACK (HTTP RESPONSE) 201 Ok
    end

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device generated response
    Dev->>+OG: RESPONSE (HTTP REQUEST -> POST)<br>Response Info (JSON)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

Usage examples

Ask for pending operations:

curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/operation/pending' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "trustedBoot": "ab2a2ed4-780d-11eb-9439-0242ac130002",
    "operation": {
      "request": {
        "deviceId": "6890af9e-781c-11eb-9439-0242ac130002",
        "path": ["gateway_001"]
      }
    }
  }'

Send an asynchronous operation response:

curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/operation/response' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "7.0",
    "operation": {
      "response": {
        "id": "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
        "timestamp": 1432454278000,
        "deviceId": "device_1",
        "name": "EQUIPMENT_DIAGNOSTIC",
        "resultCode": "SUCCESS",
        "resultDescription": "No Error",
        "steps": [
          {
            "name": "MOTHER_BOARD",
            "timestamp": 1432454278000,
            "result": "SUCCESSFUL",
            "description": "Motherboard is Ok"
          }
        ]
      }
    }
  }'

A valid request returns HTTP 201 with a Location header.

API specification

Security tips for operations

Tips to Ensure Security When Using OpenGate Operations

To ensure the security of your operations with OpenGate, follow these recommended practices:

  1. Use Encrypted Communication: Always use secure HTTP (HTTPS) for communication, utilizing the default TCP port 443. Unsecured HTTP communication (default TCP port 80) is deprecated and will soon be unsupported.

  2. Authentication Mechanisms: OpenGate requires authentication for all operations. There are two mechanisms you can use simultaneously for enhanced security:

    • API Key Authentication: Include the X-ApiKey HTTP header with the API key of a valid user in every request.
    • Mutual Authentication: Implement mutual authentication based on secure HTTP PKI infrastructure for an additional layer of security, ensuring the integrity and confidentiality of your communications.

By following these guidelines, you can enhance the security and reliability of your interactions with the OpenGate platform.