emqx-coap

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

Client Usage Example

libcoap is an excellent coap library which has a simple client tool. It is recommended to use libcoap as a coap client.

To compile libcoap, do following steps:

git clone http://github.com/obgm/libcoap
cd libcoap
./autogen.sh
./configure --enable-documentation=no --enable-tests=no
make

Publish example:

libcoap/examples/coap-client -m put -e 1234  "coap://127.0.0.1/mqtt/topic1?c=client1&u=tom&p=secret"

• topic name is "topic1", NOT "/topic1"
• client id is client1
• username is tom
• password is secret
• payload is a text string "1234"

A mqtt message with topic="topic1", payload="1234" has been published. Any mqtt client or coap client, who has subscribed this topic could receive this message immediately.

Subscribe example:

libcoap/examples/coap-client -m get -s 10 "coap://127.0.0.1/mqtt/topic1?c=client1&u=tom&p=secret"

• topic name is "topic1", NOT "/topic1"
• client id is client1
• username is tom
• password is secret
• subscribe time is 10 seconds

And you will get following result if any mqtt client or coap client sent message with text "1234567" to "topic1":

v:1 t:CON c:GET i:31ae {} [ ]
1234567v:1 t:CON c:GET i:31af {} [ Observe:1, Uri-Path:mqtt, Uri-Path:topic1, Uri-Query:c=client1, Uri-Query:u=tom, Uri-Query:p=secret ]

The output message is not well formatted which hide "1234567" at the head of the 2nd line.

Configure

Common

File: etc/emqx_coap.conf

## The UDP port that CoAP is listening on.
##
## Value: Port
coap.port = 5683

## Interval for keepalive, specified in seconds.
##
## Value: Duration
##  -s: seconds
##  -m: minutes
##  -h: hours
coap.keepalive = 120s

## Whether to enable statistics for CoAP clients.
##
## Value: on | off
coap.enable_stats = off

DTLS

emqx_coap enable one-way authentication by default.

If you want to disable it, comment these lines.

File: etc/emqx_coap.conf

## The DTLS port that CoAP is listening on.
##
## Value: Port
coap.dtls.port = 5684

## Private key file for DTLS
##
## Value: File
coap.dtls.keyfile = {{ platform_etc_dir }}/certs/key.pem

## Server certificate for DTLS.
##
## Value: File
coap.dtls.certfile = {{ platform_etc_dir }}/certs/cert.pem

Enable two-way autentication

For two-way autentication:

## A server only does x509-path validation in mode verify_peer,
## as it then sends a certificate request to the client (this
## message is not sent if the verify option is verify_none).
## You can then also want to specify option fail_if_no_peer_cert.
## More information at: http://erlang.org/doc/man/ssl.html
##
## Value: verify_peer | verify_none
## coap.dtls.verify = verify_peer

## PEM-encoded CA certificates for DTLS
##
## Value: File
## coap.dtls.cacertfile = {{ platform_etc_dir }}/certs/cacert.pem

## Used together with {verify, verify_peer} by an SSL server. If set to true,
## the server fails if the client does not have a certificate to send, that is,
## sends an empty certificate.
##
## Value: true | false
## coap.dtls.fail_if_no_peer_cert = false

Load emqx-coap

./bin/emqx_ctl plugins load emqx_coap

CoAP Client Observe Operation (subscribe topic)

To subscribe any topic, issue following command:

  GET  coap://localhost/mqtt/{topicname}?c={clientid}&u={username}&p={password}    with OBSERVE=0

• "mqtt" in the path is mandatory.
• replace {topicname}, {clientid}, {username} and {password} with your true values.
• {topicname} and {clientid} is mandatory.
• if clientid is absent, a "bad_request" will be returned.
• {topicname} in URI should be percent-encoded to prevent special characters, such as + and #.
• {username} and {password} are optional.
• if {username} and {password} are not correct, an uauthorized error will be returned.
• topic is subscribed with qos1.

CoAP Client Unobserve Operation (unsubscribe topic)

To cancel observation, issue following command:

  GET  coap://localhost/mqtt/{topicname}?c={clientid}&u={username}&p={password}    with OBSERVE=1

• "mqtt" in the path is mandatory.
• replace {topicname}, {clientid}, {username} and {password} with your true values.
• {topicname} and {clientid} is mandatory.
• if clientid is absent, a "bad_request" will be returned.
• {topicname} in URI should be percent-encoded to prevent special characters, such as + and #.
• {username} and {password} are optional.
• if {username} and {password} are not correct, an uauthorized error will be returned.

CoAP Client Notification Operation (subscribed Message)

Server will issue an observe-notification as a subscribed message.

• Its payload is exactly the mqtt payload.
• payload data type is "application/octet-stream".

CoAP Client Publish Operation

Issue a coap put command to do publishment. For example:

  PUT  coap://localhost/mqtt/{topicname}?c={clientid}&u={username}&p={password}

• "mqtt" in the path is mandatory.
• replace {topicname}, {clientid}, {username} and {password} with your true values.
• {topicname} and {clientid} is mandatory.
• if clientid is absent, a "bad_request" will be returned.
• {topicname} in URI should be percent-encoded to prevent special characters, such as + and #.
• {username} and {password} are optional.
• if {username} and {password} are not correct, an uauthorized error will be returned.
• payload could be any binary data.
• payload data type is "application/octet-stream".
• publish message will be sent with qos0.

CoAP Client Keep Alive

Device should issue a get command periodically, serve as a ping to keep mqtt session online.

  GET  coap://localhost/mqtt/{any_topicname}?c={clientid}&u={username}&p={password}

• "mqtt" in the path is mandatory.
• replace {any_topicname}, {clientid}, {username} and {password} with your true values.
• {any_topicname} is optional, and should be percent-encoded to prevent special characters.
• {clientid} is mandatory. If clientid is absent, a "bad_request" will be returned.
• {username} and {password} are optional.
• if {username} and {password} are not correct, an uauthorized error will be returned.
• coap client should do keepalive work periodically to keep mqtt session online, especially those devices in a NAT network.

CoAP Client NOTES

emqx-coap gateway does not accept POST and DELETE requests.

Topics in URI should be percent-encoded, but corresponding uri_path option has percent-encoding converted. Please refer to RFC 7252 section 6.4, "Decomposing URIs into Options":

Note that these rules completely resolve any percent-encoding.

That implies coap client is responsible to convert any percert-encoding into true character while assembling coap packet.

ClientId, Username, Password and Topic

ClientId/username/password/topic in the coap URI are the concepts in mqtt. That is to say, emqx-coap is trying to fit coap message into mqtt system, by borrowing the client/username/password/topic from mqtt.

The Auth/ACL/Hook features in mqtt also applies on coap stuff. For example:

• If username/password is not authorized, coap client will get an uauthorized error.
• If username or clientid is not allowed to published specific topic, coap message will be dropped in fact, although coap client will get an acknoledgement from emqx-coap.
• If a coap message is published, a 'message.publish' hook is able to capture this message as well.

well-known locations

Discovery always return ","

For example

libcoap/examples/coap-client -m get "coap://127.0.0.1/.well-known/core"

License

Apache License Version 2.0

Author

EMQX Team.