192 lines
7.4 KiB
Markdown
192 lines
7.4 KiB
Markdown
# Calejo Control Adapter
|
|
|
|
**Multi-protocol integration adapter for municipal wastewater pump stations with comprehensive safety and security framework**
|
|
|
|
[](https://www.python.org/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](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.
|
|
|
|
### 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 (NEW - TO BE IMPLEMENTED) │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────┐ │
|
|
│ │ Core Components: │ │
|
|
│ │ 1. Auto-Discovery Module │ │
|
|
│ │ 2. Security Layer │ │
|
|
│ │ 3. Safety Framework ⚠️ NEW │ │
|
|
│ │ 4. Plan-to-Setpoint Logic Engine │ │
|
|
│ │ 5. 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
|
|
│ │ ├── security.py # Security layer
|
|
│ │ ├── safety.py # Safety framework
|
|
│ │ └── plan_to_setpoint.py # Plan-to-setpoint logic
|
|
│ ├── protocols/
|
|
│ │ ├── opc_ua_server.py # OPC UA server
|
|
│ │ ├── modbus_server.py # Modbus TCP server
|
|
│ │ └── rest_api.py # REST API server
|
|
│ ├── database/
|
|
│ │ ├── client.py # 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
|
|
├── 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)
|
|
|
|
## 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. |