366 lines
15 KiB
Markdown
366 lines
15 KiB
Markdown
|
# Calejo Control Adapter - System Architecture
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The Calejo Control Adapter is a multi-protocol integration adapter designed for municipal wastewater pump stations. It translates optimized pump control plans from Calejo Optimize into real-time control signals while maintaining comprehensive safety and security compliance.
|
||
|
|
|
||
|
|
**Key Design Principles:**
|
||
|
|
- **Safety First**: Multi-layer safety architecture with failsafe mechanisms
|
||
|
|
- **Security by Design**: Built-in security controls compliant with industrial standards
|
||
|
|
- **Protocol Agnostic**: Support for multiple industrial protocols simultaneously
|
||
|
|
- **High Availability**: Redundant components and health monitoring
|
||
|
|
- **Transparent Operations**: Comprehensive audit logging and monitoring
|
||
|
|
|
||
|
|
## System Architecture
|
||
|
|
|
||
|
|
### High-Level 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
|
||
|
|
```
|
||
|
|
|
||
|
|
## Component Architecture
|
||
|
|
|
||
|
|
### Core Components
|
||
|
|
|
||
|
|
#### 1. Auto-Discovery Module (`src/core/auto_discovery.py`)
|
||
|
|
- **Purpose**: Automatically discovers pump stations and pumps from database
|
||
|
|
- **Features**:
|
||
|
|
- Dynamic discovery of pump configurations
|
||
|
|
- Periodic refresh of station information
|
||
|
|
- Integration with safety framework
|
||
|
|
- **Configuration**: Refresh interval configurable via settings
|
||
|
|
|
||
|
|
#### 2. Safety Framework (`src/core/safety.py`)
|
||
|
|
- **Purpose**: Multi-layer safety enforcement for all setpoints
|
||
|
|
- **Three-Layer Architecture**:
|
||
|
|
- **Layer 1**: Physical Hard Limits (PLC/VFD) - 15-55 Hz
|
||
|
|
- **Layer 2**: Station Safety Limits (Database) - 20-50 Hz (enforced here)
|
||
|
|
- **Layer 3**: Optimization Constraints (Calejo Optimize) - 25-45 Hz
|
||
|
|
- **Features**:
|
||
|
|
- Rate of change limiting
|
||
|
|
- Emergency stop integration
|
||
|
|
- Failsafe mode activation
|
||
|
|
|
||
|
|
#### 3. Emergency Stop Manager (`src/core/emergency_stop.py`)
|
||
|
|
- **Purpose**: Manual override capability for emergency situations
|
||
|
|
- **Features**:
|
||
|
|
- Station-level and pump-level emergency stops
|
||
|
|
- Automatic setpoint override to 0 Hz
|
||
|
|
- Manual reset capability
|
||
|
|
- Audit logging of all emergency operations
|
||
|
|
|
||
|
|
#### 4. Optimization Plan Manager (`src/core/optimization_manager.py`)
|
||
|
|
- **Purpose**: Manages optimization plans from Calejo Optimize
|
||
|
|
- **Features**:
|
||
|
|
- Periodic polling of optimization database
|
||
|
|
- Plan validation and safety checks
|
||
|
|
- Integration with setpoint manager
|
||
|
|
- Plan execution monitoring
|
||
|
|
|
||
|
|
#### 5. Setpoint Manager (`src/core/setpoint_manager.py`)
|
||
|
|
- **Purpose**: Calculates and manages real-time setpoints
|
||
|
|
- **Calculator Types**:
|
||
|
|
- `DIRECT_SPEED`: Direct speed control
|
||
|
|
- `LEVEL_CONTROLLED`: Level-based control with feedback
|
||
|
|
- `POWER_CONTROLLED`: Power-based control with feedback
|
||
|
|
- **Features**:
|
||
|
|
- Real-time setpoint calculation
|
||
|
|
- Integration with safety framework
|
||
|
|
- Performance monitoring
|
||
|
|
|
||
|
|
### Security Components
|
||
|
|
|
||
|
|
#### 6. Security Manager (`src/core/security.py`)
|
||
|
|
- **Purpose**: Unified security management
|
||
|
|
- **Components**:
|
||
|
|
- **Authentication Manager**: JWT-based authentication with bcrypt password hashing
|
||
|
|
- **Authorization Manager**: Role-based access control (RBAC)
|
||
|
|
- **Security Manager**: Coordination of authentication and authorization
|
||
|
|
- **User Roles**:
|
||
|
|
- `READ_ONLY`: Read-only access to system status
|
||
|
|
- `OPERATOR`: Basic operational controls including emergency stop
|
||
|
|
- `ENGINEER`: Configuration and safety limit management
|
||
|
|
- `ADMINISTRATOR`: Full system access including user management
|
||
|
|
|
||
|
|
#### 7. Compliance Audit Logger (`src/core/compliance_audit.py`)
|
||
|
|
- **Purpose**: Comprehensive audit logging for regulatory compliance
|
||
|
|
- **Supported Standards**:
|
||
|
|
- IEC 62443 (Industrial Automation and Control Systems Security)
|
||
|
|
- ISO 27001 (Information Security Management)
|
||
|
|
- NIS2 Directive (Network and Information Systems Security)
|
||
|
|
- **Features**:
|
||
|
|
- Immutable audit trail
|
||
|
|
- Event categorization by severity
|
||
|
|
- Compliance reporting
|
||
|
|
- Database and structured logging
|
||
|
|
|
||
|
|
#### 8. TLS Manager (`src/core/tls_manager.py`)
|
||
|
|
- **Purpose**: Certificate-based encryption management
|
||
|
|
- **Features**:
|
||
|
|
- Certificate generation and rotation
|
||
|
|
- TLS/SSL configuration
|
||
|
|
- Certificate validation
|
||
|
|
- Secure communication channels
|
||
|
|
|
||
|
|
### Protocol Servers
|
||
|
|
|
||
|
|
#### 9. OPC UA Server (`src/protocols/opcua_server.py`)
|
||
|
|
- **Purpose**: Industrial automation protocol support
|
||
|
|
- **Features**:
|
||
|
|
- OPC UA 1.04 compliant server
|
||
|
|
- Node caching for performance
|
||
|
|
- Security policy support
|
||
|
|
- Certificate-based authentication
|
||
|
|
- **Endpoints**: `opc.tcp://0.0.0.0:4840`
|
||
|
|
|
||
|
|
#### 10. Modbus TCP Server (`src/protocols/modbus_server.py`)
|
||
|
|
- **Purpose**: Legacy industrial protocol support
|
||
|
|
- **Features**:
|
||
|
|
- Modbus TCP protocol implementation
|
||
|
|
- Connection pooling
|
||
|
|
- Industrial security features
|
||
|
|
- High-performance data access
|
||
|
|
- **Port**: 502
|
||
|
|
|
||
|
|
#### 11. REST API Server (`src/protocols/rest_api.py`)
|
||
|
|
- **Purpose**: Modern web API for integration
|
||
|
|
- **Features**:
|
||
|
|
- OpenAPI documentation
|
||
|
|
- Response caching
|
||
|
|
- Compression support
|
||
|
|
- Rate limiting
|
||
|
|
- **Port**: 8080
|
||
|
|
|
||
|
|
### Monitoring Components
|
||
|
|
|
||
|
|
#### 12. Database Watchdog (`src/monitoring/watchdog.py`)
|
||
|
|
- **Purpose**: Ensures database connectivity and failsafe operation
|
||
|
|
- **Features**:
|
||
|
|
- Periodic health checks
|
||
|
|
- Automatic failsafe activation
|
||
|
|
- Alert generation on connectivity loss
|
||
|
|
- Graceful degradation
|
||
|
|
|
||
|
|
#### 13. Alert Manager (`src/monitoring/alerts.py`)
|
||
|
|
- **Purpose**: Comprehensive alerting system
|
||
|
|
- **Features**:
|
||
|
|
- Multi-channel notifications (email, SMS, webhook)
|
||
|
|
- Alert escalation
|
||
|
|
- Alert history and management
|
||
|
|
- Integration with audit system
|
||
|
|
|
||
|
|
#### 14. Health Monitor (`src/monitoring/health_monitor.py`)
|
||
|
|
- **Purpose**: System health monitoring and metrics
|
||
|
|
- **Features**:
|
||
|
|
- Component health status
|
||
|
|
- Performance metrics
|
||
|
|
- Resource utilization
|
||
|
|
- External health check endpoints
|
||
|
|
|
||
|
|
## Data Flow Architecture
|
||
|
|
|
||
|
|
### Setpoint Calculation Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
1. Optimization Plan Polling
|
||
|
|
↓
|
||
|
|
2. Plan Validation & Safety Check
|
||
|
|
↓
|
||
|
|
3. Setpoint Calculation
|
||
|
|
↓
|
||
|
|
4. Safety Limit Enforcement
|
||
|
|
↓
|
||
|
|
5. Protocol Server Distribution
|
||
|
|
↓
|
||
|
|
6. SCADA System Integration
|
||
|
|
```
|
||
|
|
|
||
|
|
### Safety Enforcement Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
1. Proposed Setpoint
|
||
|
|
↓
|
||
|
|
2. Emergency Stop Check (Highest Priority)
|
||
|
|
↓
|
||
|
|
3. Hard Limit Enforcement
|
||
|
|
↓
|
||
|
|
4. Rate of Change Limiting
|
||
|
|
↓
|
||
|
|
5. Final Setpoint Validation
|
||
|
|
↓
|
||
|
|
6. Protocol Server Delivery
|
||
|
|
```
|
||
|
|
|
||
|
|
## Security Architecture
|
||
|
|
|
||
|
|
### Authentication & Authorization
|
||
|
|
|
||
|
|
- **JWT-based Authentication**: Secure token-based authentication
|
||
|
|
- **Role-Based Access Control**: Granular permissions per user role
|
||
|
|
- **Certificate Authentication**: For industrial protocol security
|
||
|
|
- **Session Management**: Secure session handling with timeout
|
||
|
|
|
||
|
|
### Encryption & Communication Security
|
||
|
|
|
||
|
|
- **TLS/SSL Encryption**: All external communications
|
||
|
|
- **Certificate Management**: Automated certificate rotation
|
||
|
|
- **Secure Protocols**: Industry-standard security protocols
|
||
|
|
- **Network Segmentation**: Zone-based security model
|
||
|
|
|
||
|
|
### Audit & Compliance
|
||
|
|
|
||
|
|
- **Comprehensive Logging**: All security-relevant events
|
||
|
|
- **Immutable Audit Trail**: Tamper-resistant logging
|
||
|
|
- **Compliance Reporting**: Automated compliance reports
|
||
|
|
- **Security Monitoring**: Real-time security event monitoring
|
||
|
|
|
||
|
|
## Deployment Architecture
|
||
|
|
|
||
|
|
### Container Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────┐
|
||
|
|
│ Calejo Control Adapter Container │
|
||
|
|
│ │
|
||
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||
|
|
│ │ OPC UA Server │ │ Modbus Server │ │
|
||
|
|
│ │ Port: 4840 │ │ Port: 502 │ │
|
||
|
|
│ └─────────────────┘ └─────────────────┘ │
|
||
|
|
│ │
|
||
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||
|
|
│ │ REST API │ │ Health Monitor │ │
|
||
|
|
│ │ Port: 8080 │ │ Port: 8081 │ │
|
||
|
|
│ └─────────────────┘ └─────────────────┘ │
|
||
|
|
│ │
|
||
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
||
|
|
│ │ Core Application Components │ │
|
||
|
|
│ │ - Safety Framework │ │
|
||
|
|
│ │ - Security Layer │ │
|
||
|
|
│ │ - Monitoring & Alerting │ │
|
||
|
|
│ └─────────────────────────────────────────────────┘ │
|
||
|
|
└─────────────────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
### High Availability Features
|
||
|
|
|
||
|
|
- **Database Connection Pooling**: Optimized database connectivity
|
||
|
|
- **Component Health Monitoring**: Continuous health checks
|
||
|
|
- **Graceful Degradation**: Failsafe operation on component failure
|
||
|
|
- **Automatic Recovery**: Self-healing capabilities
|
||
|
|
- **Load Balancing**: Protocol server load distribution
|
||
|
|
|
||
|
|
## Performance & Scalability
|
||
|
|
|
||
|
|
### Performance Characteristics
|
||
|
|
|
||
|
|
- **Setpoint Calculation**: < 100ms per pump
|
||
|
|
- **Protocol Response Time**: < 50ms for OPC UA/Modbus
|
||
|
|
- **Database Operations**: Optimized connection pooling
|
||
|
|
- **Memory Usage**: Efficient caching and resource management
|
||
|
|
|
||
|
|
### Scalability Features
|
||
|
|
|
||
|
|
- **Horizontal Scaling**: Multiple adapter instances
|
||
|
|
- **Load Distribution**: Protocol-specific load balancing
|
||
|
|
- **Resource Optimization**: Dynamic resource allocation
|
||
|
|
- **Performance Monitoring**: Real-time performance metrics
|
||
|
|
|
||
|
|
## Integration Patterns
|
||
|
|
|
||
|
|
### SCADA System Integration
|
||
|
|
|
||
|
|
- **OPC UA Integration**: Standard industrial protocol
|
||
|
|
- **Modbus Integration**: Legacy system compatibility
|
||
|
|
- **REST API Integration**: Modern web services
|
||
|
|
- **Database Integration**: Direct database access
|
||
|
|
|
||
|
|
### External System Integration
|
||
|
|
|
||
|
|
- **Alert Systems**: Email, SMS, webhook integration
|
||
|
|
- **Monitoring Systems**: Health check endpoints
|
||
|
|
- **Security Systems**: Integration with enterprise security
|
||
|
|
- **Compliance Systems**: Audit log export and reporting
|
||
|
|
|
||
|
|
## Configuration Management
|
||
|
|
|
||
|
|
### Configuration Sources
|
||
|
|
|
||
|
|
- **Environment Variables**: Primary configuration method
|
||
|
|
- **Configuration Files**: YAML/JSON configuration support
|
||
|
|
- **Database Configuration**: Dynamic configuration updates
|
||
|
|
- **Runtime Configuration**: Hot-reload capability for certain settings
|
||
|
|
|
||
|
|
### Key Configuration Areas
|
||
|
|
|
||
|
|
- **Database Connection**: Connection strings and pooling
|
||
|
|
- **Safety Limits**: Station and pump-specific safety parameters
|
||
|
|
- **Security Settings**: Authentication and authorization configuration
|
||
|
|
- **Protocol Settings**: Protocol-specific configuration
|
||
|
|
- **Monitoring Settings**: Alert thresholds and monitoring intervals
|
||
|
|
|
||
|
|
## Development & Testing Architecture
|
||
|
|
|
||
|
|
### Testing Framework
|
||
|
|
|
||
|
|
- **Unit Tests**: Component-level testing
|
||
|
|
- **Integration Tests**: Component interaction testing
|
||
|
|
- **End-to-End Tests**: Complete workflow testing
|
||
|
|
- **Deployment Tests**: Production environment validation
|
||
|
|
- **Security Tests**: Security control validation
|
||
|
|
|
||
|
|
### Development Workflow
|
||
|
|
|
||
|
|
- **Code Quality**: Linting, type checking, formatting
|
||
|
|
- **Continuous Integration**: Automated testing pipeline
|
||
|
|
- **Documentation**: Comprehensive documentation generation
|
||
|
|
- **Release Management**: Version control and release process
|
||
|
|
|
||
|
|
## Compliance & Certification
|
||
|
|
|
||
|
|
### Regulatory Compliance
|
||
|
|
|
||
|
|
- **IEC 62443**: Industrial automation security
|
||
|
|
- **ISO 27001**: Information security management
|
||
|
|
- **NIS2 Directive**: Network and information systems security
|
||
|
|
- **Industry Standards**: Water/wastewater industry standards
|
||
|
|
|
||
|
|
### Certification Strategy
|
||
|
|
|
||
|
|
- **Security Certification**: IEC 62443 certification process
|
||
|
|
- **Quality Certification**: ISO 9001 quality management
|
||
|
|
- **Industry Certification**: Water industry-specific certifications
|
||
|
|
- **Continuous Compliance**: Ongoing compliance monitoring
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*This architecture document provides a comprehensive overview of the Calejo Control Adapter system architecture. For detailed implementation specifications, refer to the individual component documentation.*
|