coapy.message

Something

copyright:Copyright 2013, Peter A. Bigot license:Apache-2.0

Messages

The following message types are available:

Request	Subclass for messages that are requests.
SuccessResponse	Subclass for messages that are responses that indicate the request was successfully received, understood, and accepted.
ClientErrorResponse	Subclass for messages that are responses in cases where the server detects an error in the client’s request.
ServerErrorResponse	Subclass for messages that are responses that indicate the server is incapable of performing the request.

class coapy.message.Message(confirmable=False, acknowledgement=False, reset=False, code=None, messageID=None, token=None, options=None, payload=None)

A CoAP message, per CoAP Section 3.

A message may be created as confirmable, an acknowledgement, or a reset message. If none of these is specified, it is created as a non-confirmable message.

code, messageID, token, options, and payload all initialize the corresponding attributes of this class and if provided must be acceptable values for those attributes.

Note

The default values for code, messageID, and token are not valid for code, messageID, and token respectively. Valid values must be assigned before the message is used.

CodeClass = None

Identifier for message class.

In subclasses this is a read-only attribute giving the numeric value of the class component of code values for classes. This serves as a key to identify the appropriate constructor when creating messages from packed format.

Empty = (0, 0)

Code for a message that is neither a request nor a response. This is used for message-layer non-piggybacked ACK and for RST.

classmethod RegisterClassCode(clazz, constructor=None)

Register a fallback-constructor for messages in a code class.

This is used when no more specific information can be resolved by using the details field of the message code.

classmethod RegisterCode(code, name, constructor=None)

Register some information about messages with a particular code.

This allows extensions to add new codes as the IANA registries are updated. It also allows the Python version of decoded messages to be created using the most appropriate subclass of Message.

code must be a valid code expressed in tuple form. name is the standardized text name or description from the corresponding IANA registry. constructor is the callable that takes the same arguments as Message and creates a new instance of the class best suited for messages with code code. The constructor defaults to cls if not provided.

This method should be invoked through the subclass that is responsible for code, e.g. Request for Request.GET. See examples of use in the coapy.message source code.

Type_ACK = 2

Type for a acknowledgement (ACK) message.

Type_CON = 0

Type for a confirmable (CON) message.

Type_NON = 1

Type for a non-confirmable (NON) message.

Type_RST = 3

Type for a reset (RST) message.

Ver = 1

Version of the CoAP protocol.

_get_code()

The message code, expressed as a tuple (class, detail) where class is an integer value from 0 through 7 and detail is an integer value from 0 through 31.

A code of None is allowed only when a raw Message is created, and a valid code must be assigned before the message may be transmitted.

For convenience, the code may also be set from its packed format defined by (class << 5) | detail. Decimal code representation such as 4.03 is not supported.

_get_destination_endpoint()

Return the destination endpoint of the message.

This is the coapy.endpoint.Endpoint instance to which the message was (or will be) sent, i.e. the one on which it was (or should be) received. It starts as None, and can be assigned a value once after which it is immutable. Generally the infrastructure should be responsible for assigning a destination endpoint to a message.

See also source_endpoint.

_get_messageID()

An integer between 0 and 65535, inclusive, uniquely identifying a confirmable or non-confirmable message among those recently transmitted by its sender. This value is used to correlate confirmable and non-confirmable messages with acknowledgement and reset messages. It is not used for request/response correlation.

_get_options()

The list of options associated with the message.

Absence of options is represented by an empty list. Elements of the list must be coapy.option.UrOption (subclass) instances. The list object is owned by the message instance. Assignment to it will replace its contents. The contents will be rearranged in a stable sort by option number as needed by operations performed on the message.

_get_packed_code()

Return code in its packed form as an unsigned 8-bit integer.

This will raise ValueError if code has not been assigned.

_get_payload()

The payload or content of the message. This may be None if no payload exists; otherwise it must be a non-empty bytes instance. As a convenience, an empty bytes string is equivalent to setting the payload to None.

The representation of the payload should be conveyed by a ContentFormat option.

