emqx/emqx-coap
Fork: 34 Star: 62 (更新于 2024-12-07 14:14:36)
license: Apache-2.0
Language: Erlang .
EMQX CoAP Gateway
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.
最近版本更新:(数据更新于 2024-09-25 14:30:33)
主题(topics):
coap, coap-broker, coap-gateway, coap-server
emqx/emqx-coap同语言 Erlang最近更新仓库
2024-12-05 23:56:16 emqx/emqx
2024-04-12 18:15:12 esl/MongooseIM
2023-06-21 20:44:48 emqx/emqx-plugin-template
2021-12-17 19:39:07 emqx/ekka
2020-11-02 11:27:02 goBuildRun/buildrun-emqx-backend-mysql
1970-01-01 00:00:00 emqx/emqx-rule-engine