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.

🚧

Received Subscriptions

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.

Protocols

• AMQP
• Socket.io
• XMPP

Message Format

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:

broadcast-message-received.json

{
  "metadata": {
 		"route": [
      {
        "from": "188824f0-28c4-475b-ab36-2505402bebcb",
        "to": "cf2497d2-7426-46c4-a229-ad789063bf88",
        "type": "broadcast.sent"
      },
      {
        "from": "188824f0-28c4-475b-ab36-2505402bebcb",
        "to": "cf2497d2-7426-46c4-a229-ad789063bf88",
        "type": "broadcast.received"
      },
      {
        "from": "cf2497d2-7426-46c4-a229-ad789063bf88",
        "to": "cf2497d2-7426-46c4-a229-ad789063bf88",
        "type": "broadcast.received"
      }
    ]
  },
  "data": {
    "devices": ["*"],
    "payload": {
      "temperature": 87
    }
  }
}

metadata.route

The metadata.route array shows us each hop that happened to get this message delivered to us:

hop-1.json

{
  "from": "188824f0-28c4-475b-ab36-2505402bebcb",
  "to": "cf2497d2-7426-46c4-a229-ad789063bf88",
  "type": "broadcast.sent"
}

The message started it as a broadcast emitted by 1888...

hop-2.json

{
  "from": "188824f0-28c4-475b-ab36-2505402bebcb",
  "to": "cf2497d2-7426-46c4-a229-ad789063bf88",
  "type": "broadcast.received"
}

The message is then forwarded to cf24... by way of cf24...'s broadcast.sent subscription to 1888...

hop-3.json

{
  "from": "cf2497d2-7426-46c4-a229-ad789063bf88",
  "to": "cf2497d2-7426-46c4-a229-ad789063bf88",
  "type": "broadcast.received"
}

Lastly, the message is put into cf24...'s Firehose because of the broadcast.received subscription that cf24... has to itself.

data

The data property contains the raw data of the message that 1888... originally emitted.

data.json

{
  "devices": ["*"],
  "payload": {
    "temperature": 87
  }
}