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 |  TKL  |      Code     |    Token (TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1|    Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Figure 14: CoAP Message Format over WebSockets

The CoAP over TCP message format 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 [I-D.ietf-core-block].

Empty messages (Code 0.00) MUST be ignored by the recipient (see also Section 4.4).

3.3. Message Transmission

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.

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.

Since the WebSocket protocol provides ordered delivery of messages, the mechanism for reordering detection when observing resources [RFC7641] is not needed. The value of the Observe Option in notifications MAY be empty on transmission and MUST be ignored on reception.

3.4. Connection Health

When a client does not receive any response for some time after sending a CoAP request (or, similarly, when a client observes a resource and it does not receive any notification for some time), the connection between the WebSocket client and the WebSocket server may be lost or temporarily disrupted without the client being aware of it.

To check the health of the WebSocket connection (and thereby of all active requests, if any), the client can send a Ping frame or an unsolicited Pong frame as specified in Section 5.5 of [RFC6455]. There is no way to retransmit a request without creating a new one. Re-registering interest in a resource is permitted, but entirely unnecessary.

3.5. Closing the Connection

The WebSocket connection is closed as specified in Section 7 of [RFC6455].

All requests for which the CoAP client has not received a response yet are cancelled when the connection is closed. If the client observes one or more resources over the WebSocket connection, then the CoAP server (or intermediary in the role of the CoAP server) MUST remove all entries associated with the client from the lists of observers when the connection is closed.

4. Signaling

Signaling messages are introduced to allow peers to:

• Share characteristics such as maximum message size for the connection
• Shutdown the connection in an ordered fashion
• Terminate the 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, as adapted to the specific transport.)

4.1. Signaling Codes

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

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

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

4.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 8.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 4.6). If the option is understood but cannot be processed, the option documents the behavior.

4.3. Capability and Settings Messages (CSM)

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

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

Most CSM Options are useful mainly as initial messages in the connection.

Both capability and settings options are cumulative. A Capability and Settings message 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 Capability and Settings messages sends 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 Capability and Settings message would result in the option being set to its default value.

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

4.3.1. Server-Name Setting Option

A client can use the Server-Name critical option to indicate the default value for the Uri-Host Options in the messages that it sends to the server. It has the same restrictions as the Uri-Host Option (Section 5.10 of [RFC7252].

For TLS, the initial value for the Server-Name Option is given by the SNI value.

For Websockets, the initial value for the Server-Name Option is given by the HTTP Host header field.

4.3.2. Max-Message-Size Capability Option

The sender can use the Max-Message-Size elective 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. A peer that relies on this option being indicated with a certain minimum value will enjoy limited interoperability.

4.3.3. Block-wise Transfer Capability Option

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

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 5).

4.4. Ping and Pong Messages

In CoAP over TCP, Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient (see also Section 4.4). This provides a basic keep-alive function that can refresh NAT bindings. In contrast, Ping and Pong messages are a bidirectional exchange.

Upon receipt of a Ping message, a single Pong message is returned with the identical token. 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).

4.4.1. Custody Option

A peer replying to a Ping message can add a Custody elective option to the Pong message it returns. This option indicates that the application has processed all request/response messages that it has received in the present connection ahead of the Ping message that prompted the Pong message. (Note that there is no definition of specific application semantics of “processed”, but there is an expectation that the sender of the Ping leading to the Pong with a Custody Option should be able to free buffers based on this indication.)

A Custody elective option can also be sent in a Ping message to explicitly request the return of a Custody Option in the Pong message. A peer is always free to indicate that it has finished processing all previous request/response messages by sending a Custody Option in a Pong message. A peer is also free NOT to send a Custody Option in case it is still processing previous request/response messages; however, it SHOULD delay its response to a Ping with a Custody Option until it can also return one.

4.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 MAY be included. A release message will normally be replied to by the peer 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 Bad-Server-Name elective option indicates that the default indicated by the CSM Server-Name Option is unlikely to be useful for this server.

The Alternative-Address elective option requests the peer to instead open a connection of the same kind 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 Hold-Off elective option indicates that the server is requesting that the peer not reconnect to it for the number of seconds given in the value.

4.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 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 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.

One reason for an sender to generate an abort message is a general syntax error in the byte stream received. No specific option has been defined for this, as the details of that syntax error are best left to a diagnostic payload.

4.7. Capability and Settings examples

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

    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

CLIENT                                       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)   |

CLIENT                                        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 ]

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

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

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

   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"                   |
     |          |          |    +------------------------------------+
     |          |          |

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

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

Email: teemu.savolainen@nokia.com