# 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}`):

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

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

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