Connect over CoAP

CoAP is the protocol for the smallest, most constrained devices — battery-powered sensors on lossy networks where TCP and TLS are too heavy. It runs over UDP, uses compact CBOR payloads, and secures the link with DTLS. CORE-M terminates CoAP in the device-link adapter, authenticates the device from the DTLS handshake, decodes the CBOR body with the device profile’s decoder, and publishes a normal TelemetryPoint.

Note

Provision the device and obtain its DTLS credential first — see identity & credentials.

Ports

CoAP (plain)	5683
CoAPS (DTLS)	5684

Use CoAPS on 5684 in production. Plain 5683 carries no transport security and is for local testing only.

Authentication

CoAP devices authenticate during the DTLS handshake, before any CoAP request is processed. Two modes are supported:

• DTLS-PSK — the device presents a PSK identity; the adapter looks that identity up to resolve the tenant, device, and pre-shared key, and completes the handshake only if all three resolve. The negotiated cipher suite is TLS_PSK_WITH_AES_128_CCM_8.
• Certificate — the device presents an X.509 client certificate that maps to a registered device identity.

Caution

Identity comes only from the DTLS handshake — never from the CoAP request content. An unknown PSK identity or an unresolvable certificate causes the handshake itself to be rejected, so no CoAP request is ever processed for an unauthenticated device.

Resource and payload

Send telemetry by issuing a CoAP POST to the telemetry resource:

Method	POST
Resource	/telemetry
Payload	CBOR (application/cbor)

The payload is a CBOR-encoded object of metric → value pairs. The device profile’s payload decoder turns it into a TelemetryPoint, mapping numeric fields into numeric_values and string fields into string_values. The conceptual content matches the JSON you would send over HTTP — just CBOR-encoded to save bytes on the wire:

{ "temperature": 22.5, "humidity": 65, "state": "running" }

The tenant and device are filled in from the DTLS-authenticated session, so the payload carries only the readings.

Tip

The decoder is configured per device profile. If your devices send a custom binary or CBOR layout, define the mapping in the profile’s payload decoder rather than reshaping firmware. See device profiles.

A complete example

Using coap-client from libcoap over DTLS-PSK. The -u flag is the PSK identity, -k is the pre-shared key, and the CBOR body is read from a file:

1. Prepare the CBOR payload. For example, encode {"temperature":22.5,"humidity":65} to reading.cbor with your toolchain (most CBOR libraries do this in one call).

2. POST it to the telemetry resource over CoAPS:

   coap-client -m post \
     -u 'psk-identity-d7b1c0e2' \
     -k 's3cr3t-pre-shared-key' \
     -t application/cbor \
     -f reading.cbor \
     'coaps://coap.kronoxdata.com:5684/telemetry'

3. A successful POST returns a 2.04 Changed response. The reading is now normalized and on its way through the pipeline.

How a CoAP ingest flows

sequenceDiagram
    participant Dev as Device
    participant DL as device-link CoAP adapter :5684
    participant PSK as Credential store
    participant RP as Redpanda telemetry.raw.{tenant}

    Dev->>DL: DTLS ClientHello (PSK identity)
    DL->>PSK: Lookup identity → tenant, device, key
    alt unknown identity
        DL-->>Dev: Handshake rejected
    else resolved
        DL-->>Dev: DTLS handshake complete
        Dev->>DL: POST /telemetry (CBOR)
        DL->>DL: Decode CBOR via profile decoder
        alt decode error
            DL-->>Dev: 4.xx (rejection metric +1, nothing published)
        else decoded
            DL->>RP: Publish normalized TelemetryPoint
            DL-->>Dev: 2.04 Changed
        end
    end

Decode-error behavior

If the CBOR body is malformed or does not match the profile decoder, the payload is rejected: the rejection metric corem_protocol_payload_rejections_total{protocol="coap",reason="decode_error"} is incremented and no telemetry is published to the bus. A decode failure never produces a partial point. Inspect rejected samples in the protocol diagnostics UI to find the offending field.

After the first accepted reading the device flips to online, and goes offline if it stops sending for longer than the offline threshold (default 120 seconds).

When to choose CoAP

Reach for CoAP when…

• The device is constrained — limited RAM, CPU, or battery.
• The network is low-bandwidth, lossy, or sleepy (NB-IoT, 6LoWPAN).
• You want UDP + DTLS instead of a persistent TCP/TLS session.
• Compact CBOR payloads matter for power and airtime budgets.

For devices that also need rich device management (firmware update, observe, remote execute) layered on top of CoAP/DTLS, use LwM2M instead.

Related

Connect over LwM2M Device management — bootstrap, register, observe, execute — over CoAP/DTLS.

Sending telemetry The TelemetryPoint model and ingest lifecycle.