Supported Header Options

Name Default
Content-type text/plain
Max-age 60 seconds
Uri-Scheme coap

Classes and functions related to CoAP header options.

class coapy.options.Block(block_number=0, more=False, size_exponent=7)

Bases: coapy.options._Base

Support block-wise transfers of large resources.


This is an experimental option. See draft-bormann-core-misc

  • block_number – The number of the block
  • more – A bool used in response messages to indicate the resource has additional blocks with higher block numbers.
  • size_exponent – The base-2 exponent for the block size. The minimum exponent supported is 4 (a 16-octet block); the maximum is 11 (a 2048-octet block).
The maximum supported size for resource blocks is 2^11 or 2048 octets.
The minimum supported size for resource blocks is 2^4 or 16 octets.
The block number, starting at zero for the first block.
True iff there are subsequent blocks in the resource.

The base-2 exponent defining the size of each (non-final) block.


class coapy.options.ContentType(value=None)

Bases: coapy.options._Base

The Internet media type describing the message body.

The default content type is text/plain.

Access the value using its IANA-assigned media type encoding scheme, e.g. application/xml.

Note:Only media types that have been assigned CoAP integral values are allowed.
class coapy.options.Etag(value=None)

Bases: coapy.options._StringValue_mixin, coapy.options._Base

An opaque sequence of bytes specifying the version of resource representation.

An ETag value cannot exceed four octets in length.
An ETag value must have at least one octet.
class coapy.options.Location(value=None)

Bases: coapy.options._UriPath_mixin, coapy.options._Base

The location of a resource.

Normally used in in a response to indicate the location of a newly created resource.

class coapy.options.MaxAge(value=None)

Bases: coapy.options._IntegerValue_mixin, coapy.options._Base

The maximum age of a resource for use in cache control, in seconds.

A map from integral option types to the Python class that implements the option.
class coapy.options.UriAuthority(value=None)

Bases: coapy.options._StringValue_mixin, coapy.options._Base

The authority (host+port) part of the URI.

By default, the URI authority is empty.
class coapy.options.UriPath(value=None)

Bases: coapy.options._UriPath_mixin, coapy.options._Base

The absolute path part of the URI.

Since all CoAP URI paths are absolute, the leading slash is elided from the option value.

By default, the URI path is /, represented as an empty string.
class coapy.options.UriScheme(value=None)

Bases: coapy.options._StringValue_mixin, coapy.options._Base

The schema part of the URI.

The default URI scheme is coap.
coapy.options.decode(num_options, payload)

Decode a set of CoAP options and extract a message body.

The specified number of options are pulled from the initial octets of the payload, and converted into instances of the corresponding option class. The return value is a pair (options, body) where options is a list of all recognized options in their order of appearance and body is the remainder of the payload after options have been stripped.

  • num_options – The number of options to be extracted.
  • payload – The packed options followed by an optional message body.

(options, body)

Return type:

(list, str)


Exception if an unrecognized critical option is encountered

coapy.options.encode(options, ignore_if_default=True)

Encode a set of CoAP options for transmission.

The options are sorted as required by CoAP. The return value is a pair (num_options, packed) where num_options is the number of options that were encoded, and packed is the octet sequence encoding those options.

  • options – An iterable of option instances
  • ignore_if_default – If True, any option instance that has the default value for the option is excluded from the packed representation.

(num_options, packed_options)

Return type:

(int, str)


Exception if a packed option exceeds the representable option length

Parameter:value – Any non-negative integral value
Returns:Determine the number of octets required to express value as by pack_vlint().
Return type:int
Parameter:type_val – the integral type value for an option
Returns:True iff an option of Type type_val is elective (can be skipped if unrecognized).

Pack an integer into a string.

CoAP variable-length integers are packed into a sequence of octets in network byte order. Leading octets that would have a zero value are elided.

Parameter:value – Any non-negative integral value
Return type:str

Extract an integer from a string as created by pack_vlint().

Parameter:packed – A string of octets containing a packed integer.
Return type:int

Option Internals

Base Class for Options

class coapy.options._Base(value=None)

Base class for all CoAPy option classes.


The default value of the option. None if the option has no default.

Note:This value is overridden in each class that implements a CoAP option with a default value.

The standardized name of the option.

Note:This value is overridden in each class that implements a CoAP option.

The type code for the option.

Options with an even type code are elective, while those with an odd type code are critical.

Note:This value is overridden in each class that implements a CoAP option.
classmethod is_critical()
Return True if this option must be understood.

Return True iff the current value of the option is equal to the default value of the option.

This is used by encode to avoid unnececessarily packing options.


The length, in octets, of the packed option.

Note:This is a read-only property.

The sequence of octets representing the option value in packed form (i.e., as it appears within an option header).

The sequence does not include the option delta or length, only the value.

Note:This is a read-only property.
classmethod unpack(packed)

Create an instance of this option from a packed representation.

Parameter:packed – A sequence of octets representing the option value, exclusive of the option type and length.
Return type:An instance of the leaf class.

The option value.

Python objects and type instances assigned as option values are validated within the limitations of the CoAP option’s packed representation. For example, assigning to an instance of UriPath a value that exceeds the length limitation of 270 will result in a ValueError.

In cases where the option value is expected to have an IANA-assigned significance but the specific assigned value is unrecognized, the value assignment is permitted if doing so does not violate the requirements of the packed option representation. For example, assigning a value of 15 to an instance of ContentType would be allowed, though the value 15 is not (currently) associated with a specific media type.

Mix-in Classes

The following classes are mixed-in to CoAP option classes to provide common support for representing and validating the option values.

class coapy.options._StringValue_mixin

Mix-in to support options with octet-sequence values.

The maximum length, in octets, for the option value.
The minimum length, in octets, for the option value.
Overrides the base value property. The assigned value must be a string within the limits of MIN_VALUE_LENGTH and MAX_VALUE_LENGTH for the option class.
class coapy.options._UriPath_mixin

Mix-in to support options with string values that represent URIs.

Overrides the string value property. In addition to length limitations, the assigned value must not start with a forward-slash.
class coapy.options._IntegerValue_mixin

Mix-in to support options with integral values.

The maximum allowable value for the option.
The minimum allowable value for the option.
Overrides the base value property. The assigned value must be an integral value within the limits of MIN_VALUE and MAX_VALUE for the option class.

Table Of Contents

Previous topic


Next topic

Link Format

This Page