ponte

The Internet of Things Bridge for REST developers

Ponte

Ponte is a multi-transport Internet of Things / Machine to Machine broker. As the current state it supports MQTT and REST APIs over HTTP and CoAP.

Ponte is under active development, but it should work :). If you plan to use Ponte in production let us know, we'll be more than happy to help you getting started and solve any issue you'll find out.

A test instance of ponte is available at ponte.eclipse.org, on HTTP, MQTT and CoAP standard ports.

Installation

Ponte is a node.js application, so it needs node.js to run.

$ npm install ponte bunyan -g
$ ponte -v | bunyan

Then you can connect to it with your preferred MQTT, CoAP or HTTP client.

Command Line Options

$ ./bin/ponte --help
 
  Usage: ponte [options]
 
  Options:
 
    -h, --help           output usage information
    -V, --version        output the version number
    -m, --mqtt-port <n>  the mqtt port to listen to
    -p, --http-port <n>  the http port to listen to
    -a, --coap-port <n>  the coap port to listen to
    --host <host>        the host to listen to
    --coap-host <host>   the host to listen to for coap requests
    --mqtt-host <host>   the host to listen to for mqtt requests
    --http-host <host>   the host to listen to for http requests
    -d, --db <path>      the path were to store the database
    -c, --config <c>     the config file to use (override every other option)
    -v, --verbose        set the bunyan log to INFO
    --very-verbose       set the bunyan log to DEBUG

Usage Example

Start ponte:

$ ponte -v | bunyan

Publishing from HTTP to MQTT

Publish from HTTP:

$ curl -X PUT -d 'world' http://localhost:3000/resources/hello

The messages from HTTP are retained, which means that are sent to every new subscriber.

Subscribe using mosquitto_sub (mosquitto):

$ mosquitto_sub -t "hello" -v
hello world

Publishing from MQTT to HTTP

In order to publish a message that can be read from HTTP, a MQTT client needs to set the retain flag. This is how it is done using mosquitto_pub:

$ mosquitto_pub -t hello-from-mqtt -m "world" -r

Reading the published value is an HTTP GET away:

$ curl http://localhost:3000/resources/hello-from-mqtt
world

Publishing from CoAP to MQTT

You can send CoAP messages from the command line using coap-cli In the following example we do a CoAP PUT to a resource:

$ echo -n 'world' | coap put coap://localhost/r/hello

Subscribe using mosquitto_sub (mosquitto):

$ mosquitto_sub -t "hello" -v
hello world

Publishing MQTT to CoAP

In order to publish a message that can be read from CoAP, a MQTT client needs to set the retain flag. This is how it is done using mosquitto_pub:

$ mosquitto_pub -t hello-from-mqtt -m "world" -r

In order to receive the live updates with CoAP, we need to use the observe switch:

$ coap -o coap://localhost/r/hello-from-mqtt

Embedding

Ponte can be run in embbedded mode, by listening to specific events:

var ponte = require("ponte");
var opts = {
  logger: {
    level: 'info'
  },
  http: {
    port: 3000 // tcp 
  },
  mqtt: {
    port: 3001 // tcp 
  },
  coap: {
    port: 3000 // udp 
  },
  persistence: {
    type: 'level',
    path: './db'
  }
};
var server = ponte(opts);
 
server.on("updated", function(resource, buffer) {
  console.log("Resource Updated", resource, buffer);
});
 
// Stop the server after 1 minute 
setTimeout(function() {
  server.close(function() {
    console.log("server stopped");
  });
}, 60 * 1000);

Configuration

Configuration with MongoDB

Ponte can be run on top of MongoDB with the following configuration:

module.exports = {
  persistence: {
    // same as http://mcollina.github.io/mosca/docs/lib/persistence/mongo.js.html 
    type: "mongo",
    url: "mongodb://localhost:27017/ponte"
  },
  broker: {
    // same as https://github.com/mcollina/ascoltatori#mongodb 
    type: "mongo",
    url: "mongodb://localhost:27017/ponte"
  },
  logger: {
    level: 30, // or 20 or 40 
    name: "MongoPonte"
  }
};

Launch it with $ ponte -c config.js.

Configuration with Redis

Ponte can be run on top of Redis with the following configuration:

module.exports = {
  persistence: {
    // same as http://mcollina.github.io/mosca/docs/lib/persistence/redis.js.html 
    type: "redis",
    host: "localhost"
  },
  broker: {
    // same as https://github.com/mcollina/ascoltatori#redis 
    type: "redis",
    host: "localhost"
  },
  logger: {
    level: 20,
    name: "Config Test Logger"
  }
};

Launch it with $ ponte -c config.js.

Configuration with MQTT and Redis

