Chapters

CoAP Stack and Trace Contracts: Reference

Related reference: CoAP message types.

Use this reference with CoAP Stack and Trace Contracts. It collects the procedures and records for the chapter’s valve example; the chapter explains how to interpret them.

Acceptance Procedure

Run against a controlled test valve or simulator. Record the server start command, client and server versions, target configuration, resolved address for valve-7, timeout settings and any proxy. Start the server using the implementation lab instructions for the selected stack. Enable per-request handler logs and client pending-state/dispatch logs; capture the interface carrying their traffic.

The fixture exposes GET /valve/position, returning 2.05 Content, Content-Format application/json (50), and {"position_pct":35,"sample_age_ms":20}. Position is measured percent open, range 0–100; sample age is measurement age at response send. The current-display limit is 500 ms. Configure the fixture to send an empty ACK before a delayed separate CON result. Its fault controls must support delaying or dropping that result and substituting malformed, stale and error responses. Record how each fault was injected.

The chapter’s deterministic trace uses request Message ID 100 / Token A1 and response Message ID 700 / Token A1. Generic clients choose their own identifiers: record the actual values and follow the same relationships. Use a configurable test harness when exact identifiers and timing are needed. A CLI payload printout alone cannot verify the application’s pending state or display decision.

Capture and Send

In Wireshark, select the test interface and use capture filter udp port 5683. Start capture before sending the read. On a plain UDP lab path, these libcoap examples request JSON and print diagnostic output:

coap-client -v 7 -m get -A 50 coap://valve-7/valve/position
coap-client -v 7 -m get coap://valve-7/valve/not-present

Use the executable name supplied by the installed libcoap build, and check its help for option support. The absent path must be reserved by the fixture so the expected result is 4.04 Not Found.

  1. Read successfully. Expect CON GET, empty ACK with the request Message ID, then separate CON 2.05 with the request Token and a new Message ID, followed by an ACK for that response. The pending record stays pending after the empty ACK. Match peer and Token, validate JSON and range, and verify recorded response transit plus processing of 30 ms. Age at display is 20 + 30 = 50 ms, so display 35% and complete the read once.
  2. Reject errors and invalid data. The absent-path request must yield 4.04 and the client’s error path, even if the payload is readable. Repeat the valve GET with fixture responses containing the wrong Content-Format, malformed JSON, an out-of-range position, missing sample age and an age over 500 ms at display. Each must block a current-position display and record the reason. A protocol success code alone does not pass these cases.
  3. Check a change operation. If the fixture implements PUT /valve/target with JSON target_pct, document its success code (for example, 2.04 Changed), error cases and completion meaning before using the command below. Compare the response with the handler log and independent resulting-position evidence. A target accepted for later movement does not establish arrival. If the target resource is absent, record this test as unsupported rather than passing it.
coap-client -v 7 -m put -t 50 -e '{"target_pct":0}' coap://valve-7/valve/target

Delay, Restart and Loss

Repeat the successful GET with each controlled fault, saving the trace beside the pending record and application result.

CaseExpected evidence and acceptance decision
Delayed separate resultRequest at 0 ms, empty ACK at 40 ms, result at 240 ms in the chapter fixture. Report both delays; pending remains until a validated result. Measure sample age separately from request delay.
Client restart after empty ACKStop and restart only the test client before the delayed result. Save its old and new pending tables. Late response A1 must not complete an unrelated new request; record whether the old read is recovered or left unresolved.
Separate response lostDrop the delayed response through the fixture’s fault control. Inspect separate-CON retries and the configured application timeout. A valid retry may complete once; exhaustion yields a timeout, never a successful display based on the empty ACK.
Duplicate responseDeliver response 700 again. Expect stack duplicate handling and no second application completion; inspect the response acknowledgement behavior.
Stale representationReturn a measurement whose age at display exceeds 500 ms. Withhold a current display even if code, Token and format are correct.
Expired proxy cacheRecord Max-Age, cache residence time and origin traffic. Require revalidation or a fresh response before reuse as fresh; also apply the measurement-age limit.

Do not infer a failure’s cause from a missing screen update alone. Pair packets with dispatch and handler records. Do not reuse a Token for a new operation while a late response could still be mistaken for its result.

Observe and Security

If the valve resource supports Observe, register for a short test window:

coap-client -v 7 -m get -A 50 -s 30 coap://valve-7/valve/position

Expect an Observe registration and later notifications using the registration Token, with new Message IDs for new notification messages. Compare the observation record and dispatch log with the capture, then check ordering, format, range and sample age. A log rejecting new Message IDs despite the correct peer and registration Token identifies the correlation bug. Check cancellation and recovery under the chosen stack’s documented behavior.

