emqx/apps/emqx_gateway/src/coap

Table of Contents

1. EMQX 5.0 CoAP Gateway
   1. Features
      1. PubSub Handler
      2. MQTT Handler
      3. Heartbeat
      4. Query String
   2. Implementation
      1. Request/Response flow
   3. Example

EMQX 5.0 CoAP Gateway

emqx-coap is a CoAP Gateway for EMQ X Broker. It translates CoAP messages into MQTT messages and make it possible to communiate between CoAP clients and MQTT clients.

Features

• Partially achieves Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) we called this as ps handler, include following functions:
  • Publish
  • Subscribe
  • UnSubscribe
• Long connection and authorization verification called as MQTT handler

PubSub Handler

1. Publish

   Method: POST
   URI Schema: ps/{+topic}{?q*}
   q*: Shared Options
   Response:

   • 2.04 "Changed" when success
   • 4.00 "Bad Request" when error
   • 4.01 "Unauthorized" when with wrong auth uri query

2. Subscribe

   Method: GET Options:

   • Observer = 0

   URI Schema: ps/{+topic}{?q*}
   q*: see Shared Options
   Response:

   • 2.05 "Content" when success
   • 4.00 "Bad Request" when error
   • 4.01 "Unauthorized" when with wrong auth uri query

          Client1   Client2                                          Broker
        |          |                   Subscribe                   |
        |          | ----- GET /ps/topic1 Observe:0 Token:XX ----> |
        |          |                                               |
        |          | <---------- 2.05 Content Observe:10---------- |
        |          |                                               |
        |          |                                               |
        |          |                    Publish                    |
        | ---------|----------- PUT /ps/topic1 "1033.3"  --------> |
        |          |                    Notify                     |
        |          | <---------- 2.05 Content Observe:11 --------- |
        |          |                                               |

3. UnSubscribe

   Method : GET Options:

   • Observe = 1

   URI Schema: ps/{+topic}{?q*}
   q*: see Shared Options
   Response:

   • 2.07 "No Content" when success
   • 4.00 "Bad Request" when error
   • 4.01 "Unauthorized" when with wrong auth uri query

MQTT Handler

Establishing a connection is optional. If the CoAP client needs to use connection-based operations, it must first establish a connection. At the same time, the connectionless mode and the connected mode cannot be mixed. In connection mode, the Publish/Subscribe/UnSubscribe sent by the client must be has Token and ClientId in query string. If the Token and Clientid is wrong/miss, EMQ X will reset the request. The communication token is the data carried in the response payload after the client successfully establishes a connection. After obtaining the token, the client's subsequent request must attach "token=Token" to the Query String ClientId is necessary when there is a connection, and is a unique identifier defined by the client. The server manages the client through the ClientId. If the ClientId is wrong, EMQ X will reset the request.

1. Create a Connection

   Method: POST URI Schema: mqtt/connection{?q*} q*:

   • clientid := client uid
   • username
   • password

   Response:

   • 2.01 "Created" when success
   • 4.00 "Bad Request" when error
   • 4.01 "Unauthorized" wrong username or password

   Payload: Token if success

2. Close a Connection

   Method : DELETE URI Schema: mqtt/connection{?q*} q*:

   • clientid := client uid
   • token

   Resonse:

   • 2.01 "Deleted" when success
   • 4.00 "Bad Request" when error
   • 4.01 "Unauthorized" wrong clientid or token

Heartbeat

The Coap client can maintain the "connection" with the server through the heartbeat, regardless of whether it is authenticated or not, so that the server will not release related resources Method : PUT URI Schema: mqtt/connection{?q*} q*:

• clientid if authenticated
• token if authenticated

Response:

• 2.01 "Changed" when success
• 4.00 "Bad Request" when error
• 4.01 "Unauthorized" wrong clientid or token

Query String

CoAP gateway uses some options in query string to conversion between MQTT CoAP.

1. Shared Options

   • clientid
   • token

2. Connect Options

   • username
   • password

3. Publish

   Option	Type	Default
   retain	boolean	false
   qos	MQTT Qos	See here
   expiry	Message Expiry Interval	0(Never expiry)

4. Subscribe

   Option	Type	Default
   qos	MQTT Qos	See here
   nl	MQTT Subscribe No Local	0
   rh	MQTT Subscribe Retain Handing	0

5. MQTT Qos <=> CoAP non/con

   1.notif_type Control the type of notify messages when the observed object has changed.Can be:

   • non
   • con
   • qos in this value, MQTT Qos0 -> non, Qos1/Qos2 -> con

   2.subscribe_qos Control the qos of subscribe.Can be:

   • qos0
   • qos1
   • qos2
   • coap in this value, CoAP non -> qos0, con -> qos1

   3.publish_qos like subscribe_qos, but control the qos of the publish MQTT message

Implementation

Request/Response flow

1. Authorization check

   Check whether the clientid and token in the query string match the current connection

2. Session

   Manager the "Transport Manager" "Observe Resouces Manger" and next message id

3. Transport Mnager

   Manager "Transport" create/close/dispatch

4. Observe resources Mnager

   Mnager observe topic and token

5. Transport

   

   1. Shared State

      

6. Handler

   1. pubsub

      Method	Observe	Action
      GET	0	subscribe and reply result
      GET	1	unsubscribe and reply result
      POST	X	publish and reply result

   2. mqtt

      Method	Action
      PUT	reply result
      POST	return create connection action
      DELETE	return close connection action

Example

1. Create Connection

coap-client -m post -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&username=admin&password=public"

Server will return token X in payload

2. Update Connection

coap-client -m put -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=X"

3. Publish

coap-client -m post -e "Hellow" "obstoken" "coap://127.0.0.1/ps/coap/test?clientid=123&username=admin&password=public"

if you want to publish with auth, you must first establish a connection, and then post publish request on the same socket, so libcoap client can't simulation publish with a token

coap-client -m post -e "Hellow" "coap://127.0.0.1/ps/coap/test?clientid=123&token=X"

4. Subscribe

coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://127.0.0.1/ps/coap/test?clientid=123&username=admin&password=public"

Or

coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://127.0.0.1/ps/coap/test?clientid=123&token=X"

5. Close Connection

coap-client -m delete -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=X