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.
- CoAP means the compact request-and-response method used here.
- Firmware is the stored device code and its version.
- A payload is the useful content carried inside a message.
Major section
Start With the Packet Capture (continued)
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 useful question is not "is CoAP broken?" It is whether the decoder walked the bytes in the same order the sender encoded them: fixed header, token, option delta, option length, option value, payload marker, payload.
- 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
In the base CoAP-over-UDP format used here, every 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.
Major section
Overview: Four Fixed Bytes, Then Everything Else Is Optional (continued)
The Code byte is the hinge of the whole format.
- 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.
- The whole fixed header is four bytes.
Major section
Overview: Four Fixed Bytes, Then Everything Else Is Optional (continued)
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.
- Payload markerA single 0xFF byte separates options from payload.
- 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 ItselfThe 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 reply begins 0x64 (Version 1, Type 2 = ACK, TKL 4), then Code 0x45 which decodes as 2.05 Content, then the same Message ID 0x3721 and the same 4-byte Token.
- 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.
- The payload marker is not optional once payload bytes exist.
- Without 0xFF, a parser must keep reading option nibbles until the datagram ends; it cannot know that 32 starts a text reading.
- 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.
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.
- This runway does not prove delivery, identity, or physical action.
- In the base CoAP-over-UDP format used here, every message starts with the same 4-byte fixed header.
- The Code byte is the hinge of the whole format.
- If the first byte is 0x44, its bits are 01 00 0100: Version 1, Confirmable, and a 4-byte Token.
Retrieval practice
Recall check 1 of 6
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: D Correct for base RFC 7252: TKL 0–8 gives the Token length, so options begin after those bytes.
Retrieval practice
Recall check 2 of 6
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: C 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 6
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).
Retrieval practice
Recall check 4 of 6
Broker Bex says: answer from memory, then check your reasoning.
Q4A CoAP URI has consecutive path segments. How is the option number encoded for the later Uri-Path segment?
Show answer
Answer: D Both segments use the same option number, so the difference is zero.
Retrieval practice
Recall check 5 of 6
Broker Bex says: answer from memory, then check your reasoning.
Q5A packet has a token and options but no payload. Where does parsing stop?
Show answer
Answer: D The marker appears only when payload bytes follow.
Retrieval practice
Recall check 6 of 6
Broker Bex says: answer from memory, then check your reasoning.
Q6A CoAP parser sees an option delta that uses an extension nibble. What should it do before reading the value?
Show answer
Answer: C Nibble 13 or 14 adds its base offset before the decoded delta is added to the previous option number.
Print reference
Answers 1 of 2
Answer key.
- D · Correct for base RFC 7252: TKL 0–8 gives the Token length, so options begin after those bytes.
- C · 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).
- D · Both segments use the same option number, so the difference is zero.
- D · The marker appears only when payload bytes follow.
Print reference
Answers 2 of 2
Answer key.
- C · Nibble 13 or 14 adds its base offset before the decoded delta is added to the previous option number.