Meshblu

Meshblu is a cross-protocol IoT machine-to-machine instant messaging system. It is the core messaging system for Citrix's Octoblu IoT platform.

Supported Protocols: HTTP, Socket.io, Websocket, MQTT, CoAP, AMQP, and XMPP.

Version 2.0

We have completely re-written Meshblu into many small components or micro-services. This Meshblu 1.0 repository is being preserved for historical reference.

All of the new Meshblu components are prefixed with meshblu-core. See a list here.

Meshblu is dependent on node.js, redis, mongodb, and either npm or yarn.

Production

In order to run a barebones meshblu-core cluster, you'll need the following repositories.

1. meshblu-core-dispatcher
2. meshblu-core-worker-webhook
3. meshblu-core-protocol-adapter-http

All meshblu-core services and workers have a Dockerfile.

A production Meshblu cluster will consist of many services and workers. We currently don't have documentation for running a complex cluster but we are working on it.

Development

For development use, you can run the bundled barebones cluster:

Installation

git clone https://github.com/octoblu/meshblu
cd meshblu
npm install

See Usage

node command.js --help

Basic Example w/ env

#!/bin/bash

# For development usage only

env \
  PRIVATE_KEY_BASE64="..." \
  PUBLIC_KEY_BASE64="..." \
  PEPPER='some-random-string' \
  MESHBLU_HTTP_PORT='3000' \
  node command.js

See ./test-start.sh

Basic Example w/ args

#!/bin/bash

# For development usage only

node command.js \
  --private-key-base64 '...' \
  --public-key-base64 '...' \
  --pepper 'some-other-random-string' \
  --meshblu-http-port 3000

Debug Mode

It is normal not see any debug output by default. If you want to see debug output, use the environment DEBUG=*, or something more specific, like DEBUG=meshblu*.

It's Alive!

To verify that Meshblu 2.0 is alive and well, open http://localhost:3000/status in a web browser or open a new terminal tab and run:

curl http://localhost:3000/status

You should see Meshblu 2.0 respond with:

{"meshblu":"online"}

You can register a new IoT device by running:

curl -X POST http://localhost:3000/devices

You should see Meshblu 2.0 respond with an authentication UUID and Token as well as the device's security whitelist settings like this:

{ online: false,
  discoverWhitelist: [ '*' ],
  configureWhitelist: [ '*' ],
  sendWhitelist: [ '*' ],
  receiveWhitelist: [ '*' ],
  uuid: 'b112c941-7973-4e2b-8dbe-b7bba27ae199',
  meshblu:
   { createdAt: '2016-11-15T16:07:07.801Z',
     hash: 'Dy5NlIlmygrrnhp0Cln+zb77nHlYdobc+HwbRVzWdPs=' },
  _id: '582b32ab67899618f48c2e1b',
  token: 'd5bcf1a57f4ccefa0ecdc672c7090e7949cc8244' }

Meshblu API Documentation

Checkout our developer docs for more information on our HTTP REST API as well as documentation for all other protocol APIs, security whitelists and blacklists, connectors, data forwarders, and overall Meshblu architecture.

Introducing the Meshblu CLI

We have a convenient command line interface for simplifying the interaction with the Meshblu API.

# Install the meshblu cli utility
npm install --global meshblu-util
# Register a device
meshblu-util register -U http://localhost:3000 > meshblu.json
# Fetch the device
meshblu-util get
# Update the device
meshblu-util update -d '{"type": "some-device"}'
# Fetch the updated device
meshblu-util get

List of meshblu-core components

Workers

1. meshblu-core-dispatcher
2. meshblu-core-worker-webhook

Protocol Adapters

1. meshblu-core-protocol-adapter-socket.io
2. meshblu-core-protocol-adapter-http
3. meshblu-core-protocol-adapter-xmpp
4. meshblu-core-protocol-adapter-coap
5. meshblu-core-protocol-adapter-mqtt
6. meshblu-core-protocol-adapter-http-streaming

Firehoses

1. meshblu-core-worker-firehose-amqp
2. meshblu-core-firehose-socket.io

Balancers

1. meshblu-haproxy
2. meshblu-balancer-http-streaming
3. meshblu-balancer-firehose-socket.io
4. meshblu-balancer-xmpp
5. meshblu-balancer-websocket
6. meshblu-balancer-mqtt
7. meshblu-balancer-coap
8. meshblu-balancer-socket.io

Core Datastores

1. meshblu-core-datastore
2. meshblu-core-cache

Core Managers

1. meshblu-core-manager-token
2. meshblu-core-manager-device
3. meshblu-core-manager-hydrant
4. meshblu-core-manager-whitelist
5. meshblu-core-manager-webhook
6. meshblu-core-manager-subscription
7. meshblu-core-manager-root-token
8. meshblu-core-manager-messenger

Core Tasks

1. meshblu-core-task-black-list-token
2. meshblu-core-task-check-broadcast-received-whitelist
3. meshblu-core-task-check-broadcast-sent-whitelist
4. meshblu-core-task-check-configure-as-whitelist
5. meshblu-core-task-check-configure-whitelist
6. meshblu-core-task-check-discover-as-whitelist
7. meshblu-core-task-check-discover-whitelist
8. meshblu-core-task-check-discoveras-whitelist
9. meshblu-core-task-check-forwarded-for
10. meshblu-core-task-check-receive-as-whitelist
11. meshblu-core-task-check-receive-whitelist
12. meshblu-core-task-check-root-token
13. meshblu-core-task-check-send-as-whitelist
14. meshblu-core-task-check-send-whitelist
15. meshblu-core-task-check-token
16. meshblu-core-task-check-token-black-list
17. meshblu-core-task-check-token-cache
18. meshblu-core-task-check-update-device-is-valid
19. meshblu-core-task-check-whitelist-broadcast-as
20. meshblu-core-task-check-whitelist-broadcast-received
21. meshblu-core-task-check-whitelist-broadcast-sent
22. meshblu-core-task-check-whitelist-configure-as
23. meshblu-core-task-check-whitelist-configure-received
24. meshblu-core-task-check-whitelist-configure-sent
25. meshblu-core-task-check-whitelist-configure-update
26. meshblu-core-task-check-whitelist-discover-as
27. meshblu-core-task-check-whitelist-discover-view
28. [meshblu-core-task-check-whitelist-message-as](https://github.com/octoblu/meshblu-core-task-check-whitelist-