Source-based gateway contract
From Bluetooth collection to acknowledged cloud commit
Based on the current gateway firmware and mobile collector sources. Gateway & Edge keeps collection, local retention, upload, and server acknowledgement separate: a sample is synchronized only when HiveServer accepts the submitted batch.
Scans BLE, identifies the device type, and reads current values or replay history.
Retains every captured sample locally and advances the replay cursor only after storage.
Uploads queued batches when network transport is available and retries failures safely.
Removes data from the pending queue only after the server protocol acknowledges it.
firmware/hivegateway2, firmware/meshgateway, firmware/hivegateway, and apps/hivegateway-maui. The detailed firmware modules, mobile flows, API routes, and installation evidence follow below.Edge interaction model
How the gateway coordinates devices, local storage, and the cloud
The gateway layer exists because real deployments are messy: devices sleep, coverage drops, service staff travel, and uploads do not always happen in the same moment as collection. RoboMeshOS already includes an active mobile gateway architecture that separates collection from upload and preserves data integrity when the environment is unreliable.
BLE advertisements
Gateway scans nearby devices and detects supported sensor families from advertisements.
Connection and replay
For devices that store history, gateway connects and requests replay or delta replay from the last local cursor.
Local persistence
Collected rows are stored locally with replay cursor state, outbox batching, and retry metadata.
Upload transport
Queued data is sent in batches to the backend over the compact binary protocol.
Diagnostics and operator feedback
The app exposes runtime behavior, retry state, and collection context useful during field service.
Detailed runtime sequence
Scan and classify
The gateway listens for BLE advertisements, identifies the device family, and decides whether the current task is passive sampling, service inspection, or backlog recovery.
Connect and request history
If history exists, the gateway enables notifications, requests replay, and resumes from the last known cursor instead of downloading the same data forever.
Store before upload
Downloaded rows are first preserved locally, then converted into pending outbox work. This protects the data path from app restarts, coverage gaps, and temporary backend failures.
Upload and retry
The sender pushes batches to the cloud and tracks success or retry conditions. Upload can be paused, resumed, or delayed without losing the original collected rows.
Gateway interfaces and extension points
BLE edge contracts
New device support usually starts with advertisement recognition, replay characteristic handling, and payload decoding. That is a contained and valuable extension surface.
Persistence and outbox logic
Projects that need stronger offline behavior, exports, or replay auditing can extend the local store, cursor handling, and upload batching without breaking the public app surface.
Transport and diagnostics
Because the upload path is explicit, gateway work is a strong place to add telemetry, observability, service tools, and partner-specific synchronization rules.
Collector pseudocode
This pattern works for smart farming, meter walks, campus servicing, and other field-heavy deployments.
for each advertisement in scan():
if supported(advertisement):
device = resolveDeviceType(advertisement)
cursor = loadReplayCursor(device)
session = connect(device)
rows = replay(session, from=cursor)
storeLocally(rows)
enqueueOutbox(rows)
while internetAvailable():
batch = getOldestPendingBatch()
if not batch: break
upload(batch)
markCommitted(batch)Why different audiences care
User
The user benefits from reliable collection that keeps data flowing even when mobile coverage is poor or visits are infrequent.
Integrator
The integrator benefits from a reusable offline-first field architecture that works across many verticals with only moderate adaptation.
Programmer
The programmer benefits from an explicit runtime model with active code paths already documented in the MAUI gateway repository.
Smart farming and smart metering
Great fit for remote sites, periodic collection, and backlog recovery where devices are near a collector only occasionally.
Smart city, school, and facility deployments
Useful when a mobile service team, maintenance crew, or local device hub needs to bridge isolated sensors into a central cloud without permanent device connectivity.
Offline-first state machine
Connectivity can fail without losing the measurement
Collection, replay, persistence, and upload are separate states. The gateway keeps working in a field, basement, vehicle, or remote site while the cloud is unreachable.
Gateway synchronization loop
The loop advances only after local persistence and server acknowledgement protect the sample.
Discover
Scan BLE advertisements, identify device family, RSSI, live payload, and replay capability.
Recover
Connect when needed and request history after the last confirmed device cursor.
Journal
Store samples locally, create an outbox batch, and preserve retry metadata.
Commit
Upload framed records through TLS and clear the batch only after success.
Radio adapter
Device recognition and replay are isolated from cloud transport.
Durable outbox
Queued rows survive process restarts and temporary network loss.
Diagnostics
Operators can distinguish discovery, device replay, local queue, and upload failures.
Example field session
Live collection continues while connectivity drops; queued records drain after recovery.