Format Foundations: CoAP Messages Reference
More
Depth: Practitioner
Progress saves as you read. Mark sections complete as you go; your progress appears in the sidebar.
Start With the Decision
A controller has two unanswered requests to a leak sensor. A delayed response arrives: which request does it answer? CoAP means Constrained Application Protocol; here it runs over UDP, a transport that sends individual datagrams. An endpoint is a network address and port. Use the response’s Token, a value copied from the request, and the sensor’s endpoint to find the request. Use Message ID separately to track acknowledgements and duplicate messages.
Route Overview
This is part 1 of 3. Continue with CoAP Messages: Codes, Tokens, and Options.
Part Objectives
- Read version, type, token length, code, and message ID fields.
- Explain why CoAP keeps a fixed four-byte header.
Start With the First Four Bytes
The leak-sensor request starts with hexadecimal bytes 41 01 22 01 31. This is a prefix: any options follow it. Decode the first four bytes before interpreting byte five.
41is binary01 00 0001: version 1, type 0 (Confirmable), and Token Length (TKL) 1. Confirmable means the sender expects an acknowledgement and can retransmit if it is missing.01is the Code for GET, a request to read a resource.22 01is the two-byte Message ID0x2201.31is the one-byte Token0x31; it is outside the fixed header.
The first byte packs three fields; Code takes the next byte; Message ID takes the last two header bytes. After the header, read exactly TKL Token bytes. Options—numbered metadata fields such as a resource path—start after those bytes. If application content follows the options, a payload marker byte 0xFF separates it from them.
- In 60 Seconds
- Start With the First Four Bytes
- Quick Check: Token Versus Message ID
- Key Concepts
- For Beginners: CoAP Message Format
- Prerequisites
- Why CoAP’s Format Exists: Design Rationale
- Checkpoint: Format Constraints
- Continue: CoAP Wire Format and Option Encoding
Learning Objectives
Use the leak-sensor trace to:
- Decode version, type, TKL, Code and Message ID from four header bytes.
- Locate the Token and the start of options without treating Token bytes as metadata.
- Match a delayed response to an outstanding request using the peer endpoint and Token.
- Explain the four-byte header size from its field widths without assuming a fixed total message size.
- Fixed header: The first four bytes, containing version, type, TKL, Code and Message ID.
- Confirmable (CON): A message that requests acknowledgement; retries can still end in failure.
- Non-confirmable (NON): A message that does not request a CoAP acknowledgement.
- Acknowledgement (ACK): A message acknowledging a Confirmable message. An empty ACK carries no application response.
- Token: The value used with the peer endpoint to correlate a response with its request.
- Message ID: The field used for duplicate detection and to match ACK messages or Reset messages (which reject an unrecognized message) to the messages they refer to.
For Beginners: CoAP Message Format
In the example, 41 01 22 01 is the header and 31 is the Token. Together they occupy five bytes before any options or payload. Four bytes is the fixed header size, not the total message size. In this base format, TKL may specify zero through eight Token bytes; zero means no Token bytes follow.
Prerequisites
Before diving into this chapter, you should be familiar with:
- CoAP Introduction - Understanding why CoAP exists and its design goals
- Binary number representation (bits, bytes, hexadecimal notation)
Why CoAP’s Format Exists: Design Rationale
The example’s first byte divides into 2 version bits, 2 type bits and 4 TKL bits. Code adds 8 bits and Message ID adds 16: 2 + 2 + 4 + 8 + 16 = 32 bits, or four bytes. This explains the specified size; it does not establish that four bytes is a theoretical minimum.
| Field | Width | What to decide in the example |
|---|---|---|
| Version | 2 bits | 01 selects version 1. |
| Type | 2 bits | 00 selects CON; ACK is type 10. |
| TKL | 4 bits | 0001 says to read one Token byte next. |
| Code | 8 bits | 01 requests GET. A response uses a response code. |
| Message ID | 16 bits | 2201 identifies this message for acknowledgement matching and duplicate detection. |
A fixed binary header gives the parser known field positions. It does not promise that the whole message fits a particular link frame: Token, options, payload and lower-layer headers also consume space. UDP avoids TCP connection setup for this exchange, but the client still retains outstanding requests and Tokens, and Confirmable messages require reliability state.
Now transfer the matching rule. The same controller sends a second request to the same sensor with Token 32 and Message ID 2202. A delayed separate response carries Token 31 and Message ID 7800. It answers the first request: the peer and Token match. The new Message ID belongs to the response’s own message exchange. Do not assign it to the latest request just because it arrived last.
Transfer the boundary rule too. If the request prefix becomes 42 01 22 02 31 32, the first byte is 01 00 0010, so TKL is two. Both 31 and 32 are Token bytes. Options start at byte offset 6, counting the first header byte as offset 0.
Checkpoint: Format Constraints
Predict before reading the answers:
- For
41 01 22 01 31, where can the first option begin? Answer: offset 5: four header bytes plus one Token byte. - A separate response from the sensor has Token
32and a new Message ID. Which request does it answer? Answer: the second request, because that peer and Token match; a new Message ID does not break response correlation. - Does an empty ACK for Message ID
2201prove a successful sensor reading? Answer: no. It acknowledges the request message but contains no application response.
Continue: CoAP Wire Format and Option Encoding
You can now separate the fixed header from the Token and distinguish message tracking from response matching. To decode option numbers, response-code bits and payload boundaries in a complete trace, continue to CoAP Wire Format and Option Encoding.
Decode the previously unseen CoAP-over-UDP request prefix 43 01 6A B4 A1 B2 C3 (hexadecimal). Which reading gives version, type, TKL, Code, Message ID, Token and the zero-based offset where options can begin?
Version 1, CON, TKL 3, GET, Message ID 0x6AB4, Token A1 B2 C3; options at offset 7.
Correct. 43 splits into 01/00/0011: version 1, CON, TKL 3. Code 01 is GET; 6A B4 is Message ID 0x6AB4. Read three Token bytes after the four-byte header, so options can begin at 4 + 3 = 7.
Decode a different request prefix: 44 01 8D E2 11 22 33 44 (hexadecimal). Which reading gives its header fields, Token and the zero-based offset where options can begin?
Version 1, CON, TKL 4, GET, Message ID 0x8DE2, Token 11 22 33 44; options at offset 8.
Correct. 44 splits into 01/00/0100, so TKL is 4. Code 01 is GET and Message ID is 0x8DE2. Four header bytes plus four Token bytes puts the options boundary at offset 8.
Continue to the Next Part
Carry this evidence into CoAP Messages: Codes, Tokens, and Options, which begins with The CoAP Message Format.




