Edge Telemetry Collector Daemon

A Dockerized, independently deployable service for a plant gateway VM. It polls mapped tags over the configured field protocol, authenticates to the MaximaLabs ingestion API with a revocable ingest key, and is built for unattended field deployment — reconnect with capped backoff, and store-and-forward so a network outage never loses a reading.

• OPC-UA, Modbus TCP, EtherNet/IP, MQTT, or Sparkplug B — swapping the source swaps only the protocol driver; the durable pipeline underneath is identical.
• MQTT / Sparkplug B — publish-subscribe rather than poll: the collector subscribes once and caches whatever arrives, so a brownfield IIoT gateway feeds the same durable pipeline as an OPC-UA site.
• Store-and-forward — unreachable API → append to a capped local JSONL disk buffer, oldest dropped; flushed oldest-first on the next success.
• One outbound connection — TLS + X-API-Key to the cloud twin; nothing inbound to the plant network.

python -m flowsim.twin.collector           # run continuously
python -m flowsim.twin.collector --once     # single poll cycle

1. Mint an ingest key — in the app, open a simulation's Twin panel → Ingest keys → Create. Copy the fsk_live_… key shown once; it authorizes writes to that simulation only and can be revoked anytime.
2. Configure — copy flowsim/twin/.env.example to .env and set FLOWSIM_API, FLOWSIM_SIM_ID, FLOWSIM_INGEST_KEY, and a TAG_MAP (comma-separated FlowSimTag=protocol-address pairs — e.g. for OPC-UA: TI-101=ns=2;s=Feed.Temperature). Set SOURCE to opcua (default), modbus, ethernetip, mqtt, or sparkplug to pick the protocol.
3. MQTT / Sparkplug B only — set MQTT_HOST (+ optional MQTT_PORT, MQTT_TLS, MQTT_USERNAME/ MQTT_PASSWORD). Plain mqtt maps each FlowSimTag to a topic (TI-101=plant/unit1/ti101); each topic carries a bare number or JSON with a "value" key. sparkplug instead maps each tag to a Sparkplug metric name (TI-101=Temperature) and needs SPARKPLUG_GROUP_ID + SPARKPLUG_EDGE_NODE_ID (optional SPARKPLUG_DEVICE_ID) — one Sparkplug message carries many named metrics on a single topic, unlike plain MQTT's one-topic-per-tag.
4. Run it:

   docker compose -f flowsim/twin/docker-compose.collector.yml up -d --build
   docker compose -f flowsim/twin/docker-compose.collector.yml logs -f

   The buffer is a named volume, so it survives restarts. No published registry image — the compose file builds it locally from the bundled Dockerfile.
5. Map the ingested tags — back in the Twin panel, map each FlowSimTag from your TAG_MAP to the flowsheet location (stream field or unit metric) it represents, via the labeled dropdown of converged variables — this is the "telemetry mapping" step, done in-app rather than a separate config file.