_get_source_endpoint()

Return the source endpoint of the message.

This is the coapy.endpoint.Endpoint instance that sent (or will send) the message. It starts as None, and can be assigned a value once after which it is immutable. Generally the infrastructure should be responsible for assigning a source endpoint to a message.

See also destination_endpoint.

_get_token()

The token associated with the message.

Tokens are used to match requests with responses. The token must be a bytes instance with length between 0 and 8 octets, inclusive.

_get_type()

The type of the message as Type_CON, Type_NON, Type_ACK, or Type_RST. This is a read-only attribute.

_get_type_name()

The type of the message as a three-letter descriptive name (CON, NON, ACK, RST). This is a read-only attribute.

_sort_options()

Sort the options list and return a reference to it.

code

The message code, expressed as a tuple (class, detail) where class is an integer value from 0 through 7 and detail is an integer value from 0 through 31.

A code of None is allowed only when a raw Message is created, and a valid code must be assigned before the message may be transmitted.

For convenience, the code may also be set from its packed format defined by (class << 5) | detail. Decimal code representation such as 4.03 is not supported.

static code_as_integer(code)

Validate code and return it as an integer.

The packed encoding of (class, detail) has the 3-bit code class combined with the 5-bit code detail, as: (class << 5) | detail.

static code_as_tuple(code)

Validate code and return it as a (class, detail) tuple.

create_reply(reset=False)

Create a message-layer reply to this message.

This method creates an empty message of either type ACK (by default) or RST (if reset is True) with the same message ID as this message. The source_endpoint and destination_endpoint of the returned message are set appropriately.

MessageReplyError is raised if this message is non-confirmable and reset is false, or if self is an ACK or RST message.

destination_endpoint

Return the destination endpoint of the message.

This is the coapy.endpoint.Endpoint instance to which the message was (or will be) sent, i.e. the one on which it was (or should be) received. It starts as None, and can be assigned a value once after which it is immutable. Generally the infrastructure should be responsible for assigning a destination endpoint to a message.

See also source_endpoint.

classmethod from_packed(packed_message)

Create a Message (or subclass) instance from the packed representation of a message, per CoAP Section 3.

This will return None if the first four octets cannot be successfully decoded; such messages should be silently ignored.

It will raise a MessageFormatError when type, code and messageID information can be extracted but the message as a whole is malformatted. CoAP Section 4 specifies the receiver MUST (CON) or may (NON) or MUST NOT (ACK, RST) reply with a Reset message, and otherwise the message is ignored (from a protocol perspective; the receiver may use the failure as a cue to perform some other action; see CoAP Section 5.7.1 for example).

Otherwise it will return an instance of Message or a refined subclass based on the code within the packed representation.

is_acknowledgement()

True if this message is an acknowledgement that a particular confirmable message with messageID was received.

is_confirmable()

True if this message is confirmable, i.e. will be retransmitted for reliability, and an acknowledgement or reset is expected.

is_non_confirmable()

True if this message is non-confirmable, meaning the CoAP layer will not retransmit it, and an acknowledgement is not expected.

is_reset()

True if this message is an indication that a particular message with messageID arrived but that the receiver could not process it.

maxAge()

Return the Max-Age value for the message.

This is the value of the coapy.option.MaxAge() option if present, or its default value of 60 (seconds) if the option is missing. The value None is returned if the message is not one in which coapy.option.MaxAge() may appear (i.e., not a Response message).

messageID

An integer between 0 and 65535, inclusive, uniquely identifying a confirmable or non-confirmable message among those recently transmitted by its sender. This value is used to correlate confirmable and non-confirmable messages with acknowledgement and reset messages. It is not used for request/response correlation.

messageType

The type of the message as Type_CON, Type_NON, Type_ACK, or Type_RST. This is a read-only attribute.

messageTypeName

The type of the message as a three-letter descriptive name (CON, NON, ACK, RST). This is a read-only attribute.

options

The list of options associated with the message.

