mirror of
https://github.com/ferdzo/iotDashboard.git
synced 2026-04-05 17:16:26 +00:00
Introduced GPT/AI service, added dashboard widgets, drag and drop, export import.
This commit is contained in:
248
scripts/README.md
Normal file
248
scripts/README.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install paho-mqtt
|
||||
|
||||
# Or using uv
|
||||
uv pip install paho-mqtt
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Basic Usage (Localhost, No TLS)
|
||||
|
||||
```bash
|
||||
python scripts/mqtt_data_generator.py --device-id office-sensor-01 --interval 5
|
||||
```
|
||||
|
||||
### 2. With Specific Metrics
|
||||
|
||||
```bash
|
||||
python scripts/mqtt_data_generator.py \
|
||||
--device-id lab-sensor \
|
||||
--metrics temperature humidity co2 \
|
||||
--interval 10
|
||||
```
|
||||
|
||||
### 3. With TLS (Port 8883)
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
python scripts/mqtt_data_generator.py \
|
||||
--device-id normal-sensor \
|
||||
--interval 5
|
||||
```
|
||||
|
||||
### High-Frequency Monitoring
|
||||
```bash
|
||||
python scripts/mqtt_data_generator.py \
|
||||
--device-id fast-sensor \
|
||||
--interval 1
|
||||
```
|
||||
|
||||
### Limited Metrics (CO2 monitoring)
|
||||
```bash
|
||||
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):
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user