CoAP client AT commands

This page describes AT commands for the CoAP client. The CoAP client operates on sockets managed by the Socket AT commands. You can perform the following using the Socket AT commands:

Create a UDP socket with AT#XSOCKET or AT#XSSOCKET.
Connect it with AT#XCONNECT.
Set socket options with AT#XSOCKETOPT or AT#XSSOCKETOPT.
Close with AT#XCLOSE.

Only one CoAP request might be active at a time across all sockets.

CoAP request #XCOAPCREQ 

The #XCOAPCREQ command starts an asynchronous CoAP request on a connected UDP socket.

Set command

The set command sends a CoAP request and returns OK immediately. The server’s response is delivered through unsolicited #XCOAPCDATA and #XCOAPCSTAT notifications.

Syntax

AT#XCOAPCREQ=<handle>,<path>,<method>[,<auto_reception>[,<format>[,<confirmable>[,<content_format>[,<payload_len>[,<opt_num_1>,<opt_val_1>[,<opt_num_2>,<opt_val_2>[...]]]]]]]]

The parameters and their defined values are the following:

<handle>

Integer. Identifies the connected socket handle returned by AT#XSOCKET and connected by AT#XCONNECT.

<path>

String. The URI-path of the resource, for example "/sensors/temperature".

<method>

1 - GET.
2 - POST.
3 - PUT.
4 - DELETE.
5 - FETCH.
6 - PATCH.
7 - iPATCH.

<auto_reception>

Integer. Optional. When omitted, automatic reception is used.

1 - Automatic mode (default). Response bytes are forwarded to the host automatically through #XCOAPCDATA URCs.
0 - Manual mode. The firmware buffers each response block and emits #XCOAPCHEAD. The host must then retrieve the block using AT#XCOAPCDATA.

<format>

Integer. Optional. Controls the encoding used to deliver response payload bytes to the host.

0 - Binary (default). Response payload bytes are forwarded to the host as raw binary.
1 - Hex string. Response payload bytes are encoded as a lowercase ASCII hex string before delivery. Each raw byte becomes two hex characters. The <length> field in #XCOAPCDATA URCs and responses always reports the raw byte count. The actual data transmitted to the host is 2×<length> ASCII hex characters.

<confirmable>

Integer. Optional.

0 - Non-confirmable (NON) message (default).
1 - Confirmable (CON) message.

<content_format>

Integer. Optional. The CoAP Content-Format option number for the request payload (default 0 = text/plain). Common values:

0 - text/plain.
42 - application/octet-stream.
50 - application/json.
60 - application/cbor.

<payload_len>

Integer. Optional. When 0 or omitted and no option pairs follow, no request payload is sent and the command returns OK immediately. A positive integer specifies the total payload length in bytes and the command then returns OK and enters data mode.

Note

When option pairs follow, <payload_len> must be written explicitly. Use 0 if no payload is needed. Omitting it shifts the option pairs one position left, which always causes the command to return ERROR.

The host must send exactly this many bytes as the request payload. Data mode exits and #XDATAMODE: 0 is reported when all bytes have been consumed. Data mode is the only mechanism for supplying the payload - there is no inline parameter alternative.

The exact sending behavior depends on payload size:

Small payload (≤ 512 bytes) - All bytes are buffered until data mode exits, then the CoAP request is sent as a single packet.
Large payload (> 512 bytes) - The CoAP request starts transmitting while data mode is still active. As soon as the first full block of 512 bytes has arrived, the first CoAP Block1 packet is sent to the server. Each subsequent block is sent as more data arrives, so the server exchange runs concurrently with the host’s serial upload.

<opt_num_X>,<opt_val_X>

Optional CoAP option pairs.

When present, <payload_len> must also be present as the positional separator before the first pair.
<opt_num_X> is a decimal integer option number.
<opt_val_X> is a quoted string.
A value prefixed with 0x or 0X is decoded as raw hex bytes (for example, "0x3c" → byte 0x3c).
The hex part after the prefix must be non-empty and even-length, otherwise, the command returns ERROR.
Any value without the 0x prefix is used verbatim, including strings that look like hex (for example "abcd" → 4 ASCII bytes).
Common option numbers:
- 6 - Observe ("0x00" = register, "0x01" = deregister).
- 17 - Accept (content format the client will accept, hex-encoded).
- 35 - Proxy-Uri (full URI passed to a proxy, verbatim string).

Examples:

17,"0x00"                 Accept: text/plain (0x00)
17,"0x3c"                 Accept: application/cbor (0x3c = 60)
35,"coap://proxy/res"     Proxy-Uri verbatim string
6,"0x00",17,"0x3c"        Observe register + Accept cbor

Note