Absence of options is represented by an empty list. Elements of the list must be coapy.option.UrOption (subclass) instances. The list object is owned by the message instance. Assignment to it will replace its contents. The contents will be rearranged in a stable sort by option number as needed by operations performed on the message.

packed_code

Return code in its packed form as an unsigned 8-bit integer.

This will raise ValueError if code has not been assigned.

payload

The payload or content of the message. This may be None if no payload exists; otherwise it must be a non-empty bytes instance. As a convenience, an empty bytes string is equivalent to setting the payload to None.

The representation of the payload should be conveyed by a ContentFormat option.

source_defines_messageID()

True if this message is CON or NON.

CON and NON messages are responsible for selecting a messageID at the source_endpoint.

ACK and RST messages are message-level responses to a messageID that was selected by their destination_endpoint.

source_endpoint

Return the source endpoint of the message.

This is the coapy.endpoint.Endpoint instance that sent (or will send) the message. It starts as None, and can be assigned a value once after which it is immutable. Generally the infrastructure should be responsible for assigning a source endpoint to a message.

See also destination_endpoint.

static source_originates_type(mtype)

True if mtype is CON or NON.

CoAP defines a message layer where messages from a source to a destination may elicit message-layer replies from the destination to the source. This is completely distinct from the transaction layer requests that elicit transaction-layer responses.

CON and NON type messages are message-layer initial messages. These messages require cache entries for the source endpoint at the receiving node. This function returns True for these messages.

ACK and RST messages are message-layer responses. These messages are processed relative to the destination endpoint at the receiving node. This function returns False for these messages.

to_packed()

Generate the packed representation of the message, per CoAP Section 3.

The result is a bytes instance.

token

The token associated with the message.

Tokens are used to match requests with responses. The token must be a bytes instance with length between 0 and 8 octets, inclusive.

validate()

Validate a message against generic CoAP requirements.

A MessageValidationError exception is raised if the validation fails.

Diagnostics will be emitted for any coapy.option.UnrecognizedOption remaining in the message after validation.

class coapy.message.Request(confirmable=False, acknowledgement=False, reset=False, code=None, messageID=None, token=None, options=None, payload=None)

Bases: coapy.message.Message

Subclass for messages that are requests.

The following table shows the pre-defined method code values (class, detail) as specified in CoAP Section 12.1.1:

Code	Name	Documentation
(0, 1)	GET	CoAP Section 5.8.1
(0, 2)	POST	CoAP Section 5.8.2
(0, 3)	PUT	CoAP Section 5.8.3
(0, 4)	DELETE	CoAP Section 5.8.4

CodeClass = 0

The Message.code class component for Request messages.

DELETE = (0, 4)

Delete the resource identified by the request URI. See CoAP Section 5.8.4.

GET = (0, 1)

Retrieve a representation for the requested resource. See CoAP Section 5.8.1.

POST = (0, 2)

Process the representation enclosed in the requested resource. See CoAP Section 5.8.2.

PUT = (0, 3)

Update or create the resource using the enclosed representation. See CoAP Section 5.8.3.

create_response(rclass, piggy_backed=True, confirmable=False, **kw)

Create a response to this request.

rclass is a subclass of Response indicating the type of the response. (For non-response replies, see Message.create_reply().) If piggy_backed is True the response message will be an ACK to this message; otherwise it will be either a CON or NON message, depending on confirmable, and must be assigned its own message ID. In either case, the token value will be copied from this message. All other keyword parameters are passed to the rclass constructor. The source_endpoint and destination_endpoint attributes will be set from this message.

class coapy.message.Response(confirmable=False, acknowledgement=False, reset=False, code=None, messageID=None, token=None, options=None, payload=None)

Bases: coapy.message.Message

Subclass for messages that are responses.

Some of the semantics of CoAP depends on distinguishing requests from responses; use this as an intermediary class for common handling of SuccessResponse, ClientErrorResponse, and ServerErrorResponse.

class coapy.message.SuccessResponse(confirmable=False, acknowledgement=False, reset=False, code=None, messageID=None, token=None, options=None, payload=None)