Ponte can be run on top of MQTT broker while using Redis (or similarly MongoDB) with the following configuration:

module.exports = {
  persistence: {
    // same as http://mcollina.github.io/mosca/docs/lib/persistence/redis.js.html 
    type: "redis",
    host: "localhost"
  },
  broker: {
    // same as https://github.com/mcollina/ascoltatori#mqtt 
    type: "mqtt",
    port: "2883",
    host: "localhost"
  },
  logger: {
    level: 20,
    name: "Config Test Logger"
  }
};

Configuration with authentication and authorization callbacks

module.exports = {
  coap: {
    /**
     * @param {Object} req The incoming message @link https://github.com/mcollina/node-coap#incoming
     * @param {Function} callback The callback function. Has the following structure: callback(error, authenticated, subject)
     */
    authenticate: function(req, callback) {
      // Examples: 
      //   Error:             callback(error); 
      //   Authenticated:     callback(null, true, { username: 'someone' }); 
      //   Not authenticated: callback(null, false); 
    },
    /**
     * @param {Object} subject The subject returned by the authenticate function
     * @param {string} topic The topic
     * @param {Function} callback The callback function. Has the following structure: callback(error, authorized)
     */
    authorizeGet: function(subject, topic, callback) {
      // Examples: 
      //   Error:          callback(error); 
      //   Authorized:     callback(null, true); 
      //   Not authorized: callback(null, false); 
    },
    /**
     * @param {Object} subject The subject returned by the authenticate function
     * @param {string} topic The topic
     * @param {Buffer} payload The payload
     * @param {Function} callback The callback function. Has the following structure: callback(error, authorized)
     */
    authorizePut: function(subject, topic, payload, callback) {
      // Examples: 
      //   Error:          callback(error); 
      //   Authorized:     callback(null, true); 
      //   Not authorized: callback(null, false); 
    }
  },
  http: {
    /**
     * @param {Object} req The request object
     * @param {Function} callback The callback function. Has the following structure: callback(error, authenticated, subject)
     */
    authenticate: function(req, callback) {
      // See coap.authenticate 
    },
    /**
     * @param {Object} subject The subject returned by the authenticate function
     * @param {string} topic The topic
     * @param {Function} callback The callback function. Has the following structure: callback(error, authorized)
     */
    authorizeGet: function(subject, topic, callback) {
      // See coap.authorizeGet 
    },
    /**
     * @param {Object} subject The subject returned by the authenticate function
     * @param {string} topic The topic
     * @param {string} payload The payload
     * @param {Function} callback The callback function. Has the following structure: callback(error, authorized)
     */
    authorizePut: function(subject, topic, payload, callback) {
      // See coap.authorizePut 
    }
  },
  mqtt: {
    /**
     * @link https://github.com/mcollina/mosca/wiki/Authentication-&-Authorization
     */
    authenticate: function(client, username, password, callback) {
      // ... 
    },
    authorizePublish: function(client, topic, payload, callback) {
      // ... 
    },
    authorizeSubscribe: function(client, topic, callback) {
      // ... 
    }
  }
}

Launch it with $ ponte -c config.js.

Pub/Sub Brokers

Ponte is based on Ascoltatori, so it supports the same backends:

• RabbitMQ and all implementations of the AMQP protocol.
• Redis, the fabulous key/value store by @antirez.
• Mosquitto and all implementations of the MQTT protocol.
• MongoDB, the documental NoSQL that is revolutionizing how web apps are built.
• ZeroMQ without a central broker, so Ascoltatori can also be used in a P2P fashion.

Persistence

Ponte requires a persistent storage for HTTP syndication and MQTT support. At the current state, it uses Mosca persistence layer. Thus, it offers several persitence options:

• Memory,
• LevelUp,
• Redis,
• MongoDB

All of them can be configured from the configuration file, under the persistence key. The only exception is LevelUp, which can be specified by using the --db option from the command line.

To do

These are the new features you should expect in the coming months:

• [ ] Add Web Hooks support.
• [ ] Document configuration options.
• [ ] Add WebSocket and Server-Sent Events support.
• [ ] Add a Web App for reading and writing.
• [ ] Standalone persistence layer.

Any help is very welcome, so feel free to submit a pull-request.

Eclipse, QEST and Ponte

Ponte is a proposal at Eclipse, and this is a pure-JS rewrite of QEST in Javascript and on top of Mosca. You can find the Eclipse Project Proposal here: http://eclipse.org/proposals/technology.ponte/

Contributing to Ponte

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Makefile and package.json. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

LICENSE

Ponte is dual licensed under the "Eclipse Public License - v 1.0" and the "Eclipse Distribution License - v 1.0".