{"_id":"5721340c9091d20e003a1f85","project":"5564f26a1fd04c0d00dc9aaa","user":"5564f227f0f70f0d00a9ab20","category":{"_id":"557f6b2d38249b0d00d0d12b","pages":["557f6bd638249b0d00d0d12d","558dc2d7beb7c719007f63ca","564e56e0f42f4d0d00584a0b","564e57971560880d008d30d0","56731675f79ca90d00ad2e3c"],"__v":5,"project":"5564f26a1fd04c0d00dc9aaa","version":"5564f26a1fd04c0d00dc9aad","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-16T00:17:49.280Z","from_sync":false,"order":2,"slug":"messages","title":"Messages"},"parentDoc":null,"__v":17,"version":{"_id":"5564f26a1fd04c0d00dc9aad","project":"5564f26a1fd04c0d00dc9aaa","__v":15,"createdAt":"2015-05-26T22:23:38.671Z","releaseDate":"2015-05-26T22:23:38.671Z","categories":["5564f26b1fd04c0d00dc9aae","556741d17acd550d0075eaca","556741d87acd550d0075eacb","556742f87acd550d0075ead1","556781cd6976ef0d0099c545","5568d666d33aad0d00ec8d2e","557f6b2d38249b0d00d0d12b","55b67be9c2e909190073ed38","564e56c601e80e0d00396684","56731b714b2a680d00524daf","573612ac652bd80e00a90027","57365e2cf8ebd31700769f50","57366131f8ebd31700769f58","573b93514e029d19000b8669","573bbfdb7ac6f6170033bd35"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-27T21:50:04.599Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"In order to receive messages, a device must connect and authenticate with the Firehose. Once connected, the Firehose will immediately start streaming down all messages that the device is subscribed to.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"One thing of note is that a device is not subscribed to its own received messages by default. This is so that low power devices may opt out of receiving messages that they may not be able to handle.\",\n  \"title\": \"Received Subscriptions\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Protocols\"\n}\n[/block]\n* [AMQP](https://meshblu-amqp.readme.io/docs/receive-meshblu-messages)\n* [Socket.io](https://meshblu-socketio.readme.io/)\n* [XMPP](https://meshblu-xmpp.readme.io/)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Message Format\"\n}\n[/block]\nNo matter which protocol is used, all messages have the same structure. However, the structure is encoded in a native way for each protocol (XML for XMPP, AMQP Metadata headers, JSON for Socket.io). For simplicity, only the JSON structure is provided. See the documentation for each of the protocol adapters to see how they encode their respective metadata.\n\nHere's an example for receiving a broadcast message:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"metadata\\\": {\\n \\t\\t\\\"route\\\": [\\n      {\\n        \\\"from\\\": \\\"188824f0-28c4-475b-ab36-2505402bebcb\\\",\\n        \\\"to\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n        \\\"type\\\": \\\"broadcast.sent\\\"\\n      },\\n      {\\n        \\\"from\\\": \\\"188824f0-28c4-475b-ab36-2505402bebcb\\\",\\n        \\\"to\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n        \\\"type\\\": \\\"broadcast.received\\\"\\n      },\\n      {\\n        \\\"from\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n        \\\"to\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n        \\\"type\\\": \\\"broadcast.received\\\"\\n      }\\n    ]\\n  },\\n  \\\"data\\\": {\\n    \\\"devices\\\": [\\\"*\\\"],\\n    \\\"payload\\\": {\\n      \\\"temperature\\\": 87\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"broadcast-message-received.json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"metadata.route\"\n}\n[/block]\nThe `metadata.route` array shows us each hop that happened to get this message delivered to us:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"from\\\": \\\"188824f0-28c4-475b-ab36-2505402bebcb\\\",\\n  \\\"to\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n  \\\"type\\\": \\\"broadcast.sent\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"hop-1.json\"\n    }\n  ]\n}\n[/block]\nThe message started it as a broadcast emitted by `1888...`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"from\\\": \\\"188824f0-28c4-475b-ab36-2505402bebcb\\\",\\n  \\\"to\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n  \\\"type\\\": \\\"broadcast.received\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"hop-2.json\"\n    }\n  ]\n}\n[/block]\nThe message is then forwarded to `cf24...` by way of `cf24...'s` broadcast.sent subscription to `1888...`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"from\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n  \\\"to\\\": \\\"cf2497d2-7426-46c4-a229-ad789063bf88\\\",\\n  \\\"type\\\": \\\"broadcast.received\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"hop-3.json\"\n    }\n  ]\n}\n[/block]\nLastly, the message is put into `cf24...'s` Firehose because of the broadcast.received subscription that `cf24...` has to itself.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"data\"\n}\n[/block]\nThe `data` property contains the raw data of the message that `1888...` originally emitted.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"devices\\\": [\\\"*\\\"],\\n  \\\"payload\\\": {\\n    \\\"temperature\\\": 87\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"data.json\"\n    }\n  ]\n}\n[/block]","excerpt":"Receive all your device's messages, all in one place.","slug":"firehose","type":"basic","title":"Firehose"}

Firehose

Receive all your device's messages, all in one place.

In order to receive messages, a device must connect and authenticate with the Firehose. Once connected, the Firehose will immediately start streaming down all messages that the device is subscribed to. [block:callout] { "type": "warning", "body": "One thing of note is that a device is not subscribed to its own received messages by default. This is so that low power devices may opt out of receiving messages that they may not be able to handle.", "title": "Received Subscriptions" } [/block] [block:api-header] { "type": "basic", "title": "Protocols" } [/block] * [AMQP](https://meshblu-amqp.readme.io/docs/receive-meshblu-messages) * [Socket.io](https://meshblu-socketio.readme.io/) * [XMPP](https://meshblu-xmpp.readme.io/) [block:api-header] { "type": "basic", "title": "Message Format" } [/block] No matter which protocol is used, all messages have the same structure. However, the structure is encoded in a native way for each protocol (XML for XMPP, AMQP Metadata headers, JSON for Socket.io). For simplicity, only the JSON structure is provided. See the documentation for each of the protocol adapters to see how they encode their respective metadata. Here's an example for receiving a broadcast message: [block:code] { "codes": [ { "code": "{\n \"metadata\": {\n \t\t\"route\": [\n {\n \"from\": \"188824f0-28c4-475b-ab36-2505402bebcb\",\n \"to\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"type\": \"broadcast.sent\"\n },\n {\n \"from\": \"188824f0-28c4-475b-ab36-2505402bebcb\",\n \"to\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"type\": \"broadcast.received\"\n },\n {\n \"from\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"to\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"type\": \"broadcast.received\"\n }\n ]\n },\n \"data\": {\n \"devices\": [\"*\"],\n \"payload\": {\n \"temperature\": 87\n }\n }\n}", "language": "json", "name": "broadcast-message-received.json" } ] } [/block] [block:api-header] { "type": "basic", "title": "metadata.route" } [/block] The `metadata.route` array shows us each hop that happened to get this message delivered to us: [block:code] { "codes": [ { "code": "{\n \"from\": \"188824f0-28c4-475b-ab36-2505402bebcb\",\n \"to\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"type\": \"broadcast.sent\"\n}", "language": "json", "name": "hop-1.json" } ] } [/block] The message started it as a broadcast emitted by `1888...` [block:code] { "codes": [ { "code": "{\n \"from\": \"188824f0-28c4-475b-ab36-2505402bebcb\",\n \"to\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"type\": \"broadcast.received\"\n}", "language": "json", "name": "hop-2.json" } ] } [/block] The message is then forwarded to `cf24...` by way of `cf24...'s` broadcast.sent subscription to `1888...` [block:code] { "codes": [ { "code": "{\n \"from\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"to\": \"cf2497d2-7426-46c4-a229-ad789063bf88\",\n \"type\": \"broadcast.received\"\n}", "language": "json", "name": "hop-3.json" } ] } [/block] Lastly, the message is put into `cf24...'s` Firehose because of the broadcast.received subscription that `cf24...` has to itself. [block:api-header] { "type": "basic", "title": "data" } [/block] The `data` property contains the raw data of the message that `1888...` originally emitted. [block:code] { "codes": [ { "code": "{\n \"devices\": [\"*\"],\n \"payload\": {\n \"temperature\": 87\n }\n}", "language": "json", "name": "data.json" } ] } [/block]