How They Work

{"_id":"573b6d2537fcf72000a2e6d2","project":"5564f26a1fd04c0d00dc9aaa","user":"5564f227f0f70f0d00a9ab20","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"},"parentDoc":null,"__v":14,"category":{"_id":"56731b714b2a680d00524daf","project":"5564f26a1fd04c0d00dc9aaa","version":"5564f26a1fd04c0d00dc9aad","__v":1,"pages":["56731edc58c4890d00bb5439"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-17T20:30:41.290Z","from_sync":false,"order":3,"slug":"subscriptions","title":"Subscriptions"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-17T19:12:37.807Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Subscriptions allow messages from one device to be automatically delivered to another. This document will explain how subscriptions work in the context of [Subscriptions 2.0](doc:subscriptions-2-0) and the [Firehose](doc:firehose). Prior subscription mechanisms in Meshblu are deprecated.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/vjXxHQ70So2Pwb6Wba0o_Subscription%201.svg\",\n \"Subscription 1.svg\",\n \"0\",\n \"0\",\n \"#323232\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nIn this example, `Device B` subscribes to all broadcasts sent from `Device A`. Using the [Subscriptions 2.0](doc:subscriptions-2-0) API the subscription would look like this:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"emitterUuid\\\": \\\"Device A\\\",\\n \\\"subscriberUuid\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.sent\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Permissions\",\n \"body\": \"Subscriptions will only be activated if the proper permissions are available. Device B must be in Device A's `broadcast.sent` whitelist. Device A may revoke that permission at any time that will instantly deactivate the subscription.\\n\\nSee [Permissions 2.0](doc:permissions-2-0) for more detailed information.\"\n}\n[/block]\nIn this scenario, `Device B` must also subscribe to its own `broadcast.received` messages. This allows each device to control what messages it automatically receives from Meshblu.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"emitterUuid\\\": \\\"Device B\\\",\\n \\\"subscriberUuid\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.received\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Routes\"\n}\n[/block]\nKnowing the origin of a message can be very important when building automations. Meshblu will provide metadata that shows the path each subscription took.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"metadata\\\": {\\n \\\"route\\\": [\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device A\\\",\\n \\\"type\\\": \\\"broadcast.sent\\\"\\n },\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.recevied\\\"\\n }\\n ]\\n },\\n \\\"data\\\": {\\n \\\"devices\\\": [\\\"*\\\"]\\n }\\n} \",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nEach hop in a chain of subscriptions is appended to the `route` property in chronological order. The `from` in the first route in the list is the originator of the message. This information allows you to determine how your device received a particular message.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Advanced Subscriptions\"\n}\n[/block]\n[Subscriptions 2.0](doc:subscriptions-2-0) allow fine grained control over message types. In some advanced cases, a device may want to subscribe to messages received by another device, instead of messages emitted from that device.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/nufNSfMmToixiBx9ssWI_What%20is%20Subscription%20Broadcast%20Received.svg\",\n \"What is Subscription Broadcast Received.svg\",\n \"0\",\n \"0\",\n \"#323232\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nIn this example, `Device C` will receive any broadcasts that `Device B` receives. `Device C` will not receive any broadcasts that are sent by `Device B` without creating an additional subscription.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"emitterUuid\\\": \\\"Device B\\\",\\n \\\"subscriberUuid\\\": \\\"Device C\\\",\\n \\\"type\\\": \\\"broadcast.received\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nThe message route will also reflect the additional hop taken by the new subscription.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"metadata\\\": {\\n \\\"route\\\": [\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device A\\\",\\n \\\"type\\\": \\\"broadcast.sent\\\"\\n },\\n {\\n \\\"to\\\": \\\"Device B\\\",\\n \\\"from\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.recevied\\\"\\n },\\n {\\n \\\"to\\\": \\\"Device C\\\",\\n \\\"from\\\": \\\"Device B\\\",\\n \\\"type\\\": \\\"broadcast.recevied\\\"\\n }\\n ]\\n },\\n \\\"data\\\": {\\n \\\"devices\\\": [\\\"*\\\"]\\n }\\n} \",\n \"language\": \"json\"\n }\n ]\n}\n[/block]","excerpt":"","slug":"how-subscriptions-work","type":"basic","title":"How They Work"}

Subscriptions allow messages from one device to be automatically delivered to another. This document will explain how subscriptions work in the context of [Subscriptions 2.0](doc:subscriptions-2-0) and the [Firehose](doc:firehose). Prior subscription mechanisms in Meshblu are deprecated. [block:image] { "images": [ { "image": [ "https://files.readme.io/vjXxHQ70So2Pwb6Wba0o_Subscription%201.svg", "Subscription 1.svg", "0", "0", "#323232", "" ] } ] } [/block] In this example, `Device B` subscribes to all broadcasts sent from `Device A`. Using the [Subscriptions 2.0](doc:subscriptions-2-0) API the subscription would look like this: [block:code] { "codes": [ { "code": "{\n \"emitterUuid\": \"Device A\",\n \"subscriberUuid\": \"Device B\",\n \"type\": \"broadcast.sent\"\n}", "language": "json" } ] } [/block] [block:callout] { "type": "warning", "title": "Permissions", "body": "Subscriptions will only be activated if the proper permissions are available. Device B must be in Device A's `broadcast.sent` whitelist. Device A may revoke that permission at any time that will instantly deactivate the subscription.\n\nSee [Permissions 2.0](doc:permissions-2-0) for more detailed information." } [/block] In this scenario, `Device B` must also subscribe to its own `broadcast.received` messages. This allows each device to control what messages it automatically receives from Meshblu. [block:code] { "codes": [ { "code": "{\n \"emitterUuid\": \"Device B\",\n \"subscriberUuid\": \"Device B\",\n \"type\": \"broadcast.received\"\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Routes" } [/block] Knowing the origin of a message can be very important when building automations. Meshblu will provide metadata that shows the path each subscription took. [block:code] { "codes": [ { "code": "{\n \"metadata\": {\n \"route\": [\n {\n \"to\": \"Device B\",\n \"from\": \"Device A\",\n \"type\": \"broadcast.sent\"\n },\n {\n \"to\": \"Device B\",\n \"from\": \"Device B\",\n \"type\": \"broadcast.recevied\"\n }\n ]\n },\n \"data\": {\n \"devices\": [\"*\"]\n }\n} ", "language": "json" } ] } [/block] Each hop in a chain of subscriptions is appended to the `route` property in chronological order. The `from` in the first route in the list is the originator of the message. This information allows you to determine how your device received a particular message. [block:api-header] { "type": "basic", "title": "Advanced Subscriptions" } [/block] [Subscriptions 2.0](doc:subscriptions-2-0) allow fine grained control over message types. In some advanced cases, a device may want to subscribe to messages received by another device, instead of messages emitted from that device. [block:image] { "images": [ { "image": [ "https://files.readme.io/nufNSfMmToixiBx9ssWI_What%20is%20Subscription%20Broadcast%20Received.svg", "What is Subscription Broadcast Received.svg", "0", "0", "#323232", "" ] } ] } [/block] In this example, `Device C` will receive any broadcasts that `Device B` receives. `Device C` will not receive any broadcasts that are sent by `Device B` without creating an additional subscription. [block:code] { "codes": [ { "code": "{\n \"emitterUuid\": \"Device B\",\n \"subscriberUuid\": \"Device C\",\n \"type\": \"broadcast.received\"\n}", "language": "json" } ] } [/block] The message route will also reflect the additional hop taken by the new subscription. [block:code] { "codes": [ { "code": "{\n \"metadata\": {\n \"route\": [\n {\n \"to\": \"Device B\",\n \"from\": \"Device A\",\n \"type\": \"broadcast.sent\"\n },\n {\n \"to\": \"Device B\",\n \"from\": \"Device B\",\n \"type\": \"broadcast.recevied\"\n },\n {\n \"to\": \"Device C\",\n \"from\": \"Device B\",\n \"type\": \"broadcast.recevied\"\n }\n ]\n },\n \"data\": {\n \"devices\": [\"*\"]\n }\n} ", "language": "json" } ] } [/block]

Meshblu

Documentation

Security

Messages

Subscriptions

Message Forwarders

Authentication

Examples

Demos

Config Events