Introduction

This section describes how constrained devices push telemetry, measurements, inventory, or custom data to OpenGate over the CoAP protocol.

Endpoint & URI Structure

Every CoAP data collection request sent by a device must include the unique device identifier ({meter_id}) at the beginning of the URI path:

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

• {meter_id}: The device identifier in OpenGate (e.g. device serial number, IMEI, meter ID).
• {path}: The relative resource path defined by the device integration.

Matching South Criterias

The scheme (coap:// or coaps://) and {path} portion of the URI are evaluated against the southCriterias defined in your platform connector functions.

For example, if a connector function defines a southCriterias of "coaps://data", it will match requests sent to:

• coap://api.opengate.es:5683/METER-12345/data
• coaps://api.opengate.es:30013/METER-12345/data

Payload Formats & Manufacturer Flexibility

OpenGate does not enforce a single static payload format for CoAP data collection. Each device manufacturer or integration profile can define its own:

• URI Resource Paths: e.g., /data, /telemetry, /v1/readings, /sensors.
• Payload Encoding: JSON, CBOR (Concise Binary Object Representation), or vendor-specific binary formats suited for constrained devices and narrow bands.

The matching connector function parses the raw incoming byte payload and maps the measurements to standard OpenGate data streams.

Authentication

All requests must include API key authentication passed in CoAP Option 2502:

Example Flow

1. The device sends a CoAP POST or PUT request:

   • Target URI: coaps://api.opengate.es:30013/METER-12345/data
   • Option 2502: <your-api-key>
   • Payload: Vendor-specific measurement payload.

2. OpenGate matches the request to the connector function with southCriterias = "coaps://data".

3. The connector function parses the payload, extracts data points for device METER-12345, and formats the response status using the CoAP JavaScript API:

// Example connector function snippet returning status 2.04 (CHANGED)
coap.server.response.status = 204;
coap.server.response.send();

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: