Data collection

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();