The Constrained Application Protocol (CoAP) is a lightweight web transfer protocol (RFC 7252) designed for constrained nodes and networks. OpenGate operates exclusively as a CoAP listening server, receiving incoming request messages (e.g. for data collection or operational responses) sent by devices.

Note: OpenGate does not initiate outbound CoAP requests to external CoAP servers running on devices. All CoAP communications must be initiated by the device towards OpenGate.

Endpoints

OpenGate listens for CoAP requests on both unencrypted UDP and secure DTLS ports.

Scheme Port Transport / Security Example URI
coap:// 5683 Unencrypted (UDP) coap://api.opengate.es:5683/{meter_id}/{path}
coaps:// 30013 DTLS (Datagram Transport Layer Security) coaps://api.opengate.es:30013/{meter_id}/{path}

URI structure and south criteria

All CoAP URIs targeted by devices must place the device’s unique identifier ({meter_id}) at the beginning of the URL path:

coap://api.opengate.es:5683/{meter_id}/{path}
coaps://api.opengate.es:30013/{meter_id}/{path}
  • {meter_id}: The unique OpenGate identifier of the device.
  • {path}: The resource path matched against the south criteria in your connector functions.

For example, a connector function configured with south criteria = "coaps://data" will match requests sent to either coap://api.opengate.es:5683/{meter_id}/data or coaps://api.opengate.es:30013/{meter_id}/data.

Each manufacturer or device implementation defines its own specific paths ({path}) and payload formats (JSON, binary, etc.), which are translated into OpenGate data structures by corresponding connector functions.

Authentication

Every CoAP request sent to OpenGate must include API key authentication (X-ApiKey). In CoAP, authentication is delivered as a custom CoAP Option:

Property Value
CoAP Option Number 2502
Value Format A string containing your OpenGate API key
Requirement Required

Requests received without CoAP Option 2502 or with an invalid API key will be rejected by OpenGate as unauthorized.

Message processing and connector functions

Incoming CoAP requests are evaluated against configured connector functions:

  1. Routing: The request scheme (coap:// or coaps://) and URI path are matched against the south criteria defined in your connector functions.
  2. Execution: The matching connector function processes the request payload (such as JSON, binary data, etc).
  3. Response: OpenGate returns a CoAP response to the device. To customize the status code, content format, or body of the response sent back to the device, use the CoAP JavaScript API.