# 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:

```bash
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](../../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**:

| Property | Value |
|---|---|
| **CoAP Option Number** | `2502` |
| **Value Format** | String containing the OpenGate API key |
| **Requirement** | **Required** |

## 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](../../connector_functions/protocol_apis/coap/):

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