FostromDocs
ON THIS PAGE

Device Communication Protocols

We support multiple protocols for devices to communicate with Fostrom. All protocols require TLS encryption for security. See below for more information.

We support MQTT, MQTT over WebSockets, and HTTP + SSE. Along with that, we developed our own protocol (codenamed Moonlight), which our Device SDKs use.

We highly recommend using one of our Device SDKs to communicate with Fostrom instead of using the protocols directly, in order to avoid implementing the same base functionality. We also have plans to greatly extend the capabilities of our Device SDKs in the future. We have libraries for JavaScript, Python, and Elixir, with plans to implement SDKs in more languages soon. However, feel free to use any protocol if we don't support your language yet. We will always support these protocols in a backwards-compatible manner. See the section Choosing the right protocol for more information.

The API

Fostrom provides a consistent API across all protocols for device communication. The core operations available are:

  • heartbeat - Send a heartbeat to indicate the device is alive
  • send_datapoint - Send telemetry or sensor data to Fostrom
  • send_msg - Send a message to Fostrom. Messages can be used to trigger Actions.

Along with that, each device has a sequential mailbox. The following mailbox-related operations are available:

  • next_mail - Retrieve the next message from the device's mailbox
  • ack_mail - Acknowledge successful message processing (removes from mailbox)
  • reject_mail - Indicate message processing failed (removes from mailbox)
  • requeue_mail - Return message to mailbox for later processing

Each protocol's semantics vary but they provide the same operations and information. Additionally, connecting to Fostrom and closing a connection is protocol-specific.

Connecting and Authenticating

Authentication varies by protocol:

  • HTTP: Device credentials are sent in request headers (X-Fleet-ID, X-Device-ID, X-Device-Secret)
  • MQTT: Credentials are included in the CONNECT packet
  • WebSockets: Protocol-specific Authentication

Choosing the right protocol

The choice of picking the protocol can be made based on:

  • whether you need a persistent connection from the device to Fostrom
  • whether you can open a TCP socket on the device

Many IoT devices run on battery power and it may not be feasible keep them continuously connected to Fostrom. In such cases, we recommend using MQTT with Keep-Alive: 0. Set the Offline Threshold accordingly in the Device's Settings pane on Fostrom. A longer value will help a device to connect less frequently, as it will show as active as long as it connected at least once within the threshold.

If an open connection is valuable (such as to receive mail from Fostrom in realtime), then you should ideally use our Device SDKs, or MQTT with a Keep-Alive of 30 seconds. To keep the MQTT connection from terminating you would need to send heartbeats (which most MQTT clients will do automatically) or another packet within the time window.

Fostrom also supports MQTT over WebSockets, which can be useful if you can't open a TCP socket on the device or can't connect to port 8883. This could be useful for devices that are behind an HTTP-only firewall. You can also use HTTP instead. For HTTP, we support Server-Sent Events to receive notifications of new mail in realtime too.

A note on security

Fostrom currently only supports TLS-based security. All device connections to Fostrom must be made over TLS for all protocols. That means MQTTS, WSS, and HTTPS.

We understand that TLS can be resource-intensive for constrained IoT devices. We're developing lighter-weight security options for resource-limited devices. If current requirements are blocking your use case, contact us to discuss your needs.