Bases: coapy.message.Response

Subclass for messages that are responses that indicate the request was successfully received, understood, and accepted.

The following table shows the pre-defined success response code values (class, detail) as specified in CoAP Section 12.1.2:

Code	Name	Documentation
(2, 1)	Created	CoAP Section 5.9.1.1
(2, 2)	Deleted	CoAP Section 5.9.1.2
(2, 3)	Valid	CoAP Section 5.9.1.3
(2, 4)	Changed	CoAP Section 5.9.1.4
(2, 5)	Content	CoAP Section 5.9.1.4

Changed = (2, 4)

See CoAP Section 5.9.1.4.

CodeClass = 2

The Message.code class component for SuccessResponse messages.

Content = (2, 5)

See CoAP Section 5.9.1.5.

Created = (2, 1)

See CoAP Section 5.9.1.1.

Deleted = (2, 2)

See CoAP Section 5.9.1.2.

Valid = (2, 3)

See CoAP Section 5.9.1.3.

class coapy.message.ClientErrorResponse(confirmable=False, acknowledgement=False, reset=False, code=None, messageID=None, token=None, options=None, payload=None)

Bases: coapy.message.Response

Subclass for messages that are responses in cases where the server detects an error in the client’s request.

The following table shows the pre-defined client error response code values (class, detail) as specified in CoAP Section 12.1.2:

Code	Name	Documentation
(4, 0)	BadRequest	CoAP Section 5.9.2.1
(4, 1)	Unauthorized	CoAP Section 5.9.2.2
(4, 2)	BadOption	CoAP Section 5.9.2.3
(4, 3)	Forbidden	CoAP Section 5.9.2.4
(4, 4)	NotFound	CoAP Section 5.9.2.5
(4, 5)	MethodNotAllowed	CoAP Section 5.9.2.6
(4, 6)	NotAcceptable	CoAP Section 5.9.2.7
(4, 12)	PreconditionFailed	CoAP Section 5.9.2.8
(4, 13)	RequestEntityTooLarge	CoAP Section 5.9.2.9
(4, 15)	UnsupportedContentFormat	CoAP Section 5.9.2.10

BadOption = (4, 2)

See CoAP Section 5.9.2.3

BadRequest = (4, 0)

See CoAP Section 5.9.2.1

CodeClass = 4

The Message.code class component for ClientErrorResponse messages.

Forbidden = (4, 3)

See CoAP Section 5.9.2.4

MethodNotAllowed = (4, 5)

See CoAP Section 5.9.2.6

NotAcceptable = (4, 6)

See CoAP Section 5.9.2.7

NotFound = (4, 4)

See CoAP Section 5.9.2.5

PreconditionFailed = (4, 12)

See CoAP Section 5.9.2.8

RequestEntityTooLarge = (4, 13)

See CoAP Section 5.9.2.9

Unauthorized = (4, 1)

See CoAP Section 5.9.2.2

UnsupportedContentFormat = (4, 15)

See CoAP Section 5.9.2.10

class coapy.message.ServerErrorResponse(confirmable=False, acknowledgement=False, reset=False, code=None, messageID=None, token=None, options=None, payload=None)

Bases: coapy.message.Response

Subclass for messages that are responses that indicate the server is incapable of performing the request.

The following table shows the pre-defined server error response code values (class, detail) as specified in CoAP Section 12.1.2:

Code	Name	Documentation
(5, 0)	InternalServerError	CoAP Section 5.9.3.1
(5, 1)	NotImplemented	CoAP Section 5.9.3.2
(5, 2)	BadGateway	CoAP Section 5.9.3.3
(5, 3)	ServiceUnavailable	CoAP Section 5.9.3.4
(5, 4)	GatewayTimeout	CoAP Section 5.9.3.5
(5, 5)	ProxyingNotSupported	CoAP Section 5.9.3.6

BadGateway = (5, 2)

See CoAP Section 5.9.3.3

CodeClass = 5

The Message.code class component for ServerErrorResponse messages.

