Operations

Introduction

Because OpenGate operates exclusively as a CoAP listening server, the platform cannot initiate outbound CoAP connections to devices. Operation management over CoAP is therefore device-driven: devices periodically poll OpenGate for pending operation requests and report execution results back to the platform.

URI Structure & Device-Driven Workflow

All CoAP operation URIs must begin with the device unique identifier ({meter_id}):

coap://api.opengate.es:5683/{meter_id}/{path}
coaps://api.opengate.es:30013/{meter_id}/{path}

The operation workflow is typically split into two interaction endpoints defined via southCriterias:

1. Polling for Pending Operations

Devices periodically query OpenGate to check if there are pending operations queued for execution (e.g., firmware update requests, configuration changes, or remote commands).

• Example Device URI: coaps://api.opengate.es:30013/{meter_id}/askForOperations
• Matching southCriterias: coaps://askForOperations

Flow:

1. The device sends a CoAP request (e.g., POST or GET) to /askForOperations with CoAP Option 2502 containing the API key.
2. The connector function matching coaps://askForOperations retrieves pending operations assigned to {meter_id} from OpenGate.
3. The connector function formats and returns the pending operations to the device in the CoAP response payload.

2. Reporting Operation Execution Results

Once a device finishes executing an operation, it sends a CoAP request back to OpenGate to report the execution outcome (e.g., SUCCESS, ERROR, or progress status).

• Example Device URI: coaps://api.opengate.es:30013/{meter_id}/operationResults
• Matching southCriterias: coaps://operationResults

Flow:

1. The device sends a CoAP request (e.g., POST or PUT) containing the operation result payload.
2. The connector function matching coaps://operationResults parses the result payload and updates the operation status in OpenGate.
3. OpenGate returns a confirmation status (e.g., 2.04 Changed) via the CoAP JavaScript API.

Manufacturer & Payload Flexibility

Specific URIs and payload structures are defined per manufacturer or integration requirement. Different device models may use different relative paths (e.g., /pending-tasks, /report-outcome) and payload formats (JSON, CBOR, or binary).

Custom connector functions bridge the device-specific formats with OpenGate’s operation processing engine.

Authentication

All operation requests must carry API key authentication in CoAP Option 2502: