NEXUS | Critical Infrastructure Intelligence Platform v2.0.0

Broker Connection

Host localhost

Port 1883

WebSocket Port 9001

Username nexus

Password ••••••••••••••

Auth Username/Password Required

⚡ Event Processing Pipeline

🔌 MQTT Broker

→

📥 MQTT Bridge

→

✅ Schema Validation

→

💾 DB Ingestion

→

🤖 Anomaly Detection

→

🚨 Alert Generation

→

📧 Notifications

📡 Topics

SUB sensors/+ Sensor event ingestion (wildcard: device_id) ▼

The NEXUS API subscribes to sensors/+ where + is a single-level wildcard matching any device_id. Publish events to sensors/{device_id} to trigger the full detection pipeline.

Property	Value
Direction	Publisher → Broker → NEXUS Subscriber
QoS	0 (At most once) — recommended for high-frequency sensor data
Retain	false
Topic Pattern	`sensors/{device_id}`
Payload Format	JSON (UTF-8)
Max Payload	256 KB

SensorEventIn — Payload Schema

{ "event_id": string REQUIRED // Immutable external event ID "source": string optional // Default: "slink" "device_id": string REQUIRED // Sensor device identifier "device_type": enum REQUIRED // camera|vibration|intrusion|fiber_das|thermal|radar|other "timestamp": datetimeREQUIRED // ISO 8601 (e.g. 2026-03-15T10:30:00Z) "geo": object REQUIRED // GeoLocation (see below) "signal_type": string REQUIRED // e.g. vibration_anomaly, intrusion_detected, heat, flooding "signal_value": float optional // Numeric reading from sensor "confidence": float optional // 0.0–1.0, default 0.5 "device_health": object optional // DeviceHealth (see below) "edge_context": object optional // EdgeContext (see below) "payload_refs": object optional // PayloadRefs (see below) "raw_payload": object optional // Arbitrary additional data }

{ "lat": float REQUIRED // -90.0 to 90.0 "lon": float REQUIRED // -180.0 to 180.0 "rail_segment_id": string optional // Maps to monitored rail segment "km_marker": float optional // Kilometre marker on the route }

{ "status": string optional // OK | DEGRADED | OFFLINE (default: "OK") "battery_pct": float optional // 0–100 battery percentage "last_calibration": datetimeoptional // Last calibration timestamp }

{ "latency_ms": float optional // Edge processing latency "jitter_ms": float optional // Network jitter "inference_flag": bool optional // Edge ML inference result "edge_confidence": float optional // Edge model confidence "edge_processed": bool optional // Was this pre-processed at edge? "edge_timestamp": datetimeoptional // When edge processing occurred }

{ "snapshot_url": string optional // URL to camera snapshot "clip_url": string optional // URL to video clip }

▶ Try It — Publish Test Event

Topic: sensors/TEST-DEVICE-001

SUB nexus/health/+ Device health heartbeats (wildcard: device_id) ▼

Device health monitoring topic. Sensors publish periodic heartbeats to nexus/health/{device_id}. The NEXUS bridge logs these for connectivity tracking.

Property	Value
Direction	Device → Broker → NEXUS Subscriber
QoS	0
Retain	true (recommended for last-known-good state)
Topic Pattern	`nexus/health/{device_id}`
Payload Format	JSON (UTF-8)

Device Health — Payload Schema

{ "device_id": string REQUIRED // Device identifier "status": string optional // OK | DEGRADED | OFFLINE "battery_pct": float optional // Battery level 0–100 "uptime_hours": float optional // Hours since last reboot "firmware": string optional // Firmware version "timestamp": datetime optional // ISO 8601 }

▶ Try It — Publish Health Heartbeat

Topic: nexus/health/TEST-DEVICE-001

PUB nexus/alerts/{severity} System-generated alert notifications (outbound) ▼

When the anomaly detection pipeline generates an alert, the system publishes it to MQTT for external consumers (SCADA, dashboards, mobile apps). Subscribe to receive real-time alerts.

Property	Value
Direction	NEXUS Engine → Broker → External Subscribers
QoS	1 (At least once)
Topic Pattern	`nexus/alerts/{critical\|high\|medium\|low}`
Payload Format	JSON (UTF-8)

Alert Notification — Payload Schema

{ "alert_id": uuid // Unique alert identifier "threat_category": string // SECURITY | ENVIRONMENTAL | SAFETY | OPERATIONAL "threat_type": string // e.g. intrusion_detected, flooding, signal_failure "severity": string // critical | high | medium | low "confidence": float // 0.0–1.0 "location": string // Human-readable location "geo_lat": float // Latitude "geo_lon": float // Longitude "recommended_actions": array // AI-generated action items "owner_queue": string // security_ops | engineering_maintenance | ops_planning | control_room "created_at": datetime // ISO 8601 }

📋 Signal Types Reference

Supported signal_type values and their threat categories

signal_type	Category	Description	Example device_type
`intrusion_detected`	SECURITY	Unauthorized access detected	intrusion, camera
`cable_removal`	SECURITY	Cable theft / removal detected	vibration, fiber_das
`tampering`	SECURITY	Equipment tampering	vibration, intrusion
`vandalism`	SECURITY	Vandalism detected	camera, vibration
`flooding`	ENVIRONMENTAL	Flood risk detected	vibration, other
`vegetation`	ENVIRONMENTAL	Vegetation encroachment	camera, radar
`landslide`	ENVIRONMENTAL	Ground movement / landslide	vibration, radar
`heat`	SAFETY	Overheating / heat anomaly	thermal
`signal_failure`	SAFETY	Signal system failure	other
`vibration_anomaly`	SAFETY	Abnormal vibration patterns	vibration, fiber_das
`fatigue`	SAFETY	Material / structural fatigue detected	strain_gauge, vibration
`track_defect`	OPERATIONAL	Track infrastructure defect	vibration, radar
`power_anomaly`	OPERATIONAL	Power supply anomaly	other

🔧 Device Types

camera📷 CCTV

vibration📳 Sensors

intrusion🚧 Perimeter

fiber_das🔌 Fiber Optic

thermal🌡️ Thermal

radar📡 Radar

other⚙️ Generic

💻 Code Examples

# pip install paho-mqtt import json, paho.mqtt.client as mqtt client = mqtt.Client() client.username_pw_set("nexus", "nexus_mqtt_2026") client.connect("localhost", 1883) event = { "event_id": "py-001", "device_id": "VIB-LONDON-001", "device_type": "vibration", "timestamp": "2026-03-15T12:00:00Z", "geo": {"lat": 51.505, "lon": -0.085}, "signal_type": "vibration_anomaly", "signal_value": 0.92, "confidence": 0.85 } client.publish("sensors/VIB-LONDON-001", json.dumps(event))

// npm install mqtt const mqtt = require('mqtt'); const client = mqtt.connect('mqtt://localhost:1883', { username: 'nexus', password: 'nexus_mqtt_2026' }); client.on('connect', () => { const event = { event_id: 'js-001', device_id: 'VIB-LONDON-001', device_type: 'vibration', timestamp: '2026-03-15T12:00:00Z', geo: { lat: 51.505, lon: -0.085 }, signal_type: 'vibration_anomaly', signal_value: 0.92, confidence: 0.85 }; client.publish('sensors/VIB-LONDON-001', JSON.stringify(event)); });

# Using mosquitto_pub CLI mosquitto_pub \ -h localhost \ -p 1883 \ -u nexus \ -P nexus_mqtt_2026 \ -t "sensors/VIB-LONDON-001" \ -m '{"event_id":"cli-001","device_id":"VIB-LONDON-001","device_type":"vibration","timestamp":"2026-03-15T12:00:00Z","geo":{"lat":51.505,"lon":-0.085},"signal_type":"vibration_anomaly","signal_value":0.92,"confidence":0.85}' # Subscribe to all sensor events mosquitto_sub \ -h localhost \ -p 1883 \ -u nexus \ -P nexus_mqtt_2026 \ -t "sensors/#" \ -v

NEXUS | Critical Infrastructure Intelligence Platform v2.0.0 — MQTT API Documentation

REST API (Swagger) · Dashboard · ReDoc

NEXUS MQTT API

Broker Connection

▶ Try It — Publish Test Event

▶ Try It — Publish Health Heartbeat