EdgeTwin - Factory Motor Telemetry Dashboard

EdgeTwin is a real-time factory telemetry monitoring system that demonstrates edge computing patterns. Simulated factory motors publish MQTT telemetry, FairCom Edge ingests and stores it, and a React dashboard provides monitoring and alerts.

Features

• 20 Simulated Motors - MQTT telemetry publisher with realistic data patterns
• FairCom Edge Integration - Native MQTT-to-DB ingestion and JSON DB API
• FastAPI Backend - REST API for devices, telemetry, and alerts
• React Dashboard - Real-time overview, device details with charts, and alert management
• Fault Injection - Demo scenarios for overheat and offline alerts

Architecture

Simulator → MQTT → FairCom Edge (ingest/store) → Edge DB → FastAPI → React Dashboard

Key principle: The backend does NOT subscribe to MQTT. Edge handles MQTT ingestion natively; the backend only queries via HTTP.

Services

Service	Port	Description
edge	8080, 1883	FairCom Edge (JSON DB API + MQTT broker)
api	8000	FastAPI backend
web	3000	React dashboard (nginx)
simulator	-	MQTT telemetry publisher

Quickstart

Prerequisites

• Docker and Docker Compose
• FairCom Edge Developer Edition (Linux ARM64)

FairCom Edge Setup

FairCom Edge is a proprietary database platform and must be obtained separately:

1. Download FairCom Edge Developer Edition from FairCom
2. Extract to extra/vendor/faircom-edge/extracted/

See edge/README.md for detailed setup instructions.

Run with Docker Compose

# Start all services
docker compose up --build

# Or run in detached mode
docker compose up -d --build

# View logs
docker compose logs -f

# Stop all services
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v

Open http://localhost:3000 to view the dashboard.

Environment Variables

Variable	Default	Description
WEB_PORT	3000	Web dashboard port
API_PORT	8000	Backend API port
EDGE_HTTP_PORT	8080	FairCom Edge HTTP API port
EDGE_MQTT_PORT	1883	FairCom Edge MQTT broker port
DEVICE_COUNT	20	Number of simulated motors
HEARTBEAT_TIMEOUT_SEC	20	Seconds before device marked offline
FAULT_OVERHEAT_DEVICE	motor-007	Device to simulate overheating
FAULT_DROPOUT_DEVICE	motor-014	Device to simulate going offline

Fault Injection

By default, fault injection is enabled for demo purposes:

• motor-007 will overheat (temperature rises to 85-95°C)
• motor-014 will go offline (stops publishing telemetry after 10s)

To disable faults or change devices:

# Disable all faults
FAULT_OVERHEAT_DEVICE= FAULT_DROPOUT_DEVICE= docker compose up

# Custom fault devices
FAULT_OVERHEAT_DEVICE=motor-005 FAULT_DROPOUT_DEVICE=motor-010 docker compose up

Demo Scenarios

Out of the box, two alerts will activate shortly after starting:

1. Overheat Alert (motor-007) - Temperature rises above 80°C for 3+ readings, triggering a WARN alert. The Overview will show motor-007 in ERROR state with elevated temperature.

2. Heartbeat Missing (motor-014) - Device stops publishing telemetry after ~10 seconds. After 20 seconds of silence, a CRITICAL alert triggers. The Overview will show motor-014 as OFFLINE.

Project Structure

EdgeTwin/
├── api/                        # FastAPI backend
│   ├── src/edgetwin_api/
│   │   ├── main.py             # Application entry point
│   │   ├── settings.py         # Configuration
│   │   ├── routes/             # API endpoints
│   │   │   ├── devices.py
│   │   │   ├── telemetry.py
│   │   │   └── alerts.py
│   │   ├── services/           # Business logic
│   │   │   ├── faircom_client.py
│   │   │   ├── telemetry_service.py
│   │   │   ├── device_state_service.py
│   │   │   ├── alerts_service.py
│   │   │   └── alert_engine.py
│   │   ├── models/             # Pydantic schemas
│   │   └── utils/              # Helpers
│   ├── Dockerfile
│   └── requirements.txt
├── web/                        # React dashboard
│   ├── src/
│   │   ├── App.tsx             # Main app with routing
│   │   ├── pages/              # Route pages
│   │   │   ├── Overview.tsx
│   │   │   ├── DeviceDetail.tsx
│   │   │   └── Alerts.tsx
│   │   ├── components/         # Reusable components
│   │   │   ├── DeviceTable.tsx
│   │   │   ├── TelemetryChart.tsx
│   │   │   └── AlertList.tsx
│   │   └── api/                # API client
│   │       └── client.ts
│   ├── Dockerfile
│   └── package.json
├── simulator/                  # MQTT telemetry simulator
│   ├── src/
│   │   ├── main.py             # Entry point
│   │   ├── motor.py            # Motor simulation
│   │   ├── publisher.py        # MQTT publishing
│   │   └── config.py           # Configuration
│   ├── Dockerfile
│   └── requirements.txt
├── edge/                       # FairCom Edge configuration
│   ├── Dockerfile
│   ├── README.md               # Edge setup instructions
│   ├── entrypoint.sh
│   └── services.json
├── docs/                       # Documentation
│   └── api.md                  # API specification
├── docker-compose.yml
└── README.md

API Endpoints

Endpoint	Description
GET /health	Health check
GET /devices	List all devices with status
GET /telemetry	Query telemetry events (paginated)
GET /telemetry/aggregate	Minute-bucketed aggregates for charts
GET /alerts	List alerts with filtering

See docs/api.md for complete API specification.

Development

For local development, use Docker Compose which handles all service dependencies:

docker compose up --build

Tech Stack

• Backend: Python 3.11, FastAPI, httpx, Pydantic
• Frontend: React 18, TypeScript, Vite, Recharts, React Router
• Database: FairCom Edge (JSON DB API)
• Messaging: MQTT (paho-mqtt)
• Infrastructure: Docker, nginx

License

MIT