The Observe option (option 6) with the register value "0x00" starts a persistent subscription. The request stays active and the firmware delivers each server notification through #XCOAPCDATA (automatic mode) or #XCOAPCHEAD (manual mode). No #XCOAPCSTAT is emitted between notifications. To stop the subscription, use AT#XCOAPCCANCEL. You cannot send a separate deregister request (6,"0x01") while the subscription is active, because only one CoAP request can be active at a time.

Unsolicited notification

#XCOAPCDATA is emitted in automatic mode for each received response block.

#XCOAPCDATA: <handle>,<offset>,<length>

The notification line is terminated with \r\n, the response data follows immediately, and a \r\n terminator follows the data bytes. In binary mode (default), the data is <length> raw bytes. In hex mode (<format>=1), the data is 2×<length> lower-case ASCII hex characters.

The parameters and their defined values are the following:

<handle>: Integer. Identifies the socket.
<offset>: Integer. The number of response bytes already delivered before this block.
<length>: Integer. The raw byte count of the response data in this block. In hex mode (<format>=1), the payload following the header line is 2×<length> ASCII hex characters.

#XCOAPCHEAD is emitted in manual mode for each received response block.

#XCOAPCHEAD: <handle>,<code>,<block_len>

The parameters and their defined values are the following:

<handle>: Integer. Identifies the socket.
<code>: Integer. The CoAP response code for this block.
<block_len>: Integer. The raw byte count of the buffered block. In hex mode (<format>=1), AT#XCOAPCDATA will deliver 2×<block_len> ASCII hex characters. The host must call AT#XCOAPCDATA to retrieve this block before the next one arrives.

#XCOAPCSTAT is emitted when the request completes, fails, or is cancelled.

#XCOAPCSTAT: <handle>,<status_code>,<total_bytes>

The parameters and their defined values are the following:

<handle>: Integer. Identifies the socket.
<status_code>: Integer. The CoAP response code on success, or -1 on failure or cancel. CoAP response codes are encoded as (class << 5) | detail. For example, 2.05 Content is encoded as 69 and 2.04 Changed as 68.
<total_bytes>: Integer. The total number of raw response payload bytes received. In hex mode (<format>=1), this is the raw byte count, not the number of hex characters delivered.

Note

Block2 response transfer (server-side fragmentation of large responses) is handled automatically by the CoAP client library. All blocks are forwarded to the host in sequence. #XCOAPCSTAT is emitted only after the final block is received and delivered.

Examples

CoAP GET (automatic mode, binary):

AT#XSOCKET=1,2,0
#XSOCKET: 0,2,17
OK

AT#XCONNECT=0,"coap.example.com",5683
#XCONNECT: 0,1
OK

AT#XCOAPCREQ=0,"/sensors/temperature",1
OK

#XCOAPCDATA: 0,0,12
23.5 Celsius

#XCOAPCSTAT: 0,69,12

AT#XCLOSE=0
OK

Note

In automatic mode, a \r\n terminator is appended after the data bytes of each #XCOAPCDATA notification.

CoAP GET (automatic mode, hex-encoded response, format=1):

AT#XCOAPCREQ=0,"/sensors/temperature",1,1,1
OK

#XCOAPCDATA: 0,0,12
32332e352043656c73697573

#XCOAPCSTAT: 0,69,12

Note

The hex string and the line break after it represent the 2×<length> hex characters followed by the \r\n terminator.

CoAP GET (manual mode):

AT#XCOAPCREQ=0,"/sensors/temperature",1,0
OK

#XCOAPCHEAD: 0,69,12

AT#XCOAPCDATA=0
#XCOAPCDATA: 0,0,12
23.5 Celsius
OK

#XCOAPCSTAT: 0,69,12

CoAP POST with JSON payload (content_format=50 = application/json):

AT#XCOAPCREQ=0,"/data",2,1,0,0,50,13
OK
{"value": 42}
#XDATAMODE: 0

#XCOAPCSTAT: 0,68,0

CoAP GET through proxy with Proxy-URI option (option 35, value is a plain URI string):

AT#XCOAPCREQ=0,"proxy",1,1,0,0,0,0,35,"coap://remote-host/resource"
OK

#XCOAPCDATA: 0,0,128
<128 bytes>

#XCOAPCSTAT: 0,69,128

CoAP GET with Observe and Accept options (option 6 = Observe register "0x00", option 17 = Accept "0x3c" = 0x3c = application/cbor):

AT#XCOAPCREQ=0,"/obs",1,1,0,1,0,0,6,"0x00",17,"0x3c"
OK

#XCOAPCDATA: 0,0,18
<18 bytes CBOR>

#XCOAPCDATA: 0,0,18
<18 bytes CBOR>

AT#XCOAPCCANCEL=0
OK

#XCOAPCSTAT: 0,-1,0

The subscription stays active and delivers a #XCOAPCDATA notification for each server update until you cancel it with AT#XCOAPCCANCEL. The #XCOAPCSTAT notification is emitted only when the subscription ends.

Test command

