0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Len=0 |  TKL  |      Code     |    Token (TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1|    Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure 13: CoAP Message Format over WebSockets

As with CoAP over TCP, the message format for CoAP over WebSockets eliminates the Version field defined in CoAP over UDP. If CoAP version negotiation is required in the future, CoAP over WebSockets can address the requirement by the definition of a new subprotocol identifier that is negotiated during the opening handshake.

Requests and response messages can be fragmented as specified in Section 5.4 of [RFC6455], though typically they are sent unfragmented as they tend to be small and fully buffered before transmission. The WebSocket protocol does not provide means for multiplexing. If it is not desirable for a large message to monopolize the connection, requests and responses can be transferred in a block-wise fashion as defined in [RFC7959].

4.3. Message Transmission

As with CoAP over TCP, both endpoints MUST send a Capabilities and Settings message (CSM see Section 5.3) as their first message on the WebSocket connection.

CoAP requests and responses are exchanged asynchronously over the WebSocket connection. A CoAP client can send multiple requests without waiting for a response and the CoAP server can return responses in any order. Responses MUST be returned over the same connection as the originating request. Concurrent requests are differentiated by their Token, which is scoped locally to the connection.

The connection is bi-directional, so requests can be sent both by the entity that established the connection and the remote host.

As with CoAP over TCP, retransmission and deduplication of messages is provided by the WebSocket protocol. CoAP over WebSockets therefore does not make a distinction between Confirmable or Non-Confirmable messages, and does not provide Acknowledgement or Reset messages.

4.4. Connection Health

As with CoAP over TCP, a CoAP client can test the health of the CoAP over WebSocket connection by sending a CoAP Ping Signaling message (Section 5.4). WebSocket Ping and unsolicited Pong frames (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that redundant maintenance traffic is not transmitted.

5. Signaling

Signaling messages are introduced to allow peers to:

• Learn related characteristics, such as maximum message size for the connection
• Shut down the connection in an orderly fashion
• Provide diagnostic information when terminating a connection in response to a serious error condition

Signaling is a third basic kind of message in CoAP, after requests and responses. Signaling messages share a common structure with the existing CoAP messages. There is a code, a token, options, and an optional payload.

(See Section 3 of [RFC7252] for the overall structure of the message format, option format, and option value format.)

5.1. Signaling Codes

A code in the 7.00-7.31 range indicates a Signaling message. Values in this range are assigned by the “CoAP Signaling Codes” sub-registry (see Section 10.1).

For each message, there is a sender and a peer receiving the message.

Payloads in Signaling messages are diagnostic payloads as defined in Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling message option.

5.2. Signaling Option Numbers

Option numbers for Signaling messages are specific to the message code. They do not share the number space with CoAP options for request/response messages or with Signaling messages using other codes.

Option numbers are assigned by the “CoAP Signaling Option Numbers” sub-registry (see Section 10.2).

Signaling options are elective or critical as defined in Section 5.4.1 of [RFC7252]. If a Signaling option is critical and not understood by the receiver, it MUST abort the connection (see Section 5.6). If the option is understood but cannot be processed, the option documents the behavior.

5.3. Capabilities and Settings Messages (CSM)

Capabilities and Settings messages (CSM) are used for two purposes:

• Each capability option advertises one capability of the sender to the recipient.
• Each setting option indicates a setting that will be applied by the sender.

One CSM MUST be sent by both endpoints at the start of the connection. Further CSM MAY be sent at any other time by either endpoint over the lifetime of the connection.

Both capability and setting options are cumulative. A CSM does not invalidate a previously sent capability indication or setting even if it is not repeated. A capability message without any option is a no-operation (and can be used as such). An option that is sent might override a previous value for the same option. The option defines how to handle this case if needed.

Base values are listed below for CSM Options. These are the values for the capability and setting before any Capabilities and Settings messages send a modified value.

These are not default values for the option, as defined in Section 5.4.4 in [RFC7252]. A default value would mean that an empty Capabilities and Settings message would result in the option being set to its default value.

Capabilities and Settings messages are indicated by the 7.01 code (CSM).

5.3.1. Max-Message-Size Capability Option

The sender can use the elective Max-Message-Size Option to indicate the maximum message size in bytes that it can receive.

As per Section 4.6 of [RFC7252], the base value (and the value used when this option is not implemented) is 1152.

The active value of the Max-Message-Size Option is replaced each time the option is sent with a modified value. Its starting value is its base value.

5.3.2. Block-wise Transfer Capability Option

A sender can use the elective Block-wise Transfer Option to indicate that it supports the block-wise transfer protocol [RFC7959].

If the option is not given, the peer has no information about whether block-wise transfers are supported by the sender or not. An implementation that supports block-wise transfers SHOULD indicate the Block-wise Transfer Option. If a Max-Message-Size Option is indicated with a value that is greater than 1152 (in the same or a different CSM message), the Block-wise Transfer Option also indicates support for BERT (see Section 6). Subsequently, if the Max-Message-Size Option is indicated with a value equal to or less than 1152, BERT support is no longer indicated.

5.4. Ping and Pong Messages

In CoAP over reliable transports, Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient. This provides a basic keep-alive function. In contrast, Ping and Pong messages are a bidirectional exchange.

Upon receipt of a Ping message, the receiver MUST return a Pong message with an identical token in response. Unless there is an option with delaying semantics such as the Custody Option, it SHOULD respond as soon as practical. As with all Signaling messages, the recipient of a Ping or Pong message MUST ignore elective options it does not understand.

Ping and Pong messages are indicated by the 7.02 code (Ping) and the 7.03 code (Pong).

5.4.1. Custody Option

When responding to a Ping message, the receiver can include an elective Custody Option in the Pong message. This option indicates that the application has processed all the request/response messages received prior to the Ping message on the current connection. (Note that there is no definition of specific application semantics for “processed”, but there is an expectation that the receiver of a Pong Message with a Custody Option should be able to free buffers based on this indication.)

A sender can also include an elective Custody Option in a Ping message to explicitly request the inclusion of an elective Custody Option in the corresponding Pong message. In that case, the receiver SHOULD delay its Pong message until it finishes processing all the request/response messages received prior to the Ping message on the current connection.

5.5. Release Messages

A Release message indicates that the sender does not want to continue maintaining the connection and opts for an orderly shutdown. The details are in the options. A diagnostic payload (see Section 5.5.2 of [RFC7252]) MAY be included. A peer will normally respond to a Release message by closing the TCP/TLS connection. Messages may be in flight when the sender decides to send a Release message. The general expectation is that these will still be processed.

Release messages are indicated by the 7.04 code (Release).

Release messages can indicate one or more reasons using elective options. The following options are defined:

The elective Alternative-Address Option requests the peer to instead open a connection of the same scheme as the present connection to the alternative transport address given. Its value is in the form “authority” as defined in Section 3.2 of [RFC3986].

The Alternative-Address Option is a repeatable option as defined in Section 5.4.5 of [RFC7252]. When multiple occurrences of the option are included, the peer can choose any of the alternative transport addresses.

The elective Hold-Off Option indicates that the server is requesting that the peer not reconnect to it for the number of seconds given in the value.

5.6. Abort Messages

An Abort message indicates that the sender is unable to continue maintaining the connection and cannot even wait for an orderly release. The sender shuts down the connection immediately after the abort (and may or may not wait for a Release or Abort message or connection shutdown in the inverse direction). A diagnostic payload (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort message. Messages may be in flight when the sender decides to send an Abort message. The general expectation is that these will NOT be processed.

Abort messages are indicated by the 7.05 code (Abort).

Abort messages can indicate one or more reasons using elective options. The following option is defined:

The elective Bad-CSM-Option Option indicates that the sender is unable to process the CSM option identified by its option number, e.g. when it is critical and the option number is unknown by the sender, or when there is parameter problem with the value of an elective option. More detailed information SHOULD be included as a diagnostic payload.

For CoAP over UDP, messages which contain syntax violations are processed as message format errors. As described in Sections 4.2 and 4.3 of [RFC7252], such messages are rejected by sending a matching Reset message and otherwise ignoring the message.

For CoAP over reliable transports, the recipient rejects such messages by sending an Abort message and otherwise ignoring the message. No specific option has been defined for the Abort message in this case, as the details are best left to a diagnostic payload.

5.7. Signaling examples

An encoded example of a Ping message with a non-empty token is shown in Figure 14.

    0                   1                   2
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |      0x01     |      0xe2     |      0x42     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

    Len   =    0 -------> 0x01
    TKL   =    1 ___/
    Code  = 7.02 Ping --> 0xe2
    Token =               0x42

    0                   1                   2
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |      0x01     |      0xe3     |      0x42     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

    Len   =    0 -------> 0x01
    TKL   =    1 ___/
    Code  = 7.03 Pong --> 0xe3
    Token =               0x42

CoAP Client                             CoAP Server
  |                                            |
  | GET, /status                       ------> |
  |                                            |
  | <------   2.05 Content, 2:0/1/BERT(3072)   |
  |                                            |
  | GET, /status, 2:3/0/BERT           ------> |
  |                                            |
  | <------   2.05 Content, 2:3/1/BERT(5120)   |
  |                                            |
  | GET, /status, 2:8/0/BERT          ------>  |
  |                                            |
  | <------   2.05 Content, 2:8/0/BERT(4711)   |

CoAP Client                             CoAP Server
  |                                             |
  | PUT, /options, 1:0/1/BERT(8192)     ------> |
  |                                             |
  | <------   2.31 Continue, 1:0/1/BERT         |
  |                                             |
  | PUT, /options, 1:8/1/BERT(16384)    ------> |
  |                                             |
  | <------   2.31 Continue, 1:8/1/BERT         |
  |                                             |
  | PUT, /options, 1:24/0/BERT(5683)    ------> |
  |                                             |
  | <------   2.04 Changed, 1:24/0/BERT         |
  |                                             |

  coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ]
    path-abempty [ "?" query ]  [ "#" fragment ]

  coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ]
    path-abempty [ "?" query ] [ "#" fragment ]

  coap-ws-URI = "coap+ws:" "//" host [ ":" port ]
    path-abempty [ "?" query ] [ "#" fragment ]

      coap+ws://example.org/sensors/temperature?u=Cel
           \______  ______/\___________  ___________/
                  \/                   \/
                                     Uri-Path: "sensors"
ws://example.org/.well-known/coap    Uri-Path: "temperature"
                                     Uri-Query: "u=Cel"

  coaps-ws-URI = "coaps+ws:" "//" host [ ":" port ]
    path-abempty [ "?" query ] [ "#" fragment ]

      coaps+ws://example.org/sensors/temperature?u=Cel
            \______  ______/\___________  ___________/
                   \/                   \/
                                     Uri-Path: "sensors"
wss://example.org/.well-known/coap   Uri-Path: "temperature"
                                     Uri-Query: "u=Cel"

3.  If |url| does not have a <scheme> component whose value, when
    converted to ASCII lowercase, is "coap" or "coaps", then fail
    this algorithm.

3.  If |url| does not have a <scheme> component whose value, when
    converted to ASCII lowercase, is "coap+tcp", "coaps+tcp",
    "coap+ws", or "coaps+ws", then fail this algorithm.

7.  If |port| does not equal the request's destination UDP port,
    include a Uri-Port Option and let that option's value be |port|.

7.  If |port| does not equal the request's destination TCP port,
    include a Uri-Port Option and let that option's value be |port|.

1.  If the request is secured using DTLS, let |url| be the string
    "coaps://". Otherwise, let |url| be the string "coap://".

1.  For CoAP over TCP, if the request is secured using TLS, let |url|
    be the string "coaps+tcp://". Otherwise, let |url| be the string
    "coap+tcp://". For CoAP over WebSockets, if the request is
    secured using TLS, let |url| be the string "coaps+ws://".
    Otherwise, let |url| be the string "coap+ws://".

4.  If the request includes a Uri-Port Option, let |port| be that
    option's value.  Otherwise, let |port| be the request's
    destination UDP port.

4.  If the request includes a Uri-Port Option, let |port| be that
    option's value.  Otherwise, let |port| be the request's
    destination TCP port.

   CoAP        CoAP
  Client      Server
(WebSocket  (WebSocket
  Client)     Server)

     |          |
     |          |
     +=========>|  GET /.well-known/coap HTTP/1.1
     |          |  Host: example.org
     |          |  Upgrade: websocket
     |          |  Connection: Upgrade
     |          |  Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
     |          |  Sec-WebSocket-Protocol: coap
     |          |  Sec-WebSocket-Version: 13
     |          |
     |<=========+  HTTP/1.1 101 Switching Protocols
     |          |  Upgrade: websocket
     |          |  Connection: Upgrade
     |          |  Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
     |          |  Sec-WebSocket-Protocol: coap
     |          |
     |          |
     +--------->|  Binary frame (opcode=%x2, FIN=1, MASK=1)
     |          |    +-------------------------+
     |          |    | GET                     |
     |          |    | Token: 0x53             |
     |          |    | Uri-Path: "sensors"     |
     |          |    | Uri-Path: "temperature" |
     |          |    | Uri-Query: "u=Cel"      |
     |          |    +-------------------------+
     |          |
     |<---------+  Binary frame (opcode=%x2, FIN=1, MASK=0)
     |          |    +-------------------------+
     |          |    | 2.05 Content            |
     |          |    | Token: 0x53             |
     |          |    | Payload: "22.3 Cel"     |
     |          |    +-------------------------+
     :          :
     :          :
     |          |
     +--------->|  Close frame (opcode=%x8, FIN=1, MASK=1)
     |          |
     |<---------+  Close frame (opcode=%x8, FIN=1, MASK=0)
     |          |

   CoAP        CoAP       CoAP
  Client      Proxy      Server
(WebSocket  (WebSocket    (UDP
  Client)     Server)   Endpoint)

     |          |          |
     +--------->|          |  Binary frame (opcode=%x2, FIN=1, MASK=1)
     |          |          |    +------------------------------------+
     |          |          |    | GET                                |
     |          |          |    | Token: 0x7d                        |
     |          |          |    | Proxy-Uri: "coap://[2001:db8::1]/" |
     |          |          |    +------------------------------------+
     |          |          |
     |          +--------->|  CoAP message (Ver=1, T=Con, MID=0x8f54)
     |          |          |    +------------------------------------+
     |          |          |    | GET                                |
     |          |          |    | Token: 0x0a15                      |
     |          |          |    +------------------------------------+
     |          |          |
     |          |<---------+  CoAP message (Ver=1, T=Ack, MID=0x8f54)
     |          |          |    +------------------------------------+
     |          |          |    | 2.05 Content                       |
     |          |          |    | Token: 0x0a15                      |
     |          |          |    | Payload: "ready"                   |
     |          |          |    +------------------------------------+
     |          |          |
     |<---------+          |  Binary frame (opcode=%x2, FIN=1, MASK=0)
     |          |          |    +------------------------------------+
     |          |          |    | 2.05 Content                       |
     |          |          |    | Token: 0x7d                        |
     |          |          |    | Payload: "ready"                   |
     |          |          |    +------------------------------------+
     |          |          |

Matthias Kovatsch
Siemens AG
Otto-Hahn-Ring 6
Munich D-81739

Phone: +49-173-5288856
EMail: matthias.kovatsch@siemens.com


Teemu Savolainen
Nokia Technologies
Hatanpaan valtatie 30
Tampere FI-33100
Finland

Email: teemu.savolainen@nokia.com


Valik Solorzano Barboza
Zebra Technologies
820 W. Jackson Blvd. Suite 700
Chicago 60607
United States of America

Phone: +1-847-634-6700
Email: vsolorzanobarboza@zebra.com