GatewayTimeout = (5, 4)

See CoAP Section 5.9.3.5

InternalServerError = (5, 0)

See CoAP Section 5.9.3.1

NotImplemented = (5, 1)

See CoAP Section 5.9.3.2

ProxyingNotSupported = (5, 5)

See CoAP Section 5.9.3.6

ServiceUnavailable = (5, 3)

See CoAP Section 5.9.3.4

Utility Classes

class coapy.message.TransmissionParameters

The transmission parameters that support message transmission behavior including congestion control in CoAP.

Some of these parameters are primitive, and some are derived. Consult CoAP Section 4.8.1 for information related to changing these parameters. After changing the primitive parameters in an instance, invoke recalculate_derived() to update the derived parameters.

Parameter	Units	Documentation	Class
ACK_TIMEOUT	seconds	CoAP Section 4.8	Primitive
ACK_RANDOM_FACTOR	seconds	CoAP Section 4.8	Primitive
MAX_RETRANSMIT	transmissions	CoAP Section 4.8	Primitive
NSTART	messages	CoAP Section 4.7	Primitive
DEFAULT_LEISURE	seconds	CoAP Section 8.2	Primitive
PROBING_RATE	bytes/second	CoAP Section 4.7	Primitive
MAX_LATENCY	seconds	CoAP Section 4.8.2	Primitive
PROCESSING_DELAY	seconds	CoAP Section 4.8.2	Primitive
MAX_TRANSMIT_SPAN	seconds	CoAP Section 4.8.2	Derived
MAX_TRANSMIT_WAIT	seconds	CoAP Section 4.8.2	Derived
MAX_RTT	seconds	CoAP Section 4.8.2	Derived
EXCHANGE_LIFETIME	seconds	CoAP Section 4.8.2	Derived
NON_LIFETIME	seconds	CoAP Section 4.8.2	Derived

ACK_RANDOM_FACTOR = 1.5

A randomization factor to avoid synchronization, in seconds.

ACK_TIMEOUT = 2

The initial timeout waiting for an acknowledgement, in seconds.

DEFAULT_LEISURE = 5

A duration, in seconds, that a server may delay before responding to a multicast message.

EXCHANGE_LIFETIME = 247

Time, in seconds, from first transmission of a confirmable message to when an acknowledgement is no longer expected.

MAX_LATENCY = 100

The maximum time, in seconds, expected from the start of datagram transmission to completion of its reception. This includes endpoint transport-, link-, and physical-layer processing, propagation delay through the communications medium, and intermediate routing overhead.

MAX_RETRANSMIT = 4

The maximum number of retransmissions of a confirmable message. A value of 4 produces a maximum of 5 transmissions when the first transmission is included.

MAX_RTT = 202

Maximum round-trip-time, in seconds, considering MAX_LATENCY and PROCESSING_DELAY.

MAX_TRANSMIT_SPAN = 45

Maximum time, in seconds, from first transmission of a confirmable message to its last retransmission..

MAX_TRANSMIT_WAIT = 93

Maximum time, in seconds, from first transmission of a confirmable message to when the sender may give up on receiving acknowledgement or reset.

NON_LIFETIME = 145

Time, in seconds, from transmission of a non-confirmable message to when its Message-ID may be safely re-used.

NSTART = 1

The maximum number of messages permitted to be outstanding for an endpoint.

PROBING_RATE = 1

The target maximum average data rate, in bytes per second, for transmissions to an endpoint that does not respond.

PROCESSING_DELAY = 2

The maximum time, in seconds, that node requires to generate an acknowledgement to a confirmable message.

make_bebo(initial_timeout=None, max_retransmissions=None)

Create a RetransmissionState for binary exponential back off (BEBO) transmission.

recalculate_derived()

Calculate values for parameters that may be derived.

This uses the calculations in CoAP Section 4.8.2 to calculate MAX_TRANSMIT_SPAN, MAX_TRANSMIT_WAIT, MAX_RTT, EXCHANGE_LIFETIME, and NON_LIFETIME from other parameters in the instance.

