Meshblu is a cross-protocol IoT machine-to-machine messaging system.
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

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
  29. meshblu-core-task-check-whitelist-message-from
  30. meshblu-core-task-check-whitelist-message-received
  31. meshblu-core-task-check-whitelist-message-sent
  32. meshblu-core-task-create-session-token
  33. meshblu-core-task-create-subscription
  34. meshblu-core-task-deliver-webhook
  35. meshblu-core-task-enforce-message-rate-limit
  36. meshblu-core-task-enqueue-deprecated-webhooks
  37. meshblu-core-task-enqueue-jobs-for-forward-broadcast-received
  38. meshblu-core-task-enqueue-jobs-for-forward-configure-received
  39. meshblu-core-task-enqueue-jobs-for-forward-unregister-received
  40. meshblu-core-task-enqueue-jobs-for-subscriptions-broadcast-received
  41. meshblu-core-task-enqueue-jobs-for-subscriptions-broadcast-sent
  42. meshblu-core-task-enqueue-jobs-for-subscriptions-configure-received
  43. meshblu-core-task-enqueue-jobs-for-subscriptions-configure-sent
  44. meshblu-core-task-enqueue-jobs-for-subscriptions-message-received
  45. meshblu-core-task-enqueue-jobs-for-subscriptions-message-sent
  46. meshblu-core-task-enqueue-jobs-for-subscriptions-unregister-received
  47. meshblu-core-task-enqueue-jobs-for-subscriptions-unregister-sent
  48. meshblu-core-task-enqueue-jobs-for-webhooks-broadcast-received
  49. meshblu-core-task-enqueue-jobs-for-webhooks-broadcast-sent
  50. meshblu-core-task-enqueue-jobs-for-webhooks-configure-received
  51. meshblu-core-task-enqueue-jobs-for-webhooks-configure-sent
  52. meshblu-core-task-enqueue-jobs-for-webhooks-message-received
  53. meshblu-core-task-enqueue-jobs-for-webhooks-message-sent
  54. meshblu-core-task-enqueue-jobs-for-webhooks-unregister-received
  55. meshblu-core-task-enqueue-jobs-for-webhooks-unregister-sent
  56. meshblu-core-task-enqueue-webhooks
  57. meshblu-core-task-find-and-update-device
  58. meshblu-core-task-forbidden
  59. meshblu-core-task-get-authorized-subscription-types
  60. meshblu-core-task-get-broadcast-subscription-types
  61. meshblu-core-task-get-device
  62. meshblu-core-task-get-device-public-key
  63. meshblu-core-task-get-global-public-key
  64. meshblu-core-task-get-status
  65. meshblu-core-task-get-subscriptions
  66. meshblu-core-task-migrate-root-token
  67. meshblu-core-task-no-content
  68. meshblu-core-task-protect-your-as
  69. meshblu-core-task-publish-broadcast-received
  70. meshblu-core-task-publish-configure-received
  71. meshblu-core-task-publish-deprecated-subscriptions
  72. meshblu-core-task-publish-message
  73. meshblu-core-task-publish-message-received
  74. meshblu-core-task-publish-subscriptions
  75. meshblu-core-task-publish-unregister-received
  76. meshblu-core-task-register-device
  77. meshblu-core-task-reject-your-as
  78. meshblu-core-task-remove-device-cache
  79. meshblu-core-task-remove-root-session-token
  80. meshblu-core-task-remove-subscription
  81. meshblu-core-task-remove-token-cache
  82. meshblu-core-task-reset-token
  83. meshblu-core-task-revoke-all-tokens
  84. meshblu-core-task-revoke-session-token
  85. meshblu-core-task-revoke-token-by-query
  86. meshblu-core-task-search-device
  87. meshblu-core-task-search-token
  88. meshblu-core-task-send-message
  89. meshblu-core-task-send-message-2
  90. meshblu-core-task-unregister-device
  91. meshblu-core-task-update-device
  92. meshblu-core-task-update-message-rate

Clients

  1. node-meshblu-socket.io
  2. node-meshblu-firehose-socket.io
  3. node-meshblu-http
  4. node-meshblu-websocket
  5. node-meshblu-mqtt
  6. node-meshblu-xmpp
  7. node-meshblu-amqp
  8. node-meshblu-coap
  9. browser-meshblu-http
  10. swift-meshblu-http

Utilities

  1. meshblu-util

Legacy Meshblu 1.x

View it here