CoAP · Study deck
CoAP Wire Format and Option Encoding
A leak sensor requests the path sensors/temp, but a decoder reports only sensors.
Broker Bex is your guide for this deck.
After studying this chapter
Learning objectives
You will be able to:
- Decode the first fixed-header byte into Version, Type, and Token Length before reading the rest of a packet.
- Translate CoAP Code bytes into request methods or response classes using class/detail notation.
- Parse option delta/length bytes, extension nibbles, critical/elective option behavior, and repeated Uri-Path segments.
- Mark Message ID, Token, option, payload marker, and payload boundaries in a byte-level trace.
Major section
Start With the Packet Capture
The bytes may parse cleanly while an old unit, wrong option, or repeated command leads the receiving code to the wrong decision.
- A protocol is a shared set of rules for exchanging data.
- CoAP means the compact request-and-response method used here.
- Firmware is the stored device code and its version.
Major section
Start With the Packet Capture (continued)
A payload is the useful content carried inside a message.
- This runway does not prove delivery, identity, or physical action.
- The deeper sections show how header bits, option order, extended fields, content markers, and release checks support a bounded decode.
- The goal is to make every nibble explainable before a firmware bug, proxy bug, or malformed request can hide behind a generic error code.
Major section
Overview: Four Fixed Bytes, Then Everything Else Is Optional
Every CoAP message starts with the same 4-byte fixed header.
- After those four bytes comes the Token (exactly TKL bytes), then zero or more Options, and finally — only if there is a payload — a single 0xFF marker byte followed by the payload.
- The Code byte is the hinge of the whole format.
Major section
Overview: Four Fixed Bytes, Then Everything Else Is Optional (continued)
The whole fixed header is four bytes.
- One byte tells a parser whether it is looking at a request or a response and what happened.
- A fast sanity check is to decode the first byte before reading anything else.
- Payload marker A single 0xFF byte separates options from payload.
Major section
Overview: Four Fixed Bytes, Then Everything Else Is Optional (continued)
That single decision prevents the common off-by-four error where a decoder treats token bytes as Uri-Path option bytes and reports a nonsense resource.
- If the first byte is 0x44, its bits are 01 00 0100: Version 1, Confirmable, and a 4-byte Token.
- That compactness is the reason CoAP fits in a single UDP datagram on a constrained link.
- No marker means no payload.
Major section
Practitioner: Options Are Delta-Encoded TLVs, Not a Header Block
CoAP does not carry named text headers.
- Each option is written relative to the previous one.
- A one-byte prefix holds a 4-bit option delta (the increase in option number since the last option) and a 4-bit length.
- This delta scheme is why URI paths become several small options.
Major section
Practitioner: Options Are Delta-Encoded TLVs, Not a Header Block (continued)
The path /sensors/temp is two Uri-Path options (number 11), one carrying sensors and one carrying temp.
- Each query parameter is a separate Uri-Query option (number 15).
- The media type of a payload is one Content-Format option (number 12) holding a compact numeric ID rather than a MIME string.
- Even numbers are Elective: a recipient may silently ignore them.
Major section
Practitioner: Options Are Delta-Encoded TLVs, Not a Header Block (continued)
Option Class Is Encoded in the Number Itself The parity of the option number decides how an unknown option is treated.
- Odd numbers are Critical: a server that does not understand a critical option in a request must reject it with 4.02 Bad Option.
- So Uri-Path (11, odd) is critical, while Content-Format (12, even) is elective.
- Content-Format is a numeric ID, not a MIME string; CBOR (60) or SenML+CBOR (112) can reduce a tight byte budget.
- Options must arrive in ascending option-number order because each delta depends on the previous number.
Major section
Under the Hood: Decoding a Real GET Byte by Byte
On the wire it is a short sequence of bytes, and every one has a defined meaning.
- The table walks the request; nothing here is padding.
- The fixed header consumes offsets 0 through 3.
- TKL says the next four bytes are Token, so Options begin at offset 8.
Major section
Under the Hood: Decoding a Real GET Byte by Byte (continued)
The first option byte is then decoded as a delta from previous option number 0.
- Identifies this CON for its ACK and for duplicate detection.
- The payload marker is not optional once payload bytes exist.
- With the marker present, anything after it is application payload and is interpreted using Content-Format.
Major section
Decode Two Path Segments without a Slash Byte
The Code byte is 0x01.
- Uri-Path has option number 11.
- Relative to the initial option number zero, the delta is 11 and the length is 7, so its option header is 0xB7.
- The slash separates URI segments in a human-readable address; it is not a value byte between these two encoded options.
Major section
Decode Two Path Segments without a Slash Byte (continued)
The next segment temp uses the same option number: the delta is zero, its length is 4, and its header is 0x04.
- The total is 4 + 1 + 8 + 5 = 18 bytes.
- A decoder that assumes every request contains a marker will fail on this valid empty-body GET.
- The decoder consumes the next option's header as part of the path value, shifting its interpretation of the remaining bytes.
Major section
Release Checklist
Byte 0 is decoded into Version, Type, and TKL before reading Code or Message ID.
- TKL determines the exact Token byte count and the offset where options begin.
- Code is interpreted as class/detail, distinguishing requests from success, client-error, and server-error responses.
- Message ID matching and Token correlation are checked separately in request/response traces.
Deck summary
Key takeaways
The bytes may parse cleanly while an old unit, wrong option, or repeated command leads the receiving code to the wrong decision.
- A payload is the useful content carried inside a message.
- Every CoAP message starts with the same 4-byte fixed header.
- The whole fixed header is four bytes.
- That single decision prevents the common off-by-four error where a decoder treats token bytes as Uri-Path option bytes and reports a nonsense resource.
Retrieval practice
Recall check 1 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q1In the CoAP fixed header, what does the 4-bit Token Length (TKL) field tell a parser?
Show answer
Answer: B TKL gives the Token length; the parser reads exactly that many bytes after the fixed header before it starts decoding Options.
Retrieval practice
Recall check 2 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q2A CoAP server receives a request containing an option numbered 11 that it does not recognize. What must it do, and why?
Show answer
Answer: A Odd option numbers are Critical: an unrecognized critical option in a request forces a 4.02 Bad Option response rather than silent processing.
Retrieval practice
Recall check 3 of 3
Broker Bex says: answer from memory, then check your reasoning.
Q3A CoAP message begins with the byte 0x44. What does that first byte tell you?
Show answer
Answer: C 0x44 is 0100 0100: Version = 01 (1), Type = 00 (CON), TKL = 0100 (4).
Print reference
Answers
Answer key.
- B · TKL gives the Token length; the parser reads exactly that many bytes after the fixed header before it starts decoding Options.
- A · Odd option numbers are Critical: an unrecognized critical option in a request forces a 4.02 Bad Option response rather than silent processing.
- C · 0x44 is 0100 0100: Version = 01 (1), Type = 00 (CON), TKL = 0100 (4).