class coapy.message.RetransmissionState(initial_timeout=None, max_retransmissions=None, transmission_parameters=None)

An iterable that provides the time to the next retransmission.

initial_timeout is the time, in seconds, to the first retransmission; a default is calculated from transmission_parameters if provided.

max_retransmissions is the maximum number of re-transmissions; a default is obtained from transmission_parameters if provided.

Thus:

list(RetransmissionState(3,4))

will produce:

[3, 6, 12, 24]

_get_remaining()

The number of retransmissions remaining in the iterator.

retransmissions_remaining

The number of retransmissions remaining in the iterator.

Message-Related Exceptions

exception coapy.message.MessageError

Bases: coapy.CoAPyException

exception coapy.message.MessageFormatError

Bases: coapy.message.MessageError

Exception raised by Message.from_packed() when the message cannot be decoded. args will be (diagnostic, dkw) where diagnostic is a human-readable description of the failure cause matching one of the codes in this class, and dkw is a dictionary with entries for type, code and messageID.

Justification for the diagnosis can be found in CoAP Section 3.

EMPTY_MESSAGE_NOT_EMPTY = u'excess content in Empty message'

diagnostic value when a message with code Empty has bytes after the Message ID field.

INVALID_OPTION = u'option decode error'

diagnostic value when an Option Delta is 15 in a value that is not a Payload Marker, or an Option Delta is 15 in a value that is not a Payload Marker.

TOKEN_TOO_LONG = u'token too long'

diagnostic value when the TKL field of the message is greater than 8.

UNRECOGNIZED_CODE_CLASS = u'unrecognized code class'

diagnostic when the code has no generic handler (e.g. the message code class is 1, 6, and 7 which are currently reserved).

Technically this is not a message format error, but CoAP requires that it be treated the same way wherever the possibility is explicitly recognized (CoAP Section 4.2 and CoAP Section 4.3).

ZERO_LENGTH_PAYLOAD = u'zero-length payload'

diagnostic value when a Payload Marker is present but not followed by data.

exception coapy.message.MessageValidationError

Bases: coapy.message.MessageError

Exception raised by Message.validate(). args will be (diagnostic, message) where diagnostic is a human-readable description of the failure cause matching one of the codes in this class, and message is the invalid message.

CODE_INSTANCE_CONFLICT = u'code inconsistent with message class'

diagnostic value when the class in Message.code is not compatible with the Python class of the message instance.

CODE_TYPE_CONFLICT = u'code and messageType conflict'

diagnostic value when Message.code and Message.messageType are not consistent:

• CON and NON allowed only in Request and Response messages.
• ACK allowed only for Empty and Response messages.
• RST allowed only for Empty messages.

CODE_UNDEFINED = u'missing code'

diagnostic value when caller failed to assign a value to Message.code

EMPTY_MESSAGE_NOT_EMPTY = u'excess content in Empty message'

diagnostic value when a message with code Empty has a non-empty Message.token, Message.options, or Message.payload attribute.

PROXY_URI_CONFLICT = u'Proxy-Uri mixed with Uri-*'

diagnostic value when message has both coapy.option.ProxyUri and at least one of coapy.option.UriHost, coapy.option.UriPort, coapy.option.UriPath, or coapy.option.UriQuery.

UNRECOGNIZED_CRITICAL_OPTION = u'Unrecognized critical option'

diagnostic value when message has an option that is critical but was not recognized. For this exception the Exception.args are (diagnostic, message, option) where option is the unrecognized critical option.

exception coapy.message.MessageReplyError

Bases: coapy.message.MessageError

Exception raised when Message.create_reply() is invoked improperly.

The args are (diagnostic, msg) where diagnostic is one of the string values in this class, and msg is the message for which a reply could not be created.

ACK_FOR_NON = u'ACK of NON-confirmable message'

Per CoAP Section 4.3, a non-confirmable message MUST NOT be acknowledged.

INVALID_TYPE = u'Reply to unrepliable message'

Attempt to create a reply to an ACK or RST message.