Overview

This project monitors machine telemetry over MQTT and writes threshold-based alerts to MongoDB and Telegram for PredGuard, ProdGuard, and EcoGuard.

Setup

1. Create and activate the virtual environment.

   python3 -m venv .venv
   source .venv/bin/activate
   

2. Install dependencies.

   pip install -r mqtt_monitor/requirements.txt
   

3. Configure required environment variables. These must be set (either in a .env file or your shell environment):

   Variable	Description
   TELEGRAM_BOT_TOKEN	Telegram bot token
   TELEGRAM_CHAT_ID	Telegram chat or channel ID
   MONGODB_USERNAME	MongoDB username
   MONGODB_PASSWORD	MongoDB password
   MONGODB_HOST	MongoDB host address
   MONGODB_PORT	MongoDB port
   MONGODB_DATABASE	MongoDB database name
   MONGODB_PRODGUARD_COLLECTION	MongoDB collection name for ProdGuard machine documents (optional, default: machines)
   MONGODB_PREDGUARD_THRESHOLDS_COLLECTION	MongoDB thresholds collection name for PredGuard (optional, default: predguard_thresholds)
   MONGODB_PREDGUARD_ALERTS_COLLECTION	MongoDB alerts collection name for PredGuard (optional, default: predguard_alerts)
   MONGODB_ECOGUARD_THRESHOLDS_COLLECTION	MongoDB thresholds collection name for EcoGuard (optional, default: ecoguard_thresholds)
   MONGODB_ECOGUARD_ALERTS_COLLECTION	MongoDB alerts collection name for EcoGuard (optional, default: ecoguard_alerts)
   MQTT_BROKER	MQTT broker address
   MQTT_PORT	MQTT broker port

   Example .env file:

   TELEGRAM_BOT_TOKEN=your-bot-token
   TELEGRAM_CHAT_ID=1003842777960
   TELEGRAM_CHAT_IDS=
   MONGODB_USERNAME=your-mongodb-username
   MONGODB_PASSWORD=your-mongodb-password
   MONGODB_HOST=your-mongodb-host
   MONGODB_PORT=your-mongodb-port
   MONGODB_DATABASE=your-mongodb-database
   MONGODB_PRODGUARD_COLLECTION=machines
   MONGODB_PREDGUARD_THRESHOLDS_COLLECTION=predguard_thresholds
   MONGODB_PREDGUARD_ALERTS_COLLECTION=predguard_alerts
   MONGODB_ECOGUARD_THRESHOLDS_COLLECTION=ecoguard_thresholds
   MONGODB_ECOGUARD_ALERTS_COLLECTION=ecoguard_alerts
   MONGODB_EXTRA_ADDRESSES=
   MONGO_REFRESH_INTERVAL_SECONDS=5
   MQTT_BROKER=your-mqtt-broker
   MQTT_PORT=your-mqtt-port
   

How to Get Your Telegram Chat or Channel ID

To obtain your Telegram chat ID, open Telegram and search for @userinfobot. Start a chat with the bot, and it will send your chat ID to you automatically. For a channel, add the bot to the channel and use the channel ID (example: 1003842777960).

4. Review runtime settings in mqtt_monitor/config.py. Update MQTT broker, MongoDB host settings, log level, and threshold ratios for your environment.

Runtime Flow

1. mqtt_monitor/predguard-alarms.py runs PredGuard only. It loads configs from MONGODB_PREDGUARD_THRESHOLDS_COLLECTION and writes alerts to MONGODB_PREDGUARD_ALERTS_COLLECTION.
2. mqtt_monitor/prodguard-alarms.py runs ProdGuard only. It loads configs from MONGODB_PRODGUARD_COLLECTION and monitors three types of production alerts:
   • Short Stop Alerts: Triggered when production stops based on short_stop_topic_conditions
   • Idle Running Alerts (ProdGuard-201): Triggered when cycle_time_cumulative increases but cut_time_cumulative does not (machine spinning but not cutting)
   • Machine Idle Alerts (ProdGuard-201): Triggered when online_time_cumulative increases but cycle_time_cumulative does not (machine powered but not operating) - alerts at 30 minutes and 1 hour
3. mqtt_monitor/ecoguard-alarms.py runs EcoGuard only. It reads ecoguard records with data_name=E_A1 from MONGODB_ECOGUARD_THRESHOLDS_COLLECTION and writes alerts to MONGODB_ECOGUARD_ALERTS_COLLECTION.
4. Each process subscribes to its own MQTT topics returned from MongoDB.
5. Incoming payloads are parsed and evaluated in each process independently.
6. PredGuard and EcoGuard write matching alerts to MongoDB and Telegram, while ProdGuard sends Telegram-only alerts.

For machine documents in MONGODB_PRODGUARD_COLLECTION:

• ProdGuard expects short_stop_duration at the top level
• Reads MQTT production topics/conditions from connection_details[]
• For Idle Running alerts: checks connection_details.selected_keys for cycle_time_cumulative and cut_time_cumulative
• For Machine Idle alerts: checks connection_details.selected_keys for online_time_cumulative and cycle_time_cumulative

