calejocontrol
/
CalejoControl
1
0
Fork 0
Code Issues Pull Requests 4 Packages Projects Releases Wiki Activity
CalejoControl/README.md

256 lines
9.8 KiB
Markdown
Raw Blame History

# Calejo Control Adapter
**Multi-protocol integration adapter for municipal wastewater pump stations with comprehensive safety and security framework**
[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/docker-ready-blue)](https://www.docker.com/)
## Overview
The Calejo Control Adapter translates optimized pump control plans from Calejo Optimize into real-time control signals for municipal wastewater pump stations. It supports diverse SCADA systems with minimal configuration through automatic discovery and multiple protocol support.
### Implementation Status
✅ **Phase 1**: Core Infrastructure
- Database connection pooling with FlexibleDatabaseClient
- Auto-discovery of pump stations and pumps
- Safety framework with limit enforcement
- Emergency stop management
- Optimization plan management
✅ **Phase 2**: Multi-Protocol Servers
- OPC UA server implementation
- Modbus TCP server implementation
- REST API server implementation
- Database watchdog for failsafe operation
- Alert management system
✅ **Phase 3**: Setpoint Management
- Setpoint Manager for real-time control with three calculator types:
- `DIRECT_SPEED`: Direct speed control
- `LEVEL_CONTROLLED`: Level-based control with feedback
- `POWER_CONTROLLED`: Power-based control with feedback
- Integration with all safety components
- Unified main application
- 15 comprehensive unit tests for SetpointManager
✅ **Phase 4**: Security Layer
- JWT-based authentication with bcrypt password hashing
- Role-based access control (RBAC) with four user roles
- TLS/SSL encryption with certificate management
- Compliance audit logging for IEC 62443, ISO 27001, and NIS2
- 56 comprehensive security tests (24 auth/authz, 17 TLS, 15 audit)
⏳ **Phase 5**: Protocol Servers (Pending)
- Enhanced protocol implementations
- Protocol-specific optimizations
⏳ **Phase 6**: Integration and Testing (Pending)
- End-to-end testing
- Validation with real SCADA systems
⏳ **Phase 7**: Production Hardening (Pending)
- Performance optimization
- Monitoring and alerting
**Current Status**: All 133 tests passing (100% success rate)
**Recent Updates**:
- SetpointManager fully integrated with main application
- Added start/stop methods for SetpointManager
- Fixed configuration settings and database pool parameters
- Updated protocol server initializations
- Verified main application starts and stops gracefully
### Key Features
- **Multi-Protocol Support**: OPC UA, Modbus TCP, and REST API simultaneously
- **Auto-Discovery**: Automatically discovers pump stations and pumps from database
- **Safety Framework**: Multi-layer limits, watchdogs, emergency stop, failsafe mechanisms
- **Security**: Authentication, authorization, encryption, audit logging
- **Compliance**: IEC 62443, NIS2 Directive, ISO 27001
- **High Availability**: Caching, failover, health monitoring
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Calejo Optimize Container (Existing) │
│ - Optimization Engine │
│ - PostgreSQL Database (pump plans) │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Calejo Control Adapter (IMPLEMENTED) │
│ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Core Components: │ │
│ │ 1. Auto-Discovery Module ✅ │ │
│ │ 2. Safety Framework ✅ │ │
│ │ 3. Emergency Stop Manager ✅ │ │
│ │ 4. Optimization Plan Manager ✅ │ │
│ │ 5. Setpoint Manager ✅ │ │
│ │ 6. Database Watchdog ✅ │ │
│ │ 7. Alert Manager ✅ │ │
│ │ 8. Multi-Protocol Server ✅ │ │
│ │ - OPC UA Server │ │
│ │ - Modbus TCP Server │ │
│ │ - REST API │ │
│ └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
↓
(Multiple Protocols)
↓
┌─────────────────┼─────────────────┐
↓ ↓ ↓
Siemens WinCC Schneider EcoStruxure Rockwell FactoryTalk
```
## Project Structure
```
calejo-control-adapter/
├── src/
│ ├── core/
│ │ ├── auto_discovery.py # Auto-discovery module
│ │ ├── safety.py # Safety framework
│ │ ├── emergency_stop.py # Emergency stop manager
│ │ ├── optimization_manager.py # Optimization plan manager
│ │ └── setpoint_manager.py # Setpoint manager
│ ├── protocols/
│ │ ├── opcua_server.py # OPC UA server
│ │ ├── modbus_server.py # Modbus TCP server
│ │ └── rest_api.py # REST API server
│ ├── database/
│ │ ├── flexible_client.py # Flexible database client
│ │ └── models.py # Data models
│ ├── monitoring/
│ │ ├── watchdog.py # Database watchdog
│ │ └── alerts.py # Alert manager
│ └── main.py # Main application
├── tests/
├── config/
│ ├── settings.py # Application settings
│ └── docker-compose.yml # Docker configuration
├── docs/
│ ├── specification.txt # Full implementation specification
│ ├── optimization_plan_management.md # Optimization system documentation
│ └── alert_system_setup.md # Alert system configuration guide
├── requirements.txt # Python dependencies
├── Dockerfile # Docker container definition
└── README.md # This file
```
## Getting Started
### Prerequisites
- Python 3.11+
- PostgreSQL 14+
- Docker (optional)
### Installation
1. **Clone the repository**
```bash
git clone http://95.111.206.201:3000/calejocontrol/CalejoControl.git
cd calejo-control-adapter
```
2. **Install dependencies**
```bash
pip install -r requirements.txt
```
3. **Set up environment variables**
```bash
cp config/.env.example config/.env
# Edit config/.env with your database and security settings
```
4. **Run the application**
```bash
python -m src.main
```
### Docker Deployment
```bash
# Build the container
docker build -t calejo-control-adapter .
# Run the container
docker run -p 8080:8080 -p 4840:4840 -p 502:502 calejo-control-adapter
```
## Configuration
Key configuration options:
- `DATABASE_URL`: PostgreSQL connection string
- `OPC_UA_ENDPOINT`: OPC UA server endpoint (default: opc.tcp://0.0.0.0:4840)
- `MODBUS_PORT`: Modbus TCP port (default: 502)
- `REST_API_PORT`: REST API port (default: 8080)
- `SAFETY_TIMEOUT_SECONDS`: Database watchdog timeout (default: 1200)
### Alert System Configuration
For detailed alert system setup (email, SMS, webhook integration), see:
[Alert System Setup Guide](docs/alert_system_setup.md)
## Safety Framework
The adapter implements a comprehensive three-layer safety architecture:
1. **Layer 1**: Physical Hard Limits (PLC/VFD) - 15-55 Hz
2. **Layer 2**: Station Safety Limits (Database) - 20-50 Hz (enforced by adapter)
3. **Layer 3**: Optimization Constraints (Calejo Optimize) - 25-45 Hz
### Safety Features
- **Hard Operational Limits**: Speed, level, power, and flow limits
- **Rate of Change Limits**: Prevent sudden speed changes
- **Database Watchdog**: Reverts to safe defaults if updates stop
- **Emergency Stop**: Manual override capability
- **Failsafe Mode**: Automatic fallback to default setpoints
## Security & Compliance
- **Authentication**: JWT tokens and certificate-based authentication
- **Authorization**: Role-based access control (RBAC)
- **Encryption**: TLS/SSL for all communications
- **Audit Logging**: Immutable audit trail for compliance
- **Standards**: IEC 62443, ISO 27001, NIS2 Directive
## Development
### Running Tests
```bash
pytest tests/
```
### Code Quality
```bash
flake8 src/ tests/ # Linting
mypy src/ # Type checking
black src/ tests/ # Code formatting
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For support and documentation, refer to the specification in `docs/specification.txt` or contact the development team.
Reference in New Issue View Git Blame Copy Permalink