171 lines
4.3 KiB
Markdown
171 lines
4.3 KiB
Markdown
# Modbus to MQTT Bridge Service
|
||
|
||
A Python service that reads temperature and humidity data from a Modbus TCP server and publishes the data to an MQTT broker.
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
POE/
|
||
├── config.py # Configuration constants
|
||
├── sensor_bridge.py # Core logic for Modbus and MQTT operations
|
||
├── main.py # Entry point
|
||
├── requirements.txt # Python dependencies
|
||
├── README.md # This file
|
||
├── poe.py # Original single file (backup)
|
||
└── memory-bank/ # Memory bank directory
|
||
```
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### 1. Install Dependencies
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. Configure Settings
|
||
Edit `config.py` to match your environment:
|
||
```python
|
||
# Modbus configuration
|
||
MODBUS_HOST = "10.84.48.153"
|
||
MODBUS_PORT = 505
|
||
|
||
# MQTT configuration
|
||
MQTT_BROKER = "mqtt.service.mesh"
|
||
MQTT_TOPIC = "Temperature_Humidity"
|
||
```
|
||
|
||
### 3. Run the Service
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
## 📊 Features
|
||
|
||
- **Modbus TCP Client**: Reads data from Modbus holding registers
|
||
- **MQTT Publisher**: Publishes sensor data to MQTT broker
|
||
- **Data Processing**: Converts raw sensor values to calibrated readings
|
||
- **Error Handling**: Robust error handling and retry mechanisms
|
||
- **Logging**: Comprehensive logging for monitoring and debugging
|
||
- **Health Check API**: HTTP endpoints for system health monitoring
|
||
- **Sensor Status Tracking**: Real-time tracking of individual sensor health
|
||
- **Alerting System**: Automatic alerts for sensor failures and recovery
|
||
- **Recovery Detection**: Detects when failed sensors come back online
|
||
|
||
## 📈 Data Format
|
||
|
||
The service publishes JSON data to the MQTT topic:
|
||
```json
|
||
{
|
||
"time": "2024-01-15 10:30:25",
|
||
"location": "Office",
|
||
"temperature": 23.5,
|
||
"humidity": 65.2
|
||
}
|
||
```
|
||
|
||
## 🔧 Configuration
|
||
|
||
All configuration is centralized in `config.py`:
|
||
|
||
| Parameter | Description | Default |
|
||
|-----------|-------------|---------|
|
||
| `MODBUS_HOST` | Modbus TCP server IP | "10.84.48.153" |
|
||
| `MODBUS_PORT` | Modbus TCP port | 505 |
|
||
| `MQTT_BROKER` | MQTT broker address | "mqtt.service.mesh" |
|
||
| `MQTT_TOPIC` | MQTT publish topic | "Temperature_Humidity" |
|
||
| `PUBLISH_INTERVAL` | Data publish interval (seconds) | 10 |
|
||
| `LOCATION` | Sensor location identifier | "Office" |
|
||
|
||
## 📡 Sensor Mapping
|
||
|
||
- **Register 0**: Temperature (raw value × 0.1 - 40)
|
||
- **Register 1**: Humidity (raw value × 0.1)
|
||
|
||
## 🏥 Health Check & Monitoring
|
||
|
||
### Health Check Endpoints
|
||
|
||
The service provides HTTP endpoints for monitoring:
|
||
|
||
- **http://localhost:8080/health** - Basic service health check
|
||
- **http://localhost:8080/sensors** - Detailed sensor status information
|
||
|
||
### Alerting System
|
||
|
||
The system automatically sends MQTT alerts for:
|
||
|
||
- **Sensor Failures**: When a sensor fails 3 consecutive times
|
||
- **Sensor Recovery**: When a failed sensor comes back online
|
||
|
||
Alert topics:
|
||
- `sensor-alerts` - Failure and recovery alerts
|
||
- `sensor-status/{location}/status` - Individual sensor status updates
|
||
|
||
### Demo Monitoring Script
|
||
|
||
Use the demo script to test monitoring features:
|
||
|
||
```bash
|
||
# Check health endpoint
|
||
python demo_monitoring.py health
|
||
|
||
# Check sensors status
|
||
python demo_monitoring.py sensors
|
||
|
||
# Monitor system for 5 minutes
|
||
python demo_monitoring.py monitor 300
|
||
```
|
||
|
||
### Configuration Options
|
||
|
||
| Parameter | Description | Default |
|
||
|-----------|-------------|---------|
|
||
| `HEALTH_CHECK_ENABLED` | Enable/disable health check server | True |
|
||
| `HEALTH_CHECK_PORT` | HTTP server port | 8080 |
|
||
| `ALERTING_ENABLED` | Enable/disable MQTT alerts | True |
|
||
| `SENSOR_TIMEOUT_THRESHOLD` | Failures before alert | 3 |
|
||
| `RECOVERY_CONFIRMATION_COUNT` | Successes to confirm recovery | 2 |
|
||
|
||
## 🛠️ Maintenance
|
||
|
||
### Running as a Service
|
||
|
||
For production deployment, consider running as a system service:
|
||
|
||
```bash
|
||
# Example systemd service file
|
||
[Unit]
|
||
Description=Modbus MQTT Bridge
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=pi
|
||
WorkingDirectory=/path/to/POE
|
||
ExecStart=/usr/bin/python3 main.py
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
### Monitoring
|
||
|
||
The service provides comprehensive logging. Monitor the logs for:
|
||
- Connection status
|
||
- Data reading success/failure
|
||
- MQTT publish status
|
||
- Error conditions
|
||
|
||
## 🤝 Contributing
|
||
|
||
1. Fork the repository
|
||
2. Create a feature branch
|
||
3. Make your changes
|
||
4. Test thoroughly
|
||
5. Submit a pull request
|
||
|
||
## 📝 License
|
||
|
||
This project is licensed under the MIT License.
|