CoAP Block-Wise Transfer Workbench

Animate RFC 7959 Block1 and Block2 transfers, block fields, retries, size negotiation, and completion rules.

Interactive CoAP block-wise transfer workbench for learning Block1 uploads, Block2 downloads, NUM/M/SZX option fields, 2.31 Continue, 2.05 Content, 4.08 and 4.13 error cases, block-size negotiation, and constrained-network tradeoffs.

CoAP RFC 7959 Block1 / Block2

CoAP Block-Wise Transfer Workbench

Break a large request or response body into CoAP blocks. Step through each request and response, inspect the NUM/M/SZX option fields, test server size negotiation, and see why smaller blocks trade throughput for recoverability on constrained links.

Direction Block2 download

Progress 0 / 16 blocks

Active option 2:0/1/256

Diagnosis Ready

1

Pick direction

Block1 is for a large request payload, such as PUT firmware. Block2 is for a large response payload, such as GET configuration.

2

Choose block size

SZX encodes 16 to 1024 byte blocks using 2^(SZX+4). Smaller blocks retry cheaply but need more exchanges.

3

Watch the M bit

The transfer continues while M=1. The final block has M=0; do not rely only on a size estimate.

4

Read the response

Block1 uses 2.31 Continue until the final block. Block2 returns 2.05 Content blocks requested by the client.

Animated transfer

A client retrieves a large resource from a constrained server in Block2 response chunks.

1. Prepare Choose size and direction.

2. Request Client asks for a block.

3. Response Server returns a code and option.

4. Complete Stop when M is zero.

C

Client Requests block 0 and reassembles the body.

GET /config Block2 NUM=0 ->

Request Block2: 0/0/256

<- 2.05 Content Block2 NUM=0

Response Block2: 0/1/256

S

Server Sends one response block and sets M if more remain.

Body split into blocks 16 blocks shown

NUM

Zero-based block number.

0

M bit

One means more blocks follow.

1, more

SZX

Block size exponent.

4 -> 256 B

Byte range

Payload span in this block.

0-255

Ready to transfer

Use Step to watch the first request/response exchange. The option readout uses the RFC shorthand Block2 NUM/M/size.

Event trace

Controls

Start with a preset, then change size, direction, and loss behavior.

Scenario Configuration download Firmware upload Sensor log download Lossy field link Server asks for smaller blocks

Transfer direction

Payload size

512 B

4096 B

32 KB

Requested block size 16 B (SZX 0) 32 B (SZX 1) 64 B (SZX 2) 128 B (SZX 3) 256 B (SZX 4) 512 B (SZX 5) 1024 B (SZX 6)

Server accepted maximum 64 B maximum 128 B maximum 256 B maximum 512 B maximum 1024 B maximum

Simulate one lost response. In CON mode, the client retries the same block instead of restarting the whole body. Use Confirmable messages. Each exchange has ACK/retry behavior; NON has lower overhead but no automatic message-layer retry.

Quick Reference Find the rule without reading the whole page

Question	Fast answer	Why it matters	Watch out
Which option do I use?	Block1 for request payloads, Block2 for response payloads.	It tells you whether the big body is travelling client-to-server or server-to-client.	Both options can appear in both message directions, but each pertains to its own payload direction.
How is block size encoded?	size = 2^(SZX+4), with SZX 0 to 6 for 16 to 1024 bytes.	Receivers can negotiate a smaller block that fits their memory and link constraints.	Larger blocks reduce exchanges but make each loss more expensive.
When is transfer complete?	The final block has M=0.	The M bit is the completion signal for this transfer.	Size1/Size2 are estimates or hints; the end is governed by the M bit.
What happens on Block1 upload?	Non-final blocks normally receive 2.31 Continue; the final block gets success or an error.	The server can assemble or stream request body blocks before applying the change.	Missing earlier blocks can produce 4.08 Request Entity Incomplete.
What happens on Block2 download?	The client requests each NUM and the server returns 2.05 Content with payload.	The client reassembles the response representation one block at a time.	Dynamic resources should use ETag checks if consistency matters.

Option value

The compact integer is (NUM << 4) + (M << 3) + SZX. This workbench displays the human-readable shorthand NUM/M/size.

NUM starts at 0 M is 0 or 1 SZX 0..6

Block1 upload

Use for PUT or POST request bodies that are too large for one message. The final block is where an atomic create or replace normally takes effect.

PUT/POST 2.31 Continue 4.13 too large

Block2 download

Use for a large response body. The first GET can include a preferred Block2 size; follow-up GETs ask for later block numbers.

GET response 2.05 Content ETag for consistency

Learning Support Independent learner guide

First task

Keep the default configuration download, click Step twice, and compare the request option with the response option. The request asks for a block; the response says whether more blocks follow.

Tradeoff task

Change 256 B to 64 B, then watch block count rise. This is useful when links are lossy or buffers are small, but it increases request/response overhead.

Troubleshooting task

Select the capacity scenario. The server accepts a smaller maximum, so the client must adapt to the lower SZX instead of insisting on its original block size.

Technical Accuracy Notes What is simplified and what follows the RFCs

Model scope

This is a teaching model for payload splitting and message sequence. It does not attempt to calculate exact link-layer airtime, DTLS overhead, OSCORE overhead, or implementation-specific buffering.

Retries

The lost-response path uses CoAP Confirmable message behavior from RFC 7252. It shows a retry of the same block exchange, not a new transfer of the entire body.

Size indications

Size1 and Size2 can communicate body-size estimates, but they do not by themselves end the transfer. The workbench uses the M bit as the transfer-completion rule.

RFC 7959: CoAP Block-Wise Transfer RFC 7252: CoAP Core Protocol