{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"How They Work","type":"basic","slug":"how-subscriptions-work","excerpt":"","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]","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"573b6d2537fcf72000a2e6d2","project":"5564f26a1fd04c0d00dc9aaa","user":"5564f227f0f70f0d00a9ab20","createdAt":"2016-05-17T19:12:37.807Z","githubsync":"","version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5564f26b1fd04c0d00dc9aae","556741d17acd550d0075eaca","556741d87acd550d0075eacb","556742f87acd550d0075ead1","556781cd6976ef0d0099c545","5568d666d33aad0d00ec8d2e","557f6b2d38249b0d00d0d12b","55b67be9c2e909190073ed38","564e56c601e80e0d00396684","56731b714b2a680d00524daf","573612ac652bd80e00a90027","57365e2cf8ebd31700769f50","57366131f8ebd31700769f58","573b93514e029d19000b8669","573bbfdb7ac6f6170033bd35"],"_id":"5564f26a1fd04c0d00dc9aad","createdAt":"2015-05-26T22:23:38.671Z","project":"5564f26a1fd04c0d00dc9aaa","releaseDate":"2015-05-26T22:23:38.671Z","__v":15},"parentDoc":null,"__v":14,"category":{"sync":{"isSync":false,"url":""},"pages":["56731edc58c4890d00bb5439"],"title":"Subscriptions","slug":"subscriptions","order":3,"from_sync":false,"reference":false,"_id":"56731b714b2a680d00524daf","project":"5564f26a1fd04c0d00dc9aaa","version":"5564f26a1fd04c0d00dc9aad","__v":1,"createdAt":"2015-12-17T20:30:41.290Z"}}

Documentation

Security

Messages

Subscriptions

Message Forwarders

Authentication

Examples

Demos

Config Events

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]