Data sources and protocols

mag-dash supports several ways to ingest data. This page explains each option and documents browser/security constraints.

Local file (JSON Lines)

  • Choose a file via the browser file picker.

  • Format: one JSON object per line, e.g.

    { "ts": "26 Oct 2025 14:20:00", "x": 123.456, "y": -78.9, "z": 5.0 }

  • Header lines can be skipped via the UI.

  • Works fully offline.

WebSocket (JSON Lines over text frames)

  • Enter a ws:// or wss:// URL.

  • The server should send one JSON object per line in text frames.

  • Cross‑origin WebSockets are usually allowed by browsers, but your server may restrict the Origin header. Configure an allowlist as needed.

  • Mixed content rules apply: when the dashboard is served over https://, the browser blocks ws:// (insecure). Use wss://.

MQTT over WebSocket

  • Enter a broker WebSocket URL (e.g., ws://localhost:9001 or wss://mqtt.example.com:443/mqtt).

  • You can specify username/password when required by the broker.

  • The UI uses a vendored ESM bundle that provides mqtt.connect(...).

  • Broker requirements:

    • WebSocket (ws or wss) must be enabled on the broker.

    • When internet‑facing, configure allowed Origins.

    • On https:// pages, use wss:// to avoid mixed content.

Topics

  • Provide a topic filter (e.g., sensors/mag/#).

  • Messages should be text payloads containing a single JSON object per message (same schema as above).

Schema

  • Expected keys: ts (UTC timestamp string), x, y, z (numbers in nT).

  • Values are displayed with three decimals; additional properties are preserved in the history table but not charted.