iotDashboard/scripts/README.md

MQTT Data Generator

A Python script that simulates realistic environmental sensor data and publishes it to your MQTT broker for testing the IoT Dashboard.

Features

✅ 8 Environmental Metrics: Temperature, Humidity, CO2, Pressure, Light, Noise, PM2.5, VOC
✅ Realistic Patterns: Daily cycles (office hours, night time)
✅ Random Walk: Natural sensor drift and variations
✅ Anomaly Injection: 5% chance of anomalies for testing alerts
✅ Self-Correcting: Values drift back toward optimal ranges (simulates HVAC)
✅ TLS/mTLS Support: Secure connections with certificates

Installation

# Install dependencies
pip install paho-mqtt

# Or using uv
uv pip install paho-mqtt

Quick Start

1. Basic Usage (Localhost, No TLS)

python scripts/mqtt_data_generator.py --device-id office-sensor-01 --interval 5

2. With Specific Metrics

python scripts/mqtt_data_generator.py \
  --device-id lab-sensor \
  --metrics temperature humidity co2 \
  --interval 10

3. With TLS (Port 8883)

python scripts/mqtt_data_generator.py \
  --device-id secure-sensor \
  --broker localhost \
  --port 8883 \
  --tls \
  --ca-cert infrastructure/mosquitto/certs/ca.crt \
  --client-cert path/to/device.crt \
  --client-key path/to/device.key \
  --interval 5

4. Limited Duration (Testing)

# Run for 5 minutes
python scripts/mqtt_data_generator.py \
  --device-id test-sensor \
  --duration 300 \
  --interval 2

Command Line Arguments

Argument	Required	Default	Description
--broker	No	localhost	MQTT broker hostname
--port	No	1883	MQTT broker port (8883 for TLS)
--device-id	Yes	-	Device ID for MQTT topics
--metrics	No	all	Specific metrics to publish
--interval	No	5	Publish interval in seconds
--duration	No	0	Run duration in seconds (0 = infinite)
--tls	No	False	Enable TLS/SSL encryption
--ca-cert	No	-	Path to CA certificate
--client-cert	No	-	Path to client certificate (mTLS)
--client-key	No	-	Path to client private key (mTLS)

Available Metrics

All metrics follow the standards in services/gpt_service/METRICS_REFERENCE.md:

• temperature - Indoor temperature (15-28°C)
• humidity - Relative humidity (20-70%)
• co2 - Carbon dioxide concentration (400-1500 ppm)
• pressure - Atmospheric pressure (1000-1030 hPa)
• light - Illuminance (200-1000 lux)
• noise - Sound level (30-70 dB)
• pm25 - Fine particulate matter (0-50 µg/m³)
• voc - Volatile organic compounds (0-500 ppb)

MQTT Topic Format

Published to standard format: devices/{device_id}/{metric}

Examples:

• devices/office-sensor-01/temperature
• devices/office-sensor-01/humidity
• devices/lab-sensor/co2

Data Patterns

Daily Cycles

• Business hours (9-17): Higher CO2, temperature, noise
• Night time (22-6): Lower light, CO2, noise
• All day: Natural variations within ranges

Realistic Behavior

• Random walk: Small incremental changes
• Self-correcting: HVAC-like drift toward optimal ranges
• Anomalies: 5% chance of spikes/drops for alert testing

Example Values

[14:23:45] Iteration 1
  📊 temperature: 21.34 °C -> devices/office-sensor-01/temperature
  📊 humidity: 45.67 % -> devices/office-sensor-01/humidity
  📊 co2: 678.0 ppm -> devices/office-sensor-01/co2
  📊 pressure: 1015.23 hPa -> devices/office-sensor-01/pressure
  📊 light: 456.0 lux -> devices/office-sensor-01/light
  📊 noise: 42.5 dB -> devices/office-sensor-01/noise
  📊 pm25: 8.3 µg/m³ -> devices/office-sensor-01/pm25
  📊 voc: 120.0 ppb -> devices/office-sensor-01/voc

Multi-Device Simulation

Run multiple instances with different device IDs:

# Terminal 1 - Office sensor
python scripts/mqtt_data_generator.py --device-id office-01 &

# Terminal 2 - Lab sensor
python scripts/mqtt_data_generator.py --device-id lab-01 &

# Terminal 3 - Warehouse sensor
python scripts/mqtt_data_generator.py --device-id warehouse-01 &

Testing Scenarios

Normal Operations

python scripts/mqtt_data_generator.py \
  --device-id normal-sensor \
  --interval 5

High-Frequency Monitoring

python scripts/mqtt_data_generator.py \
  --device-id fast-sensor \
  --interval 1

Limited Metrics (CO2 monitoring)

python scripts/mqtt_data_generator.py \
  --device-id co2-monitor \
  --metrics co2 temperature humidity \
  --interval 10

Integration with IoT Dashboard

1. Register device (if using device_manager):

curl -X POST http://localhost:8000/devices/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Office Sensor","location":"Building A - Floor 2"}'

2. Start data generator with the device ID:

python scripts/mqtt_data_generator.py --device-id <device_id>

3. View in dashboard: Data will appear in the frontend automatically

4. Test AI analysis: Use the AI Insights widget to analyze patterns

Troubleshooting

Connection Refused

• Check MQTT broker is running: docker compose -f infrastructure/compose.yml ps
• Verify port: 1883 (plain) or 8883 (TLS)

TLS Certificate Errors

• Ensure CA certificate path is correct
• For mTLS, verify client cert/key match device registration
• Check certificate hasn't expired

No Data in Dashboard

• Verify mqtt_ingestion service is running
• Check Redis stream: redis-cli XLEN mqtt:ingestion
• Verify db_write service is running
• Check device_id matches registered device

High CPU Usage

• Increase --interval value
• Reduce number of metrics
• Run fewer instances

Performance

• CPU: ~1-2% per instance at 5s interval
• Memory: ~20MB per instance
• Network: ~100 bytes per metric per publish
• Recommended: Max 10 instances on a single machine

Example Output

============================================================
🌡️  MQTT Environmental Sensor Data Generator
============================================================
Device ID: office-sensor-01
Metrics: temperature, humidity, co2, pressure, light, noise, pm25, voc
Interval: 5s
Duration: Infinite
============================================================
✓ Connected to MQTT broker at localhost:1883

[14:23:45] Iteration 1
  📊 temperature: 21.34 °C -> devices/office-sensor-01/temperature
  📊 humidity: 45.67 % -> devices/office-sensor-01/humidity
  📊 co2: 678.0 ppm -> devices/office-sensor-01/co2
  📊 pressure: 1015.23 hPa -> devices/office-sensor-01/pressure
  📊 light: 456.0 lux -> devices/office-sensor-01/light
  📊 noise: 42.5 dB -> devices/office-sensor-01/noise
  📊 pm25: 8.3 µg/m³ -> devices/office-sensor-01/pm25
  📊 voc: 120.0 ppb -> devices/office-sensor-01/voc

[14:23:50] Iteration 2
  ...

Stopping the Generator

• Ctrl+C: Graceful shutdown
• Automatic: If --duration specified

License

Part of the IoT Dashboard project.