Skip to content

Latest commit

 

History

History
201 lines (169 loc) · 7.42 KB

README.md

File metadata and controls

201 lines (169 loc) · 7.42 KB
Raw

CoAP Publish-Subscribe interface to RabbitMQ

Plug-in for the RabbitMQ broker implementing the Publish-Subscribe Broker for the Constrained Application Protocol (CoAP), which is designed for the Constrained RESTful Environments.

The REST architecture style promotes client-server operations on cacheable resources. This plug-in implements a REST API for the the Last Value Cache; a CoAP resource represents an information in the cache and (AMQP) messages represent updates of the cached information.

This is an experimental implementation of the draft-koster-core-coap-pubsub-02. Not for operational use.

The implementation is based on the Generic Erlang CoAP Client/Server. It supports the following features:

Interactions

Quick Introduction

RabbitMQ will listen for UDP packets on port 5683. You can use the command-line tool from libcoap, or any other CoAP client and perform all standard operations:

  • Discover the /ps function and available resources by GET /.well-known/core. Thr broker will return a link to the pub/sub function and a list of resources that can be accessed by the user "anonymous", or an empty list if the user "anonymous" does not exist. 
    $ ./coap-client coap://127.0.0.1/.well-known/core
</ps>;rt="core.ps",</ps/%2F/topic1>;ct=0;sz=15600

    $ ./coap-client coap://127.0.0.1/.well-known/core?rt=core.ps
</ps>;rt="core.ps"
  • Create a topic by POST /ps/vhost "<topic1>". The broker will create an x-lvc exchange named "topic1" in a given vhost. The default vhost is called "/", which must be encoded as "%2f". 
    $ ./coap-client -m post coap://127.0.0.1/ps/%2f -e "<topic1>"
  • Publish to a topic by PUT /ps/vhost/topic1 "1033.3" or PUT /ps/vhost/topic1/key "1033.3". The broker will publish a message to the exchange "topic1" in a given vhost, optionally using the routing key "key". 
    $ ./coap-client -m put coap://127.0.0.1/ps/%2f/topic1 -e "1033.3"
  • Get the most recent published value by GET /ps/vhost/topic1 or GET /ps/vhost/topic1/key 
    $ ./coap-client coap://127.0.0.1/ps/%2f/topic1
1033.3
  • Subscribe to a topic by GET /ps/vhost/topic1 Observe:0 or GET /ps/vhost/topic1/key Observe:0
  • Receive publications as 2.05 Content 
    $ ./coap-client coap://127.0.0.1/ps/%2f/topic1 -s 10
  • Remove a topic by DELETE /ps/vhost/topic1
    The broker will delete the exchange "topic1" in a given vhost and terminate all CoAP observers of this topic. 
    $ ./coap-client -m delete coap://127.0.0.1/ps/%2f/topic1

RabbitMQ Behaviour

Each CoAP topic is implemented as an RabbitMQ exchange. Subscription to a topic is implemented using a temporary RabbitMQ queue bound to that exchange.

Names of the temporary queues are composed from a prefix coap/ and IP:port of the subscriber. For example, a subscription from 127.0.0.1:40212 will be served by the queue coap/127.0.0.1:40212. Deleting this queue will forcibly terminate the observer.

All CoAP clients are authenticated as a user "anonymous". By setting RabbitMQ permissions for this user you can restrict access rights of the CoAP clients. The authenticated DTLS access is not supported (for now).

The message attributes gets converted as shown in the following table:

AMQP CoAP
message_id (<= 8 bytes) ETag
4 bytes of SHA(message_id) ETag (from AMQP)
expiration [milliseconds] Max-Age [seconds]
content_type Content-Format

The implementation intentionally differs from the draft-02 in the following aspects:

  • The POST and DELETE operations are idempotent. Creating a topic that already exist causes 2.01 "Created" instead of 4.03 "Forbidden". Similarly, deleting a topic that does not exist causes 2.02 "Deleted".
  • Topic values are listed under .well-known/core as standard resources.

Installation

This plug-in requires the Last value caching exchange. Please make sure that both rabbitmq_lvc and rabbitmq_coap_pubsub are installed.

RabbitMQ Configuration

To enable access via the plain CoAP (without authentication) you need to create the user "anonymous" with desired access rights.

To change the default settings you may add the rabbitmq_coap_pubsub section to your RabbitMQ Configuration.

Key Documentation 
prefix
 Path to the pub/sub Function. The path is defined as a list of strings; each string defines one segment of the absolute path to the resource.
Default: 
[<<"ps">>]
 
udp_listen
 Port for incoming coap:// requests.
Default: 
5683
 
dtls_listen
 Port for incoming coaps:// requests.
Disabled by default. 
dtls_options
 Configuration of the DTLS server. Shall include at least certfile and keyfile fields. See ssl_option() for more details.

For example:

{rabbitmq_coap_pubsub, [
    {prefix, [<<"ps">>]},
    {udp_listen, 5683},
    {dtls_listen, 5684},
    {dtls_options, [
        {certfile, "/etc/rabbitmq/cert.pem"},
        {keyfile, "/etc/rabbitmq/key.pem"}
    ]}
]}

Installation from source

Build Status

Build and activate the RabbitMQ plug-in rabbitmq-coap-pubsub. See the Plugin Development Guide for more details.

$ git clone -b stable https://github.com/gotthardp/rabbitmq-coap-pubsub.git
$ cd rabbitmq-coap-pubsub
$ make dist

History

  • 0.2.0 (Dec 22, 2015) Compatible with RabbitMQ 3.6.x and later.
  • 0.1.0 (Nov 14, 2015) First release. Compatible with RabbitMQ 3.5.x only.

Copyright and Licensing

Copyright (c) 2015 Petr Gotthard [email protected]. All Rights Reserved.

This package is subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/.

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.