Quickstart -> Messages

Now that we have the action setup, let's send a message from the drone. This will trigger our action, and queue a message for one of the gates. We'll then receive and process the resulting message on the gate controller device.

Sending Messages

Sending messages is nearly the same as sending datapoints. The only difference is in the URL.

Let's say that one of the drones finds out that some animals are in the wrong zone. They are in Zone B, but instead should be in Zone A by now. The drone can send the following message then:

curl https://device.fostrom.dev/v1/msg/detected-incorrect-zone \
  -XPOST \
  -d '{"zone": "b", "open_gate": true, "n_animals_in_fov": 7}' \
  -H 'Content-Type: application/json' \
  -H 'X-Fleet-ID: <your-fleet-id>' \
  -H 'X-Device-ID: <your-device-id>' \
  -H 'X-Device-Secret: <your-device-secret>'

You should get the following response:

{"ok": true}

The action we setup in the previous step should execute shortly, queuing a message into the mailbox of zone-b-large-gate based on the logic we wrote. The gate controller can then fetch the message and process it to open the gate.

Receiving Messages

Messages arriving from Fostrom are queued in a device mailbox. Each device has its own independent sequential mailbox which it can process at its own pace. This ensures that a device cannot get overwhelmed in case something else goes wrong, and can rely on general ordering of events in its own mailbox.

Messages are pushed automatically when using MQTT and if there's no pending message waiting to be acknowledged. Messages can also be fetched manually at any time. When using HTTP, we'll simply fetch the next message from the mailbox.

A note on polling: If you do want to use HTTP to communicate with Fostrom, you do not need to poll the mailbox. Instead, you should periodically send a heartbeat to indicate the device is active and functioning correctly. In the response, a header called X-Messages-Available: true | false is always present. Process that and fetch the next message when required.

To receive a message:

curl https://device.fostrom.dev/v1/mailbox/next \
  -XGET \
  -H 'X-Fleet-ID: <your-fleet-id>' \
  -H 'X-Device-ID: <your-device-id>' \
  -H 'X-Device-Secret: <your-device-secret>'

You should get the following response:

{
  "msg_id": "<some-msg-id>",
  "name": "set-gate-state",
  "payload": {
    "zone": "b",
    "open_gate": true,
    "priority": 1
  }
}

The device can then proceed to open the gate. Once its done though, it needs to acknowledge this message as received. Only then can the device fetch the next message from the mailbox (if any). Remember that the mailbox can only be processed sequentially by the device.

To acknowledge the message, replace the <msg-id> below with the msg_id provided by Fostrom:

curl https://device.fostrom.dev/v1/mailbox/ack/<msg-id> \
  -XPUT \
  -H 'X-Fleet-ID: <your-fleet-id>' \
  -H 'X-Device-ID: <your-device-id>' \
  -H 'X-Device-Secret: <your-device-secret>'

You should get the following response:

{"ok": true}

Now whenever you fetch the next message, you'll get a new message or no message if the mailbox is empty. If you were to try to fetch the next message without acknowledging, you'll get the same message. A good idea is to keep a short list of recently processed messages and use the msg_id is an idempotency key to avoid reprocessing messages.

Next up, we'll review everything we've setup so far, and outline further steps.