7.7 KiB

Raw Blame History

Calejo Control Adapter

Multi-protocol integration adapter for municipal wastewater pump stations with comprehensive safety and security framework

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
│   ├── 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

Clone the repository

git clone http://95.111.206.201:3000/calejocontrol/CalejoControl.git
cd calejo-control-adapter

Install dependencies
```
pip install -r requirements.txt
```

Set up environment variables

cp config/.env.example config/.env
# Edit config/.env with your database and security settings

Run the application
```
python -m src.main
```

Docker Deployment

# 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

Safety Framework

The adapter implements a comprehensive three-layer safety architecture:

Layer 1: Physical Hard Limits (PLC/VFD) - 15-55 Hz
Layer 2: Station Safety Limits (Database) - 20-50 Hz (enforced by adapter)
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

pytest tests/

Code Quality

flake8 src/ tests/          # Linting
mypy src/                   # Type checking
black src/ tests/           # Code formatting

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
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.

7.7 KiB Raw Blame History