Run

Run each process in its own terminal:

python3 mqtt_monitor/predguard-alarms.py
python3 mqtt_monitor/prodguard-alarms.py
python3 mqtt_monitor/ecoguard-alarms.py

Tests

Run unit tests with the project virtual environment:

.venv/bin/python -m unittest discover -s tests -v

Current test coverage includes:

• payload parsing edge cases (tests/test_payload_parser.py)
• guard runtime behavior (tests/test_guard_runtime.py)
• green runtime behavior (tests/test_green_runtime.py)
• production runtime behavior (tests/test_production_runtime.py)
• ProdGuard-201 idle running and machine idle alerts (tests/test_prodguard_201.py)

Note: Running tests with system python3 may fail if dependencies are not installed globally. Use .venv/bin/python for consistent results.

ProdGuard-201 Features

Idle Running Alert

Monitors machines where the spindle is rotating but no cutting operation is happening. This helps minimize inefficient machine operation and production time loss.

Requirements:

• Machine must provide cycle_time_cumulative and cut_time_cumulative data
• These fields must be listed in connection_details.selected_keys
• MQTT broker and topic are read from connection_details.broker and connection_details.topic
• short_stop_duration must be configured at the machine level

Alert Condition:

• cycle_time_cumulative is increasing (machine is running)
• cut_time_cumulative is NOT increasing (no cutting happening)
• Condition persists for the duration of short_stop_duration

Telegram Message Format:

🚨🚨 IQV PRODUCTION ---- BOŞTA ÇALIŞMA UYARISI 🚨🚨
🏢 şirketinizde,
🏭 [Organization Name] organizasyonunuzda bulunan
⚙ [Machine Name] makinesi
[Timestamp] (TR) tarihinden itibaren makineniz devir yapmasına rağmen kesme işlemi gerçekleştirmemektedir.
Makine boşta çalışmaktadır.
Lütfen kontrol ediniz.

Machine Idle (No Activity) Alert

Monitors machines that remain powered on (connected to electricity with control panels active) but do not operate for extended periods.

Requirements:

• Machine must provide online_time_cumulative and cycle_time_cumulative data
• These fields must be listed in connection_details.selected_keys
• MQTT broker and topic are read from connection_details.broker and connection_details.topic

Alert Condition:

• online_time_cumulative is increasing (machine is powered on)
• cycle_time_cumulative is NOT increasing (machine is not operating)
• Alerts are sent at two thresholds: 30 minutes and 1 hour

Telegram Message Format:

🚨🚨 IQV PRODUCTION ---- MAKİNE HAREKETSİZ UYARISI 🚨🚨
🏢 şirketinizde,
🏭 [Organization Name] organizasyonunuzda bulunan
⚙ [Machine Name] makinesi
[Timestamp] (TR) tarihinden itibaren makineniz elektriğe bağlı olmasına rağmen [Duration] boyunca herhangi bir devir hareketi gözlemlenmemektedir.
Makine aktif görünmekte ancak çalışmamaktadır.
Lütfen kontrol ediniz.

Note: Both cumulative values (cycle_time_cumulative, cut_time_cumulative, online_time_cumulative) are monotonically increasing counters that track total time in their respective states.

Project Structure & File Roles

The main logic is in the mqtt_monitor directory. Here is how the files are connected and what they do:

• predguard-alarms.py: PredGuard monitor entry point. Listens to PredGuard MQTT topics, parses payloads, checks PredGuard thresholds, and triggers PredGuard alerts.
• prodguard-alarms.py: ProdGuard monitor entry point and alert logic module. Listens to production MQTT topics, evaluates short-stop conditions, and dispatches ProdGuard alerts.
• ecoguard-alarms.py: EcoGuard monitor entry point. Listens to EcoGuard MQTT topics, checks E_A1 energy thresholds, and dispatches EcoGuard alerts.
• alerts.py: Writes alerts to MongoDB and sends Telegram notifications.
• config.py: Centralizes all configuration and environment variables.
• logging_utils.py: Sets up logging to file and console.
• machine_catalog.py: Fetches machine topics and configuration from MongoDB.
• payload_parser.py: Parses MQTT payloads and extracts numeric values.
• rules.py: Contains threshold rules for warning/critical alerts.
• data/: Stores any local data files used by the application.

How Files Work Together

1. predguard-alarms.py loads PredGuard configs from MongoDB using machine_catalog.py.
2. ecoguard-alarms.py loads EcoGuard configs from MongoDB using machine_catalog.py.
3. prodguard-alarms.py loads ProdGuard configs from MongoDB using machine_catalog.py.
4. Each process subscribes to its own MQTT topics and receives payloads.
5. Guard and green values are parsed by payload_parser.py and checked against thresholds using rules.py.
6. Production values are evaluated by logic in prodguard-alarms.py.
7. Alerts are sent via alerts.py.
8. Logging is handled by logging_utils.py.
9. All settings are managed in config.py.

This modular design ensures separation of concerns and makes the codebase easy to maintain and extend.

Logs

Runtime logs are written to mqtt_monitor/data/monitor.log.