baudcast

A socket-based, realtime messaging API; designed for the internet of things.

baudcast is a node module that allows machine-to-machine (M2M) communication of internet-connected devices over a simple and configurable REST API.

No registration/setup required, just start baudcasting and receiving key-value data right away.

Installation

Open your app's folder in the terminal and run the following command:

$ npm install baudcast

Usage

baudcast can be easily configured to use custom endpoints and response templates.

As an example, the HAPI-REST API specification has been implemented with baudcast:

var app = require('express')();
var bodyParser = require('body-parser');
var server = require('http').Server(app);
var client = require('redis').createClient();
var baudcast = require('baudcast')(server, client);
 
app.use(bodyParser()); // necessary for handling POST variables
 
app.get('/', function(req, res) { res.send('<i>baudcasting</i> things...'); });
 
 
/* set up endpoint to make a baudcast */
app.post('/baudcast/for/:thing', baudcast.route.makeNewBaudcast);
app.get('/baudcast/for/:thing', baudcast.route.makeNewBaudcast); // GET works too
 
/* set up endpoint to get last baudcast */
app.get('/get/last/baudcast/from/:thing', baudcast.route.getLastBaudcast);
 
/* set up endpoint to get last 800 baudcasts */
app.get('/get/baudcasts/from/:thing', baudcast.route.getBaudcasts);
 
 
/* set up custom response template */
var template = {
    verb: {
        get: 'getting',
        create: 'creating'
    },
 
    respondSuccess: function (action, resourceType, data) {
        var response = {
            this: "succeeded",
            by: this.verb[action],
            the: resourceType,
            with: data
        };
 
        return response;
    },
 
    respondFailure: function(why, apiErrorCode) {
        var response = {
            this: "failed",
            with: apiErrorCode || 500,
            because: why
        };
 
        return response;
    }
};
 
baudcast.useTemplate(template);
 
 
app.listen(3000);
server.listen(8888);
console.log('Server on port 3000, socket on port 8888...');

baudcasting

Simply call the following URL(as set up in the code) to make a new baudcast:

http://{some-host}:3000/baudcast/for/{thing}?foo=bar&baz=qux

The server will respond with:

{
    "this": "succeeded",
    "by": "creating",
    "the": "baudcast",
    "with": {
        "thing": "{thing}",
        "created": 1402642240997,
        "content": {
            "foo": "bar",
            "baz": "qux"
        }
    }
}

The POST method can also be used to baudcast valid JSON data.

Getting baudcasts

The last 800 baudcasts made by a thing over the last 24 hours can be retrieved by calling the following URL:

http://{some-host}:3000/get/baudcasts/from/{thing}

The server will return an array of baudcasts in the following form:

{
    "this": "succeeded",
    "by": "getting",
    "the": "baudcasts",
    "with": [
        {
            "thing": "{thing}",
            "created": 1402642240997,
            "content": {
                "hello": "again"
            }
        },
        {
            "thing": "{thing}",
            "created": 1402640319211,
            "content": {
                "hello": "world"
            }
        }
    ]
}

The latest baudcast made by a thing can be retrieved by making a call to the following URL:

http://{some-host}:3000/get/last/baudcast/from/{thing}

The server will return a single baudcast in the following form:

{
    "this": "succeeded",
    "by": "getting",
    "the": "baudcast",
    "with": {
        "thing": "{thing}",
        "created": 1402642240997,
        "content": {
            "foo": "bar",
            "baz": "qux"
        }
    }
}

Apart from the API endpoints, a device can also subscribe to a thing (or publish a new baudcast) using the popular socket.io framework.

To use baudcast with js, just include the socket.io script:

<script src="https://cdn.socket.io/socket.io-1.0.4.js"></script>

and use the following code:

var socket = io('http://{some-host}:8888');
 
socket.emit('subscribe', '{thing}'); // you can subscribe to as many things you like
 
socket.on('baudcast', function(baudcast) {
    // do your magic here
    console.log(baudcast);
 
});
 
socket.emit('baudcast', '{another-thing}', {ping: 'pong'});

Each baudcast received, for a subscribed thing will be an Object of the form:

{
    thing: "{thing}",
    created: 1402642240997,
    content: {
        foo: "bar",
        baz: "qux"
    }
}

API

for(thing, content)

This function makes a new baudcast for a thing.

from(thing, callback)

This function executes callback(baudcast) everytime a thing makes a new baudcast.

route.makeNewBaudcast(req, res)

This is the app handler for making a new baudcast. This supports POST as well as GET variables.

route.getLastBaudcast(req, res)

This is the handler for retrieving the most recent baudcast made by a thing. Since baudcasts are realtime and ephemeral, they are only stored for 24 hours.

route.getBaudcasts(req, res)

This is the handler for retrieving all the baudcasts made by a thing. Again, because baudcasts are ephemeral, only the last 800 baudcasts are stored.

useTemplate(newTemplate)

This function is used to specify the response template of the REST API. Note that it's argument is a JSON object that should contain the methods respondSuccess and respondFailure, whose signatures should follow guidelines in the example.

Examples

Simple wireless control of Arduino LED