CoAP glossary
Message fields, exchanges and resources in the lamp-and-thermostat flat.
Accept
Accept names the format requested for the response.
Content-Format identifies the encoding actually carried in the body. A server can reject a requested response format that it does not support.
Boiler example: Ask the thermostat for a JSON temperature response by setting Accept to that format.
Also see: Content-Format, JSON, representation
acknowledgement
An acknowledgement (ACK) confirms receipt of a CON message.
CON means a Confirmable message, which requests acknowledgement and permits a limited number of retries. Missing acknowledgement can mean that the reply was lost, so it does not prove the command was never received.
Boiler example: Check the lamp’s response and resulting state after receiving its ACK.
Also see: acknowledgement (ACK), CON, retransmission
acknowledgement (ACK)
An acknowledgement (ACK) confirms message receipt.
An empty ACK carries no operation result. Even a successful application response needs a defined relationship to the physical lamp state.
Boiler example: Keep the lamp’s receipt acknowledgement separate from evidence that it obeyed the command.
Also see: Confirmable message, empty ACK, acknowledgement
acknowledgment
An Acknowledgment (ACK) confirms receipt of a CON message by its Message ID, the identifier used for message matching.
A confirmable message requests this receipt reply and can be retried within limits. Receipt alone does not prove that the requested action succeeded.
Boiler example: Check the lamp’s acknowledgment separately from the application result and resulting lamp state.
Also see: Confirmable (CON), Message ID, empty ACK
API
An application programming interface, or API, defines requests and their results.
A path identifies the named value or state, and a method specifies the operation to perform. The agreement also says what data to send and what result to expect.
Boiler example: Define how the gateway reads the thermostat’s temperature and replaces its sampling setting.
Also see: resource, method, resource contract
authenticated encryption with associated data
Authenticated encryption with associated data encrypts content and checks integrity, including associated data covered by the protection.
Integrity means detecting changes to protected data. A nonce is a value used by this encryption that must not be reused with the same key.
Boiler example: Protect the thermostat’s reading with authenticated encryption and check that altered protected data fails verification.
Also see: Integrity, Confidentiality, nonce
Authentication
Authentication establishes a peer’s identity.
A peer is the other participant in the exchange. Authorization separately decides whether that identity may perform an operation on a named resource.
Boiler example: Check the lamp controller’s identity and its permission to change the lamp state.
Also see: peer, Authorization, Peer authentication
Authorization
Authorization decides whether that identity may use a particular method on a resource.
Authentication establishes who the communicating device or program is. Permission to read a named value or setting does not automatically permit changing it.
Boiler example: Allow the gateway’s controller to change the lamp state while rejecting a write from a client permitted only to read.
Also see: Authentication, resource, method
block transfer
Block transfer splits a representation into smaller exchanges.
A representation is the encoded data describing a resource. Block1 carries pieces in requests, while Block2 carries pieces in responses.
Boiler example: Transfer the battery sensor’s software image in smaller exchanges and verify the complete image before installation.
Also see: Block-wise transfer, Block1, Block2, Firmware
Block-wise transfer
Block-wise transfer divides a representation into numbered pieces at the application layer.
A representation is the data describing a named resource, such as a sensor reading. Block1 carries pieces of request data, while Block2 carries pieces of response data.
Boiler example: Download the battery sensor’s software image in numbered pieces, keeping each piece in its correct place.
Also see: Block1, Block2, representation
Block1
Block1 carries large request bodies.
Block1 carries the pieces of a large body sent in requests, while Block2 carries pieces returned in responses. A repeated piece must not be stored twice.
Boiler example: Send a software image to the battery sensor in PUT requests, which ask it to store the supplied image, using Block1.
Also see: Block2, Block-wise transfer, M
Block2
Block2 carries large response bodies.
GET, the operation for retrieving a named value or state, can return firmware in numbered response pieces. Repeated pieces belong at their recorded byte positions rather than being appended again.
Boiler example: Let the battery sensor fetch its replacement firmware in Block2 responses.
Also see: Block1, Block-wise transfer, Firmware
cache
A cache stores responses for reuse.
Max-Age limits how long a stored response may be reused as fresh. Forwarding the response through a gateway does not restart that allowance.
Boiler example: Reuse the gateway’s cached thermostat response only while its freshness allowance remains valid.
Also see: Max-Age, proxy, representation
Cache key
The cache key is the request information used to select a stored response.
A cache stores responses for reuse. Check the matching key, remaining freshness allowance and access permission before sharing a stored response.
Boiler example: Check the cache key before the gateway reuses a stored thermostat temperature response.
CBOR
CBOR, the Concise Binary Object Representation, is a binary data format, not compressed JSON.
A binary format represents data as bytes rather than JSON, a text format of named values. Comparing formats must preserve the same information rather than drop fields.
Boiler example: Encode the thermostat’s device identity, reading and unit in CBOR while preserving all three fields.
Also see: JSON, representation, Content-Format
client
A client is the program making a request.
The server answers the request. The requested resource is a named value or state, such as a temperature reading.
Boiler example: Use the gateway as the client when requesting the thermostat’s temperature.
Coalescing
Coalescing combines changes into an update containing the latest state when changes exceed the transmission budget.
The resulting update contains the latest state rather than every intermediate change. Record the sending policy and compare actual traffic before claiming savings.
Boiler example: Combine rapid thermostat changes into an update carrying the latest temperature when the sending budget is exceeded.
Also see: notification, Observe, polling
CoAP
CoAP, the Constrained Application Protocol, gives small devices rules for exchanging messages.
A program making a request is the client, and the device answering it is the server. Message acknowledgement, the reported result and the physical action need separate evidence.
Boiler example: Use CoAP for the gateway’s lamp commands and thermostat temperature requests.
CoAP option
Options are named CoAP fields describing the request.
These fields can describe details such as the resource path. If a protected connection ends at the gateway, the gateway can recover the fields it protected.
Boiler example: Check which request options the gateway can read when it handles the thermostat’s protected request.
Code
The Code names the requested operation or its result.
GET requests a resource reading, while a response code reports the result. The Code has a separate job from the Message ID used to match acknowledgments.
Boiler example: Check the Code in the thermostat’s reply before accepting its temperature reading.
Also see: method, response code, Message ID
Code
The Code states the requested method or reported result.
A method names the operation requested, while a response reports its result. An empty acknowledgment uses an empty Code and carries no operation result.
Boiler example: Inspect the lamp’s response Code before claiming that its setting change succeeded.
Also see: Code, method, response code, empty ACK
CON
A confirmable (CON) message requests acknowledgement and bounded retransmission when no acknowledgement arrives.
Bounded retransmission means resending stops at a limit, so CON does not guarantee delivery. An acknowledgement confirms receipt and does not prove that a lamp performed the requested action.
Boiler example: Choose CON for the lamp command whose loss matters, then check the reported result and lamp state.
Also see: Confirmable (CON), acknowledgement (ACK), retransmission
Confidentiality
Confidentiality hides protected data from parties without the key.
Datagram Transport Layer Security (DTLS) protects the message between its configured peers. If that protection ends at the gateway, the gateway can read the decrypted content.
Boiler example: Check whether the gateway is allowed to read the thermostat’s temperature before ending DTLS protection there.
Also see: DTLS, Integrity, security context
Confirmable (CON)
A Confirmable (CON) request expects acknowledgement and permits retransmission if none arrives.
An acknowledgement confirms message receipt, while an empty acknowledgement carries no request result. Retries stop at a limit, and a successful result still needs a defined relationship to physical device state.
Boiler example: Send the lamp’s set-off command as CON and check the result before recording that the lamp obeyed.
Also see: acknowledgement (ACK), retransmission, Non-confirmable (NON)
- Where used: CoAP Messages: Format Foundations
- Where used: CoAP Message Exchanges
- Where used: CoAP Exchange Reliability Contracts
- Where used: CoAP Methods and Multicast
- Where used: CoAP API Design: Delivery and Security Decisions
- Where used: CoAP Observe Freshness Contracts
- Where used: CoAP Security: Protection and Application Fit
- Where used: CoAP Security: Implementation and Operations
- Where used: CoAP Lab: Stack and Trace Contracts
- Where used: CoAP Lab: Message Construction
- Where used: CoAP Stack and Trace Contracts
Confirmable message
A Confirmable message requests an acknowledgement and supports bounded retransmission.
An acknowledgement confirms receipt, and retransmission means sending the same message again. Retries stop at a limit, so receipt and the lamp’s physical action still need separate checks.
Boiler example: Send the lamp command as a Confirmable message, then check the response and resulting lamp state.
Also see: acknowledgement (ACK), retransmission, Duplicate suppression
Content-Format
Content-Format identifies the encoding of a message’s body.
The body is the data carried in the message. Knowing its encoding does not establish that its values meet the application’s rules.
Boiler example: Check the thermostat response’s Content-Format before decoding its temperature data.
CoRE Link Format
CoRE Link Format is a comma-separated list of resource links and attributes.
A server supporting discovery returns these links when asked for /.well-known/core. Their attributes describe capabilities, such as resource type and support for observing changes, without granting access.
Boiler example: Read the advertised links to distinguish the thermostat’s temperature resource from the lamp’s control resource.
Also see: Resource discovery, resource, Content-Format
critical option
A critical option has an odd number; a server must reject a request containing an unrecognized critical option with 4.02 Bad Option.
An option is a numbered field carrying a message detail. Locate and decode the field before deciding whether it is understood, because the error response alone does not identify the offending byte.
Boiler example: Have the thermostat reject the gateway’s request if it contains a critical option the thermostat does not recognize.
Also see: option, elective option, response code
datagrams
Here we use its base format over User Datagram Protocol (UDP), which carries separate messages called datagrams.
Here the format is the base Constrained Application Protocol (CoAP) format carried over UDP. A resource is a named item a device exposes, and the receiver must locate its message fields correctly before interpreting the request.
Boiler example: Inspect the battery sensor’s received datagram to locate the request fields before reading its resource path.
Also see: CoAP, fixed header, Uri-Path
delta encoding
In delta encoding, each option stores the increase from the previous option number.
An option is a numbered message field. Follow the encoded value lengths to find field boundaries rather than guessing where a value ends.
Boiler example: Decode the thermostat request’s option-number increases and lengths before reconstructing its path.
Also see: option, option delta, Uri-Path
DTLS
Datagram Transport Layer Security (DTLS) protects messages between its connection endpoints.
If the gateway is an allowed reader, Datagram Transport Layer Security can protect traffic from the device to the gateway. The gateway can read the decrypted message, so any onward path needs its own protection decision.
Boiler example: Use DTLS between the thermostat and the gateway when the gateway is allowed to read the temperature.
Also see: Object Security for Constrained RESTful Environments (OSCORE), pre-shared key (PSK), Peer authentication
- Where used: CoAP API Design: Delivery and Security Decisions
- Where used: CoAP Advanced Features
- Where used: CoAP Security: Protection and Application Fit
- Where used: CoAP Security: Implementation and Operations
- Where used: CoAP Security: CON and NON Trade-Offs
- Where used: CoAP DTLS/OSCORE Security
- Where used: CoAP Lab: Message Construction
Duplicate suppression
Duplicate suppression recognizes a recent message by source endpoint and MID and reuses its acknowledgement.
The source endpoint is the sender’s address and port, and MID means Message ID. This record lasts for a limited exchange period and is not permanent command history.
Boiler example: Recognize a retried lamp command and reuse its acknowledgement instead of treating the repeated message as a new action.
Also see: Message ID, retransmission, idempotent
elective option
An elective option has an even number; an unrecognized elective option is ignored.
An option is a numbered CoAP field. Content-Format, which identifies the message body’s format, is elective, while an unrecognized critical option requires rejection of the request.
Boiler example: Locate the thermostat reply’s Content-Format field before using it to decode the temperature body.
Also see: critical option, Content-Format, option
empty ACK
An empty ACK acknowledges the request message but carries no operation result or Token.
It uses the request’s Message ID, the identifier for acknowledgment matching. The controller stops retrying that request message and keeps waiting for the result.
Boiler example: Keep waiting for the lamp’s operation result after receiving only an empty ACK.
Also see: acknowledgment, separate response, Message ID
endpoint
An endpoint is a network address and port.
A Token is a client-selected value used to match a response with its request. Check it together with the expected endpoint rather than treating the Token alone as enough.
Boiler example: Match the thermostat’s reply to the gateway’s pending request using its endpoint and Token.
Also see: token, client, server endpoint
ETag
An ETag is a representation identifier that a client can compare across responses.
A representation is the resource data in a particular format and version. A matching ETag supports combining saved blocks from that version, but does not prove who authorized the software.
Boiler example: Compare the battery sensor’s saved software ETag with the resumed response before combining their bytes.
Also see: representation, Block2, Max-Age
Firmware
Firmware is the software installed on a device.
An over-the-air update delivers replacement device software through the network. Receiving every piece still needs separate checks of the complete image and evidence of installation.
Boiler example: Check the battery sensor’s complete firmware image before accepting the update in Pete’s flat.
Also see: Block-wise transfer, Block1, Block2
fixed header
The fixed header is the first four bytes, containing version, type, Token Length, Code and Message ID.
Token Length counts the Token bytes that follow the header. The Code identifies the requested operation or response result, while Message ID supports receipt matching and duplicate detection.
Boiler example: Read the thermostat request’s fixed header before locating its Token and path options.
Also see: token length (TKL), Message ID, Code
handler
A handler is application code that reads or changes a resource.
A resource is a named item that a device exposes. The server registers its handler for a path and method, and the messaging library routes matching requests to that code.
Boiler example: Map the thermostat’s temperature read to the handler that supplies its reading.
idempotence
Repeating the same operation has the same intended effect as applying it once.
Repeating a desired-state assignment leaves the same intended setting. Replies can differ even when repeated operations have the same intended effect.
Boiler example: Repeat the lamp’s request to set its state to on after a lost reply, then check the resulting state.
Also see: idempotent, PUT, readback
idempotent
An idempotent operation preserves its intended state when repeated.
A command that sets a desired state keeps that intended state when repeated. A toggle can reverse the first action if executed again.
Boiler example: Repeat the lamp’s “set off” command while preserving the same intended final state.
Also see: idempotence, PUT, readback
Integrity
Integrity detects changes to protected data.
Modified protected bytes should fail verification. Receipt of a protected message still needs separate checks of permission and the application result.
Boiler example: Check that changing protected bytes in the thermostat’s message causes verification to fail.
Also see: Confidentiality, authenticated encryption with associated data, Authorization
JSON
JSON, or JavaScript Object Notation, represents named values as text.
Content-Format identifies the encoding of the message body. A readable temperature record still needs the agreed fields, such as its value and unit.
Boiler example: Send the thermostat’s temperature value and unit together in a JSON response.
Also see: Content-Format, representation, CBOR
keep-alive
A keep-alive is client-originated traffic sent before mapping expiry.
The mapping lets replies reach the client through a network address translator, or NAT. Keeping an observation registration does not itself keep that network mapping alive.
Boiler example: Send client traffic before the gateway’s mapping expires so later thermostat updates can still reach the display.
Also see: NAT, observation, observer lease
Leisure
Leisure is the response-delay window used to spread multicast replies.
Each responding server chooses a random delay within the window. This reduces simultaneous reply bursts without proving that every device answered.
Boiler example: Let devices delay their discovery replies within Leisure while the gateway collects responses.
Also see: Multicast, Resource discovery, server
Location options
Location options identify the created resource’s location when it differs from the request URI.
A URI is the address identifying a resource. When POST creates a resource at a server-assigned address, retain Location-Path and Location-Query for later access.
Boiler example: Keep the returned Location options when the thermostat creates a configuration resource at a different address.
Also see: Uniform Resource Identifier (URI), resource, response code
M
M, the More flag, indicates whether more data blocks follow.
A value of one means more blocks follow, and zero marks the final piece. The final flag alone does not prove that all bytes arrived or that an update is safe to install.
Boiler example: Check the More flag on the battery sensor’s last software block, then verify the complete image before installation.
Max-Age
Max-Age is the response’s freshness lifetime.
This lifetime is measured in seconds and limits how long a stored response may be reused as fresh. It does not prove that the physical temperature has stayed unchanged.
Boiler example: Mark the thermostat’s saved reading as stale when its Max-Age allowance expires.
Also see: cache, representation, Observe
- Where used: CoAP API Design: Delivery and Security Decisions
- Where used: CoAP Resource Negotiation Patterns
- Where used: CoAP Observe: Subscriptions and Updates
- Where used: CoAP Observe: Efficiency and Lifecycle
- Where used: CoAP Observe Freshness Contracts
- Where used: CoAP Block and Discovery Contracts
- Where used: CoAP Lab: Message Construction
- Where used: CoAP Stack and Trace Contracts
maximum transmission unit (MTU)
The maximum transmission unit (MTU) is the largest IP packet the path can carry without IP fragmentation.
IP fragmentation means splitting an IP packet into smaller pieces. Count network, transport, security and CoAP fields before choosing how much application data an exchange can carry.
Boiler example: Include all packet fields when choosing a software block size for the battery sensor’s network path.
Also see: block transfer, payload, fixed header
Message ID
The Message ID identifies a message for duplicate detection and acknowledgment matching.
Duplicate detection recognizes repeated messages, while an acknowledgement confirms receipt. A Token, the request’s response-matching value, has a separate job from the Message ID.
Boiler example: Match the thermostat’s acknowledgement by Message ID and its later reading by Token and peer.
Also see: token, acknowledgement (ACK), endpoint
- Where used: CoAP Messages: Format Foundations
- Where used: CoAP Messages: Codes, Tokens, and Options
- Where used: CoAP Messages: Parsing and Validation
- Where used: CoAP Wire Format and Option Encoding
- Where used: CoAP Message Exchanges
- Where used: CoAP Exchange Reliability Contracts
- Where used: CoAP Methods and Multicast
- Where used: CoAP Observe Freshness Contracts
- Where used: CoAP Security: Implementation and Operations
- Where used: CoAP Lab: Stack and Trace Contracts
- Where used: CoAP Lab: Message Construction
- Where used: CoAP Stack and Trace Contracts
method
A method says what operation a request asks the resource to perform.
GET asks to read a named resource, while PUT assigns a value at a known target. The response code reports the operation’s result.
Boiler example: Use GET to read the thermostat’s temperature and PUT to request a lamp state.
Also see: resource, response code, PUT
Multicast
Multicast sends one request to a group address.
Eligible devices reply individually to the requester. Missing replies do not prove that every device has been reached.
Boiler example: Use the gateway to send a temperature request to the group and collect replies from the devices that answer.
Also see: Leisure, Resource discovery, Non-confirmable (NON)
NAT
NAT, or network address translation, maintains mappings that allow return traffic through a gateway.
A mapping can expire while a device is idle. Keeping a server’s registration does not preserve the gateway’s mapping.
Boiler example: Check whether the gateway’s NAT mapping remains usable when the battery sensor wakes.
Also see: keep-alive, endpoint, observation
nibble
A nibble is four bits.
In an option header, the upper nibble describes the increase from the previous option number. The lower nibble describes the option value’s length.
Boiler example: Read both nibbles of an option header when decoding the thermostat’s message.
Also see: delta encoding, option delta, option
NON
A non-confirmable (NON) message is a CoAP message that CoAP does not acknowledge or retransmit.
This can suit routine temperature readings when the loss policy allows a missing sample to be replaced by a later one. A request sent this way can still receive a response.
Boiler example: Send a replaceable thermostat reading as NON when an occasional missing reading is acceptable.
Also see: Non-confirmable (NON), Confirmable (CON), notification
Non-confirmable (NON)
A Non-confirmable (NON) message has no message-layer acknowledgement or retransmission.
It suits a stream when an occasional loss is acceptable because a later reading replaces it. A request using this message type can still receive a response.
Boiler example: Use NON for the thermostat’s routine temperature stream when a later reading can replace a lost sample.
Also see: Confirmable (CON), notification, response code
- Where used: CoAP Message Exchanges
- Where used: CoAP Exchange Reliability Contracts
- Where used: CoAP Methods and Multicast
- Where used: CoAP Method/Multicast Contracts
- Where used: CoAP API Design: Delivery and Security Decisions
- Where used: CoAP Observe Freshness Contracts
- Where used: CoAP Security: Protection and Application Fit
- Where used: CoAP Security: Implementation and Operations
- Where used: CoAP Lab: Message Construction
nonce
A nonce is a value used by authenticated encryption that must not be reused with the same key.
Authenticated encryption encrypts content and checks that it has not been altered, including other data covered by the protection. Sender sequence state contributes to the nonce, so losing that state can undermine safe recovery.
Boiler example: Preserve safe sender sequence state when the battery sensor restarts so its protected reports do not reuse a nonce with the same key.
Also see: authenticated encryption with associated data, security context, replay window
notification
A notification is a later response sent for the continuing request.
Observe is the continuing request relationship that allows these later responses. Match that relationship, compare update order and check freshness before using a reading.
Boiler example: Check the thermostat notification’s request match, order and freshness before updating the display.
Also see: Observe, Observe sequence, Max-Age
NUM
NUM is the block number.
A block is a numbered piece of the transferred data. Its number and selected size determine where its bytes belong, so a size change requires recalculating the number.
Boiler example: Place a repeated software block for the battery sensor at its existing byte position instead of appending it.
Also see: Block-wise transfer, SZX, M
Object Security for Constrained RESTful Environments (OSCORE)
OSCORE protects selected CoAP message content between its security endpoints.
A proxy is a device that forwards requests on another program’s behalf. Protection can start at the device and end at the final reader so that the forwarding gateway cannot read selected content.
Boiler example: Protect the thermostat’s selected content from the device to the final reader when the gateway may only forward it.
Also see: DTLS, proxy, security context
observation
An observation is the continuing request relationship.
A notification is a response carrying an update within that relationship. Match the relationship before checking the update’s order and how long its accepted data remains fresh.
Boiler example: Keep the thermostat observation’s identity separate from the displayed temperature’s freshness deadline.
Also see: notification, Observe value, Max-Age
Observe
Observe extends a GET request so the server can send later responses when a resource changes.
The later responses are notifications, and the continuing registration state is an observation. This arrangement suits a display needing current temperature rather than a history of every intermediate reading.
Boiler example: Register the gateway to receive later thermostat temperatures through Observe.
Also see: observer, notification, polling
Observe
Observe registers interest in later resource notifications.
A notification is a later response carrying a resource update. Later notifications retain the registration token, the value matching responses to the request, while their Message IDs can change.
Boiler example: Register interest in the thermostat’s temperature so the display can receive later updates.
Also see: notification, token, Observe sequence, Max-Age
- Where used: CoAP Methods and Multicast
- Where used: CoAP Resource Negotiation Patterns
- Where used: CoAP Observe: Efficiency and Lifecycle
- Where used: CoAP Security: Protection and Application Fit
- Where used: CoAP Lab: Stack and Trace Contracts
- Where used: CoAP Lab: Message Construction
- Where used: CoAP Stack and Trace Contracts
Observe sequence
An Observe sequence is the response value used to order notifications.
The sequence can wrap around, so ordinary numerical comparison alone is insufficient. Matching the request and checking freshness remain separate decisions.
Boiler example: Use the thermostat’s Observe sequence to reject an older update that arrives after a newer one.
Also see: Observe value, notification, Max-Age, token
Observe value
The Observe value is a sequence used to order representations, not a count of delivered events.
A representation is an encoded resource state. An older update must not replace a newer accepted state or extend its freshness deadline.
Boiler example: Compare Observe values before replacing the thermostat’s displayed temperature with an arriving update.
Also see: observation, Observe sequence, Max-Age
observer
An observer is a client registered to receive those updates.
Observe lets a program making requests register for later values of a named resource. A saved temperature can become stale even while that registration remains active.
Boiler example: Register the gateway as an observer of the thermostat’s temperature resource.
Also see: Observe, notification, observation
observer lease
An optional observer lease is a separate application policy limiting how long the server keeps an observation without renewal.
Cleanup must actually run to remove expired registrations. With periodic cleanup, scheduler delays can leave an expired entry present beyond its lease duration.
Boiler example: Apply an observer lease to the gateway’s thermostat registration and run the cleanup that removes expired entries.
Also see: observer, observation, observer registry
observer registry
An observer registry is the server’s retained record of observation relationships.
An endpoint is a network address and port, and a Token is the value that matches responses to a request. Retain these with the resource and format-selecting GET options, refreshing an existing endpoint and Token pair rather than adding a duplicate.
Boiler example: Refresh the thermostat’s existing registry entry when the gateway registers again with the same endpoint and Token.
Also see: observation, endpoint, token
option
An option supplies a numbered detail, such as a path segment or content format.
An option has a number, a length and value bytes. Options appear in number order from lower to higher, and repeated numbers are allowed.
Boiler example: Carry the thermostat resource’s path segments in the gateway request’s options.
Also see: option delta, Uri-Path, Content-Format
option delta
An option delta is the difference from the previous option number, starting at zero.
An option is a numbered detail in the message. Adding its delta updates the option number, while consuming its value bytes advances the byte position.
Boiler example: Decode the option deltas in the gateway’s thermostat request to identify its path segments.
Also see: option, delta encoding, Uri-Path
Options
Options are numbered metadata fields, such as a resource path; they start after the Token bytes.
These fields describe message details such as the path selecting a resource. Read the stated number of token bytes before interpreting any options.
Boiler example: Locate the thermostat’s path options after the token bytes when decoding its request.
Also see: token length (TKL), Uri-Path, payload
payload
A payload carries the message’s data.
A request body can carry a proposed setting, and a response body can carry a temperature reading. Content-Format identifies how that body is encoded.
Boiler example: Read the temperature from the thermostat’s response payload.
Also see: representation, Content-Format, payload marker
- Where used: CoAP Messages: Format Foundations
- Where used: CoAP Messages: Codes, Tokens, and Options
- Where used: CoAP Messages: Parsing and Validation
- Where used: CoAP Wire Format and Option Encoding
- Where used: CoAP Message Exchanges
- Where used: CoAP API Design: Resource and Response Contracts
- Where used: CoAP Security: Protection and Application Fit
- Where used: CoAP DTLS/OSCORE Security
- Where used: CoAP Lab: Stack and Trace Contracts
- Where used: CoAP Lab: Message Construction
- Where used: CoAP Stack and Trace Contracts
payload marker
A payload marker is 0xFF at an option boundary, introducing a nonempty payload.
The payload is the application content after the message fields. The same byte inside a token or option value is data, and a marker without following content is malformed.
Boiler example: Find the payload marker at the option boundary before reading the thermostat’s temperature data.
Also see: payload, Options, token length (TKL)
peer
A peer is the other endpoint in an exchange.
An endpoint is a network address and port. Match a later response using that peer, the request identifier called the Token, and the operation still awaiting a result.
Boiler example: Match the thermostat’s delayed reading against the peer the gateway originally asked.
Also see: endpoint, token, separate response
Peer authentication
Peer authentication establishes the identity of the communicating peer; either credential arrangement needs a maintained lifecycle.
A pre-shared key is a secret provisioned to the communicating peers, while certificate authentication uses public-key credentials. Operators must be able to provision, replace and revoke the chosen credentials.
Boiler example: Check the battery sensor’s configured peer identity and maintain the credentials used for that check.
Also see: Authentication, pre-shared key (PSK), trust anchor
piggybacked response
A piggybacked response carries the result inside the acknowledgement.
The acknowledgement confirms receipt, while the included answer reports the operation’s result. A separate response sends that result later in a new message exchange.
Boiler example: Return the thermostat’s ready temperature reading inside the acknowledgement to the gateway’s request.
Also see: acknowledgement (ACK), separate response, token
polling
Polling means repeatedly requesting a reading.
GET is the method for reading a named resource. Observe extends a GET so the server can send later updates instead of requiring a fresh question for each reading.
Boiler example: Ask the thermostat for its current temperature repeatedly when using polling.
Also see: method, Observe, representation
pre-shared key (PSK)
A pre-shared key (PSK) is a secret provisioned to the communicating peers.
The peers are the two ends communicating with each other. Operators need to provision, replace and revoke their shared secret securely.
Boiler example: Provision a shared secret to the thermostat and gateway when choosing PSK credentials for their protected exchange.
Also see: DTLS, Peer authentication, peer
proxy
A proxy forwards requests on a client’s behalf and may use a cache.
It may store a response for reuse when the request and caching rules permit. A stored temperature reading still needs a check of its remaining freshness allowance.
Boiler example: Let the gateway request the thermostat’s temperature on the display’s behalf.
PUT
PUT requests a change to a resource’s state.
An acknowledgement confirms receipt rather than proving the requested change happened. If the resource does not support PUT, its error response cannot be fixed by increasing the retry timeout.
Boiler example: Check the thermostat’s response to the gateway’s PUT before recording that its reporting interval changed.
Also see: method, resource contract, response code
readback
A readback is a read of the setting after a write to check the resulting state.
A successful write response and a later read provide separate evidence about a stored setting. Stored configuration alone does not prove the physical lamp acted.
Boiler example: Read the lamp’s stored setting after a write, then check its physical behavior separately.
Also see: PUT, response code, resource contract
replay
A replay is a copied protected message sent again.
Encryption alone does not prove that a request is new. Rejecting a repeated protected message is separate from reusing a saved reply to avoid repeating an application operation.
Boiler example: Replay a captured protected thermostat message and check that it causes no new application delivery.
Also see: Replay state, replay window, Duplicate suppression
Replay protection
Replay protection rejects reuse of old protected messages using security context state.
A security context holds keys and the state used to protect and verify messages. Rejecting a reused protected command does not decide whether a newly issued command is permitted or safe.
Boiler example: Reject a captured protected lamp command when it is sent again, and check permission for new commands separately.
Also see: replay, security context, Authorization
Replay state
Replay state records information used to reject repeated protected traffic.
Safe security state must remain usable across device sleep or restart. Resetting a sender counter while reusing the same keys and associated state is unsafe.
Boiler example: Check the battery sensor’s retained replay state before sending protected readings after sleep.
Also see: replay, replay window, security context
replay window
The recipient’s replay window identifies duplicate protected requests while allowing the configured range of reordered requests.
A protected request can arrive again or arrive out of order. Preserving replay-checking state matters across restart, while checking the age of application data remains a separate task.
Boiler example: Check a repeated protected request from the battery sensor against the recipient’s replay window after restart.
Also see: replay, Replay protection, security context
representation
A representation is an encoding of a resource’s data.
A resource is a named value or state, and both communicating sides must understand its data format and fields. Content-Format identifies the format actually supplied in the message body.
Boiler example: Check the thermostat reading’s format and fields before displaying its temperature.
Also see: resource, Content-Format, Accept
Reset (RST)
A Reset (RST) rejects a message whose exchange context the receiver cannot use.
It reports missing message context rather than application success. A restarted client can reject an update requesting acknowledgement for a registration it no longer remembers.
Boiler example: Send RST when the restarted gateway receives a confirmable thermostat update for a registration it has lost.
Also see: Confirmable (CON), acknowledgement (ACK), observation
resource
A resource is a named value or state.
Its path identifies it, and a method specifies the operation to perform. The supported operations and their results form an agreement for the program making the request.
Boiler example: Treat the thermostat’s temperature reading as a resource the gateway can request.
Also see: Uniform Resource Identifier (URI), method, resource contract
- Where used: CoAP Messages: Codes, Tokens, and Options
- Where used: CoAP Messages: Parsing and Validation
- Where used: CoAP Methods and Multicast
- Where used: CoAP Method/Multicast Contracts
- Where used: CoAP API Design: Resource and Response Contracts
- Where used: CoAP Resource Negotiation Patterns
- Where used: CoAP Security: Implementation and Operations
- Where used: CoAP Lab: Stack and Trace Contracts
- Where used: CoAP Stack and Trace Contracts
resource contract
A resource contract is the path, supported methods, payload rules and response behavior a server implements.
A handler is the function called for an operation on a registered resource. A successful reply needs to be interpreted alongside that implementation and the resulting state.
Boiler example: Document the lamp command’s path, permitted operation, data rules and reply meaning before checking that the lamp obeyed.
Also see: API, handler, resource, response code
Resource discovery
Resource discovery returns advertised resource links instead of making a client guess paths.
A server offering discovery exposes /.well-known/core and chooses which links to advertise. Finding a link still requires separate checks of identity and permission.
Boiler example: Have the gateway discover the thermostat’s temperature resource instead of guessing its path.
Also see: resource, CoRE Link Format, Authorization
response code
The response code reports the result of a request.
Check the code before decoding and displaying the returned data. A successful code still needs the application’s documented meaning and device evidence before it establishes a physical action.
Boiler example: Check the lamp command’s response code and resulting lamp state before recording that it obeyed.
Also see: Code, payload, resource contract
retransmission
A retransmission sends the same message again when acknowledgment is missing.
A matching acknowledgement stops retransmission. Without one, the sender retries with increasing waits until the retry limit is reached.
Boiler example: Retry the lamp’s Confirmable command when its acknowledgement is missing, while checking the resulting state separately.
Also see: Confirmable message, acknowledgement (ACK), Duplicate suppression
safe method
A safe method requests no state change.
GET reads a resource, meaning a named value or state, without requesting a change. Among GET, PUT, POST and DELETE, only GET is safe.
Boiler example: Read the thermostat’s temperature with GET without requesting a change to its settings.
Also see: method, resource, idempotent
security association
A security association includes keys and record sequence state shared with the peer.
The peer is the other end of the protected exchange. After wake, use retained state only when the library supports it and the peer still accepts it; establish fresh state if required information was lost.
Boiler example: Check which security state the battery sensor and gateway still accept before sending after wake.
Also see: DTLS, peer, session resumption
security context
A security context contains keys and associated state used to protect and verify messages.
Object Security for Constrained RESTful Environments (OSCORE) can protect requests between a sensor and service through a forwarding gateway. Those endpoints share the context, while the gateway does not receive their content keys.
Boiler example: Keep the battery sensor’s OSCORE context shared with the service when the gateway should only forward protected content.
Also see: Object Security for Constrained RESTful Environments (OSCORE), Replay state, nonce
separate response
A separate response is sent after the device acknowledges the request without yet returning its result.
An empty acknowledgement confirms receipt without supplying the requested result. The later response has its own Message ID and uses the original Token, the value that matches the response to its request.
Boiler example: Keep the thermostat read pending after its empty acknowledgement until the separate response supplies the result.
Also see: empty ACK, token, Message ID, piggybacked response
server
A server is the device answering a request.
The client is the program making the request. The server’s response code reports the result, and its payload carries the message data.
Boiler example: The thermostat’s room sensor acts as the server when it answers a temperature request.
Also see: client, resource, response code, payload
server endpoint
A server endpoint is its network address and port.
A Token is the request identifier echoed in responses from that address and port. Match the endpoint and Token before deciding whether a later temperature update belongs to the continuing registration.
Boiler example: Check the thermostat’s server endpoint and Token before accepting its update at the gateway.
Also see: endpoint, token, observation
session resumption
Retaining a live DTLS association differs from session resumption, which negotiates renewed use of earlier session information.
Datagram Transport Layer Security (DTLS) protects traffic between security endpoints. Saving a memory buffer alone proves neither complete retained security state nor acceptance by the other endpoint.
Boiler example: Verify supported DTLS recovery and peer acceptance before the battery sensor sends after waking.
Also see: DTLS, security association, Peer authentication
stack
A stack is the software library that handles protocol messages.
A handler is application code that reads or changes a named value or state. The library routes a request to the registered handler, while the application defines what the result means.
Boiler example: Use the thermostat’s stack to route a temperature request to the code that supplies the reading.
Also see: handler, resource contract, CoAP
SZX
SZX encodes the selected block size.
A block carries one numbered part of the transferred data, and the final part can be shorter than the selected size. If the size changes, recalculate the block number from the required byte position.
Boiler example: Check SZX before placing the battery sensor’s next firmware block at its byte position.
token
A token matches a response to its request.
The requester chooses this value and the response echoes it. Check the expected network address and port as well as the token before accepting a reply.
Boiler example: Match the thermostat’s temperature reply to its request using the token and the expected address and port.
Also see: Message ID, endpoint, Observe
- Where used: CoAP Messages: Format Foundations
- Where used: CoAP Messages: Codes, Tokens, and Options
- Where used: CoAP Messages: Parsing and Validation
- Where used: CoAP Wire Format and Option Encoding
- Where used: CoAP Message Exchanges
- Where used: CoAP Exchange Reliability Contracts
- Where used: CoAP Methods and Multicast
- Where used: CoAP Method/Multicast Contracts
- Where used: CoAP Observe: Subscriptions and Updates
- Where used: CoAP Observe: Efficiency and Lifecycle
- Where used: CoAP Observe Freshness Contracts
- Where used: CoAP Advanced Features
- Where used: CoAP Security: Protection and Application Fit
- Where used: CoAP Security: Implementation and Operations
- Where used: CoAP Lab: Stack and Trace Contracts
- Where used: CoAP Lab: Message Construction
- Where used: CoAP Stack and Trace Contracts
token bucket
A token bucket holds permission tokens: each accepted request consumes one, capacity limits how many are held, and tokens refill over time.
Capacity permits a burst of requests, while refill controls the rate accepted over time. A per-device limit reduces one source of overload without guaranteeing that the whole service can cope.
Boiler example: Apply a token bucket to repeated requests from the battery sensor to limit the work accepted from that device.
Also see: Authorization, server, method
token length (TKL)
The token length tells the decoder how many token bytes follow the fixed header.
The fixed header is the first four bytes of this message layout. After consuming the declared Token bytes, which match a response to its request, decoding continues with the numbered message details called options.
Boiler example: Use TKL to find where the Token ends in the gateway’s temperature request to the thermostat.
Also see: token, fixed header, option
trace
A trace is a record of requests and replies.
Keep the destination, operation, path, sent data, returned code and returned data together with the observed state. The reply must be interpreted alongside the implementation and resulting state.
Boiler example: Record the lamp command, its reply and the observed lamp state before claiming the lamp obeyed.
Also see: resource contract, response code, readback
trust anchor
A trust anchor is a key or authority the deployment already trusts.
A certificate binds a public key to an identity through a certificate trust system. Certificate mode needs this already trusted key or authority and a policy for validating certificates.
Boiler example: Configure the trusted key or authority used to validate certificates for the thermostat’s protected connection.
Also see: DTLS, Peer authentication, pre-shared key (PSK)
Uniform Resource Identifier (URI)
A Uniform Resource Identifier (URI) identifies the resource.
A resource is a named value or state, and the URI path selects it. The method says which operation to perform, such as GET to read it.
Boiler example: Use the thermostat’s temperature URI to select the reading the gateway wants to request.
Uri-Path
Uri-Path carries one segment of the request path.
An option is a numbered message field. Repeated Uri-Path options carry separate path segments without slash bytes between their values.
Boiler example: Reconstruct the thermostat’s /sensors/temp path from separate sensors and temp option values.
Also see: option, delta encoding, resource