For a DTLS deployment, use its configured coaps:// endpoint and credentials according to the security contract. Capture filter udp port 5684 and display filter dtls && udp.port == 5684 expose handshake and record activity on the standard secure port. Adapt both to a configured alternative port. Run repeated reads on one established client context to assess session reuse, then test expired-session recovery. Separate CLI invocations may create separate security contexts, so their handshakes alone do not demonstrate a reuse bug. Encrypted captures need endpoint logs or an authorized decryption setup for CoAP fields; record types alone do not prove authentication or cipher configuration.

A new pending record is peer=valve-9:5683, Token=B2, GET /valve/position, status=pending. The client sends CON MID 210, receives empty ACK 210, then receives CON MID 880, Token B2, 2.05 Content from valve-9:5683 with payload {“position_pct”:62}. Which decision is justified before displaying a current position?

Match peer and Token B2 to the pending read; ACK MID 880; require the documented payload format, units/range and sample freshness evidence before displaying it as current.

Correct. MID 210 matched the request ACK; MID 880 identifies the separate response for acknowledgement. Peer and Token connect it to GET /valve/position. A 2.05 and readable payload still need Content-Format, handler meaning and valid age evidence; this trace supplies no sample age, so withhold a current-position display.

An Observe client no longer needs temperature updates and wants to end its registration explicitly. Which request does that?

Send a GET with Observe:1 using the registered Token.

Correct. Observe:1 deregisters the established observation.

Tools and Evidence

ToolCommand or filterEvidence suppliedLimit
libcoap coap-clientcoap-client -v 7 -m get -A 50 coap://valve-7/valve/positionReturned code, payload and available client diagnosticsDoes not establish the product client’s validation or physical valve movement.
Wireshark, plain CoAPCapture: udp port 5683; display: coap && udp.port == 5683Message types, Message IDs, Token, code, options and retransmissionsLimit to the resolved valve address when other devices share the capture.
Wireshark, DTLSDisplay: dtls && udp.port == 5684Handshake patterns and protected record trafficDoes not expose encrypted CoAP fields or prove security configuration by itself.
Server logsPer-request peer, Token, URI/method, code, sample time and send timeHandler behavior and the measurement-age basisMust be correlated with the captured request.
Client logsPending record, dispatch decision, receive/display times and completion countCorrelation, restart handling, age checks and timeout behaviorUse a consistent time basis or a documented bound for transit and processing.
Device feedbackMeasured position and command/result timestampsResulting physical state under the handler contractACKs and target-set logs alone cannot establish arrival.

Release Checklist

Before shipping, retain these records with the tested build:

  • Stack and target: library/version, configuration, memory fit, required Observe/security support and intended client interoperability.
  • Resource table: each URI and method mapped to its handler, success/error codes, payload type, Content-Format, units/range and completion meaning.
  • Client validation: branch on response.code before trusting response.payload; retain success, documented error, malformed and stale-data results.
  • Correlation and recovery: peer/Token/pending context for ordinary and separate responses; observation context for notifications; Message IDs for ACKs and duplicate detection. Include restart, loss, timeout and duplicate evidence.
  • Message policy: explain CON versus NON choices and which valve telemetry losses the application tolerates.
  • Freshness: sample-age definition and display limit, measured or bounded transit/processing, Max-Age, cache residence and proxy revalidation behavior.
  • Security: identify plain CoAP, DTLS or Object Security for Constrained RESTful Environments (OSCORE), which protects CoAP messages at the application layer. For DTLS retain configuration, session reuse and recovery evidence; use the security-contract page for authentication and replay checks.
  • Physical outcome: distinguish receipt, a validated measurement and arrival at a commanded position; retain device-state evidence where a command claims completion.

Quick Reference

ItemRecall
Transport and URIPlain UDP commonly uses port 5683, coap://host:port/path; DTLS commonly uses 5684, coaps://host:port/path.
MethodsGET reads; POST creates/processes; PUT updates; DELETE removes.
Message typesCON requests acknowledgement; NON has no required message-layer ACK; ACK acknowledges; RST indicates unavailable message context.
Example codes2.01 Created; 2.04 Changed; 2.05 Content; 4.04 Not Found; 4.05 Method Not Allowed; 5.00 Internal Server Error.
ObserveRegisters for later resource notifications; check correlation, ordering and freshness.
Classic Block1/Block2Individual blocks up to 1024 bytes; this is not the total representation-size limit.

Specific References

Hi, I’m Broker Bex. What do you need?

Find help

Let’s find what you need

Find a lesson or return to your module guide.

Give feedback

Help improve this chapter

Tell us what helped or what needs fixing.

Tips

Try a small next step

A few ways to get more from this chapter.

Ask AI

Continue the conversation

Take the conversation further with your preferred assistant.

AI help is available in supported modules when enabled in Settings.

No live person answers on independent study. Feedback does not promise a personal reply.

For welfare or safety concerns, follow your school’s procedures outside IoTClass.