The test command tests the existence of the command and provides information about the type of its subparameters.

Syntax

AT#XCOAPCREQ=?

Response syntax

#XCOAPCREQ: <handle>,<path>,<method>[,<auto_reception>[,<format>[,<confirmable>[,<content_format>[,<payload_len>[,<opt_num>,<opt_val>...]]]]]]

Example

AT#XCOAPCREQ=?
#XCOAPCREQ: <handle>,<path>,<method>[,<auto_reception>[,<format>[,<confirmable>[,<content_format>[,<payload_len>[,<opt_num>,<opt_val>...]]]]]]
OK

CoAP data pull #XCOAPCDATA 

The #XCOAPCDATA command pulls a buffered response block for a manual-mode CoAP request.

Set command

The set command delivers one buffered response block to the host and unblocks the CoAP client to request the next Block2 block, if any.

Syntax

AT#XCOAPCDATA=<handle>[,<length>]

The parameters and their defined values are the following:

<handle>

Integer. Identifies the socket used when starting the manual-mode request.

<length>

Integer. Optional. The maximum number of bytes to return in this pull.

When omitted, the full block buffer size (512 bytes) is used.

Response syntax

When a block is available:

#XCOAPCDATA: <handle>,<offset>,<length>
<data>
OK

In binary mode (default), <data> is <length> raw bytes. In hex mode (<format>=1), <data> is 2×<length> lower-case ASCII hex characters.

The #XCOAPCDATA: line is terminated with \r\n. <length> raw response bytes follow immediately with no additional separator. OK follows on its own line after the response bytes.

When no block has been buffered yet (the firmware is still waiting for the server response).

#XCOAPCDATA: <handle>,<offset>,<length>
OK

The parameters and their defined values are the following:

<handle>: Integer. Identifies the socket.
<offset>: Integer. The number of response bytes already delivered before this pull.
<length>: Integer. The number of response bytes delivered in this pull. A value of 0 means no block is ready yet.

After the last block is drained, #XCOAPCSTAT is emitted as a URC after the final OK.

Note

If AT#XCOAPCDATA is not called within 30 seconds of a #XCOAPCHEAD notification, the request is aborted and #XCOAPCSTAT: <handle>,-1,<total_bytes> is emitted.

Example

AT#XCOAPCREQ=0,"/large",1,0
OK

#XCOAPCHEAD: 0,69,512

AT#XCOAPCDATA=0,512
#XCOAPCDATA: 0,0,512
<512 bytes>
OK

#XCOAPCHEAD: 0,69,512

AT#XCOAPCDATA=0,512
#XCOAPCDATA: 0,512,512
<512 bytes>
OK

#XCOAPCSTAT: 0,69,1024

Test command

The test command tests the existence of the command and provides information about the type of its subparameters.

Syntax

AT#XCOAPCDATA=?

Response syntax

#XCOAPCDATA: <handle>[,<length>]

Example

AT#XCOAPCDATA=?
#XCOAPCDATA: <handle>[,<length>]
OK

CoAP request cancel #XCOAPCCANCEL 

The #XCOAPCCANCEL command cancels the active CoAP request. It is also the mechanism for stopping a CoAP Observe subscription started with the Observe register option (6,"0x00").

Set command

The set command cancels the currently active CoAP request.

Syntax

AT#XCOAPCCANCEL=<handle>

The parameters and their defined values are the following:

<handle>: Integer. Must match the socket handle that was passed to AT#XCOAPCREQ when the request was started. This acts as an ownership assertion: the command returns ERROR if no request is active or if the active request belongs to a different handle.

Note

Only one CoAP request can be active at a time. The <handle> check is an ownership guard, not a per-socket filter. Cancellation always applies to the single in-flight request.

An unsolicited #XCOAPCSTAT: <handle>,-1,<total_bytes> notification is emitted after cancellation, where <total_bytes> is the number of response bytes already delivered to the host.

Example

AT#XCOAPCCANCEL=0
OK
#XCOAPCSTAT: 0,-1,0

Test command

The test command tests the existence of the command and provides information about the type of its subparameters.

Syntax

AT#XCOAPCCANCEL=?

Response syntax

#XCOAPCCANCEL: <handle>

Example

AT#XCOAPCCANCEL=?
#XCOAPCCANCEL: <handle>
OK

CoAP client AT commands

CoAP request #XCOAPCREQ

Set command

Syntax

Unsolicited notification

Examples

Test command

Syntax

Response syntax

Example

CoAP data pull #XCOAPCDATA

Set command

Syntax

Response syntax

Example

Test command

Syntax

Response syntax

Example

CoAP request cancel #XCOAPCCANCEL

Set command

Syntax

Example

Test command

Syntax

Response syntax

Example

CoAP request #XCOAPCREQ 

CoAP data pull #XCOAPCDATA 

CoAP request cancel #XCOAPCCANCEL 