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 and the Firehose. Prior subscription mechanisms in Meshblu are deprecated.

In this example, Device B subscribes to all broadcasts sent from Device A. Using the Subscriptions 2.0 API the subscription would look like this:

JSON

{
  "emitterUuid": "Device A",
  "subscriberUuid": "Device B",
  "type": "broadcast.sent"
}

🚧

Permissions

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.

See Permissions 2.0 for more detailed information.

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.

JSON

{
  "emitterUuid": "Device B",
  "subscriberUuid": "Device B",
  "type": "broadcast.received"
}

Routes

Knowing the origin of a message can be very important when building automations. Meshblu will provide metadata that shows the path each subscription took.

JSON

{
  "metadata": {
    "route": [
      {
        "to": "Device B",
        "from": "Device A",
        "type": "broadcast.sent"
      },
      {
        "to": "Device B",
        "from": "Device B",
        "type": "broadcast.recevied"
      }
    ]
  },
  "data": {
    "devices": ["*"]
  }
}

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.

Advanced Subscriptions

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.

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.

JSON

{
  "emitterUuid": "Device B",
  "subscriberUuid": "Device C",
  "type": "broadcast.received"
}

The message route will also reflect the additional hop taken by the new subscription.

JSON

{
  "metadata": {
    "route": [
      {
        "to": "Device B",
        "from": "Device A",
        "type": "broadcast.sent"
      },
      {
        "to": "Device B",
        "from": "Device B",
        "type": "broadcast.recevied"
      },
      {
        "to": "Device C",
        "from": "Device B",
        "type": "broadcast.recevied"
      }
    ]
  },
  "data": {
    "devices": ["*"]
  }
}