Repository navigation
Packet Lifecycle
This page describes how a sensor reading moves through Loom, from collection on a device to long-term storage.
- A Loom device collects sensor measurements and stores them in the manager's JSON document.
- If Hypnos is used, the document can be timestamped with the real-time clock and saved to the SD card.
- The document is sent out through one of the configured communication paths.
- For LoRa deployments, a node sends data to a hub. Large LoRa payloads are split into fragments and reassembled by the hub.
- For MQTT/MongoDB deployments, the device or hub publishes the complete JSON document to an MQTT broker.
- A backend bridge subscribes to MQTT topics, reshapes incoming JSON when needed, and writes the result to MongoDB Atlas.
Sensors take measurements and package them into the manager's JSON document. Loom stores module data in a contents array.
If the device uses Hypnos, the document can be stamped with a timestamp from the real-time clock and saved to the SD card as a local backup.
The device can publish data directly over MQTT using Loom_MongoDB, or it can send the data over LoRa to a hub that handles the next step.
In LoRa deployments, the node transmits the JSON document to a hub. If the document is too large for one radio frame, it is split into numbered fragments, sent one at a time, and reassembled by the receiver.
The hub receives LoRa fragments and tracks reassembly state per sender address. This prevents fragments from different nodes from being mixed together. After a complete packet is reassembled, the hub can publish it to the MQTT broker.
Mosquitto is the MQTT message broker. Each published message has a topic string. Subscribers register interest in topics, and Mosquitto routes matching messages to them.
Mosquitto operates at QoS 1, so every message is acknowledged by the receiver. If the MQTT bridge goes down and comes back up, Mosquitto redelivers missed messages instead of silently dropping them.
Loom_MongoDB publishes to different topic formats depending on configuration:
- With a project name:
ProjectName/DatabaseName/DeviceNameInstanceNumber - Without a project name:
DatabaseName/DeviceNameInstanceNumber
For example, a WeatherChimes device named Chime with instance 1 may publish to WeatherChimes/Chimes/Chime1.
The MQTT bridge is an always-running backend process that subscribes to incoming Mosquitto messages. When a message arrives, the bridge uses the topic string to determine where the data should be written in MongoDB.
The bridge also reshapes the raw Loom JSON before upload when needed. In particular, sensor data may arrive nested in the manager's contents array, while MongoDB documents are easier to query when key fields such as type, timestamp, and sensor module readings are written in a flatter structure.
On startup, the bridge retries both the Mosquitto and MongoDB connections up to 5 times before giving up. This helps with temporary Docker startup ordering issues.
MongoDB Atlas is the cloud-hosted MongoDB cluster used for long-term storage. MongoDB stores JSON-like documents, which maps naturally to Loom sensor payloads.
The bridge maps MQTT topics to MongoDB destinations according to the backend configuration. In the current Loom topic format, the topic includes the database name and device identifier, and may also include a project name.
Loom's manager stores module readings in a contents array. For easier querying in MongoDB, backends often flatten the data by extracting common fields like type, timestamp, device ID or name, and individual module readings into top-level document fields.
Keep Mosquitto and the MQTT bridge running continuously. If deployed with Docker or another service manager, configure both services to restart automatically.
Start Mosquitto before the bridge when possible. The bridge should still retry its broker and database connections, so temporary startup ordering issues do not cause permanent failure. The bridge retries Mosquitto and MongoDB connections during startup to handle service ordering problems.
Device-side MQTT also retries broker connections. The default retry limit in Loom_MongoDB is 4 unless changed with setMaxRetries().
Loom MQTT publishes use QoS 1 by default. QoS 1 requires acknowledgement from the receiver, which lets the broker redeliver messages if the bridge disconnects and reconnects. This ensures messages are not silently lost.
Do not treat the MQTT broker as permanent storage. Mosquitto helps with delivery reliability during temporary outages, but MongoDB Atlas is the long-term data store.