# CoAP Gateway
# Introduction
The CoAP gateway implements publish, subscribe, and receive messages as standard with Publish-Subscribe Broker for the CoAP (opens new window).
For security reasons, the CoAP gateway implements Connection Mode to provide client access authentication to restrict unauthorized CoAP clients.
# Quick Start
In EMQX 5.0, CoAP gateways can be configured and enabled through the Dashboard.
It can also be enabled via the HTTP API, and emqx.conf e.g:
TIP
Configuring the gateway via emqx.conf requires changes on a per-node basis, but configuring it via Dashboard or the HTTP API will take effect across the cluster.
The CoAP gateway only supports UDP and DTLS type listeners, for a complete list of configurable parameters refer to: Gateway Configuration - Listeners
# Working Mode
CoAP gateway support two working mode:
Connectionless Mode
: This mode fully follows the Publish-Subscribe Broker for the CoAP (opens new window) standard. In this mode there is no need for connection authentication, session and heartbeat maintenance. Only supports:- Message Publish
- Topic Subscribe
- Topic Unsubscribe
Connection Mode
: This model defines the concepts of connection authentication, session, and heartbeat maintenance. Client needs to create a connection before publishing or subscribing. Then it uses the token returned by the connection to invoke message publishing and topic subscription. It supports:- Create connection
- Close connection
- Heartbeat
- Authentication
Enabling Connection Mode
is determined by the connection_required
option:
# emqx.conf
gateway.coap {
## true: Enabling connection mode
## false: Using connectionless mode
connection_required = true
}
2
3
4
5
6
7
TIP
Connection mode
only brings new connection management related interfaces. You can still perform publish/subscribe and unsubscribe operations in this mode, but you need to carry ClientId and Token for each request.
# Authentication
Only available in Connection Mode
.
The client ID, username, and password are provided by the client's Create Connection request. The CoAP gateway supports the following authenticator types:
- Built-in Database Authentication
- MySQL Authentication
- MongoDB Authentication
- PostgreSQL Authentication
- Redis Authentication
- HTTP Server Authentication
- JWT Authentication
For example, to create a built-in database authentication for CoAP gateway via HTTP API, or emqx.conf:
Unlike the MQTT protocol, the gateway only supports the creation of an authenticator, not a list of authenticators (or an authentication chain). When no authenticator is enabled, it means that all CoAP clients are allowed to log in.
For the configuration format of other types of authenticators refer to: Security - Authenticator
# Publish/Subscribe
The CoAP gateway uses the URI path and methods defined in the Publish-Subscribe Broker for the CoAP (opens new window) standard.
Detailed parameters refer to Message Publish, Topic Subscribe, Topic Unsubscribe.
There is no special authorization configurations within CoAP gateway, and its permission control for topics needs to be configured Authorization.
# User Interfaces
- Detailed confguration options: Configuration - CoAP Gateway
- Detailed HTTP APIs description: HTTP API - Gateway
# Client libraries
# Appendix: Client side interfaces
# Create Connection
Only available in Connection Mode
.
This interface is used to create a client connection to the CoAP gateway. When the authentication of the CoAP gateway is enabled, the gateway will verify the clientid
, username
, password
provided by this request to prevent illegal users.
Request Parameters:
- Method:
POST
- URI:
mqtt/connection{?QueryString*}
, theQueryString
is:clientid
: required parameter, UTF-8 string. The gateway uses this string as a unique identifier for the connectionusername
: optional parameter, UTF-8 string. Used for connection authentication.password
: optional parameter, UTF-8 string. Used for connection authentication.
- Payload: empty
Response:
- Return Code:
2.01
: Connection created successfully. Token string for this connection will be returned in the message body.4.00
: Bad request. Detailed error information will be returned in the message body.4.01
: Not authorized. The request format is validated, but authorization falied.
- Payload: When the return code is
2.01
, the message body isToken
, otherwise it isErrorMessage
.Token
: The token string to be used for subsequent requests.ErrorMessage
: the error description messages.
Take libcoap
as an example:
# Initiate a connection request with clientid 123 and username and password admin/public.
# Returned token is 3404490787
coap-client -m post -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&username=admin&password=public"
3404490787
2
3
4
5
TIP
After the connection is successfully created, you can use Dashboard, HTTP API or CLI to check the client list in the CoAP gateway.
# Close Connnection
Only available in Connection Mode
.
This interface is used to close the CoAP connection.
Request Parameters:
- Method:
DELETE
- URI:
mqtt/connection{?QueryString*}
, theQueryString
is:clientid
: required parameter, UTF-8 string. The gateway uses this string as a unique identifier for the connectiontoken
: required parameter, Using the token string returned by Create Connetion request
- Payload: empty
Response:
- Return Code:
2.01
: Close connection successfully.4.00
: Bad request. Detailed error information will be returned in the message body.4.01
: Not authorized. The request format is validated, but authorization falied.
- Payload: When the return code is
2.01
, the message body isToken
, otherwise it isErrorMessage
.
For example:
coap-client -m delete -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=3404490787"
# Hearbeat
Only available in Connection Mode
.
This interface is used to maintain the connection between the CoAP client and the gateway. When the heartbeat expires, the gateway deletes the session, subscription, and releases all resources for that client.
Request Parameters:
- Method:
PUT
- URI:
mqtt/connection{?QueryString*}
, theQueryString
is:clientid
: required parameter, UTF-8 string. The gateway uses this string as a unique identifier for the connectiontoken
: required parameter, Using the token string returned by Create Connetion request
- Payload: empty
Response:
- Return Code:
2.01
: Close connection successfully.4.00
: Bad request. Detailed error information will be returned in the message body.4.01
: Not authorized. The request format is validated, but authorization falied.
- Payload: When the return code is
2.01
, the message body isToken
, otherwise it isErrorMessage
.
For example:
coap-client -m put -e "" "coap://127.0.0.1/mqtt/connection?clientid=123&token=3404490787"
TIP
The heartbeat interval is determined by the hearbeat
option of CoAP gateway, defaults to 30 seconds.
# Message Publish
This interface is used by the CoAP client to send messages to specified topic. Additional identity information needs to be carried if the Connection Mode
enabled.
Request Parameters:
Method:
POST
URI:
mqtt/{+topic}{?QueryString*}
{+topic}
is the topic of publish message, i.e. the URI isps/coap/test
if publish message tocoap/test
.{?QueryString}
is request parameters:clientid
: required inConnection Mode
and optional inConnectionless Mode
.token
:Connection Mode
only, required parameter.retain
: Whether to publish as a retained message. boolean, optional parameter, default isfalse
.qos
: Message QoS, which identifies the QoS level of the message and affects only how the MQTT client receives the message. Enum with0
,1
,2
.expiry
: Message expiry interval in seconds, default is 0 which means never expire
Payload: Message payload
Response:
- Return Code:
2.04
: Publish successfully4.00
: Bad request. Detailed error information will be returned in the message body.4.01
: Not authorized. The request format is validated, but authorization falied.
- Payload: When the return code is
2.04
, the message body is empty, otherwise it isErrorMessage
.
For example, publish a message in Connectionless Mode
:
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test"
Or carry clientid
and token
in Connection Mode
:
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test&clientid=123&token=3404490787"
# Topic Subscribe
This interface is used by the CoAP client to subscribe a topic. Additional identity information needs to be carried if the Connection Mode
enabled.
Request Parameters:
Method:
POST
Options: Set
observer
to0
URI:
mqtt/{+topic}{?QueryString*}
{+topic}
is the topic need to subscribe, i.e. the URI isps/coap/test
if subscribe tocoap/test
.{?QueryString}
is request parameters:clientid
: required inConnection Mode
and optional inConnectionless Mode
.token
:Connection Mode
only, required parameter.qos
: Subscription QoS to indicate which the MessageType(CON
orNON
) used by gateway to deliver messages to CoAP client. Enumerated with:0
: Using NON message to delivery1
or2
: Using CON message to delivery
Payload: empty
Response:
- Return Code:
2.05
: Subscribe successfully4.00
: Bad request. Detailed error information will be returned in the message body.4.01
: Not authorized. The request format is validated, but authorization falied.
- Payload: When the return code is
2.05
, the message body is empty, otherwise it isErrorMessage
.
For example,subscribe coap/test
in Connectionless Mode
:
coap-client -m get -s 60 -O 6,0x00 -o - -T "obstoken" "coap://127.0.0.1/ps/coap/test"
Or, carry clientid
and token
to subscribe in Connection Mode
:
coap-client -m post -e "Hi, this is libcoap" "coap://127.0.0.1/ps/coap/test&clientid=123&token=3404490787"
# Topic Unsubscribe
This interface is used by the CoAP client to unsubscribe a topic. Additional identity information needs to be carried if the Connection Mode
enabled.
Request Parameters:
Method:
GET
URI:
mqtt/{+topic}{?QueryString*}
{+topic}
is the topic need to unsubscribe, i.e. the URI isps/coap/test
if subscribe tocoap/test
.{?QueryString}
is request parameters:clientid
: required inConnection Mode
and optional inConnectionless Mode
.token
:Connection Mode
only, required parameter.
Payload: empty
Response:
- Return Code:
2.07
: Unsubscribe successfully4.00
: Bad request. Detailed error information will be returned in the message body.4.01
: Not authorized. The request format is validated, but authorization falied.
- Payload: When the return code is
2.07
, the message body is empty, otherwise it isErrorMessage
.