CalejoControl/docs/PROTOCOL_INTEGRATION.md

# Calejo Control Adapter - Protocol Integration Guide

## Overview

The Calejo Control Adapter supports multiple industrial protocols simultaneously, providing flexible integration options for various SCADA systems and industrial automation platforms.

**Supported Protocols**:
- **OPC UA** (IEC 62541): Modern industrial automation standard
- **Modbus TCP** (RFC 1006): Legacy industrial protocol support
- **REST API**: Modern web services for integration

## OPC UA Integration

### OPC UA Server Configuration

#### Server Endpoints

```python
class OPCUAServer:
    def __init__(self, endpoint: str = "opc.tcp://0.0.0.0:4840"):
        """Initialize OPC UA server with specified endpoint."""
        
    def start(self):
        """Start the OPC UA server."""
        
    def stop(self):
        """Stop the OPC UA server."""
```

#### Security Policies

- **Basic256Sha256**: Standard security policy
- **Aes256Sha256RsaPss**: Enhanced security policy
- **Certificate Authentication**: X.509 certificate support
- **User Token Authentication**: Username/password authentication

### OPC UA Address Space

#### Node Structure

```
Root
├── Objects
│   ├── PumpStations
│   │   ├── Station_001
│   │   │   ├── Pumps
│   │   │   │   ├── Pump_001
│   │   │   │   │   ├── Setpoint (Hz)
│   │   │   │   │   ├── ActualSpeed (Hz)
│   │   │   │   │   ├── Status
│   │   │   │   │   └── SafetyStatus
│   │   │   │   └── Pump_002
│   │   │   └── StationStatus
│   │   └── Station_002
│   ├── Safety
│   │   ├── EmergencyStopStatus
│   │   ├── SafetyLimits
│   │   └── WatchdogStatus
│   └── System
│       ├── HealthStatus
│       ├── PerformanceMetrics
│       └── AuditLog
└── Types
    ├── PumpStationType
    ├── PumpType
    └── SafetyType
```

#### Node Examples

```python
# Pump setpoint node
setpoint_node = server.nodes.objects.add_object(
    f"ns={namespace_index};s=PumpStations.Station_001.Pumps.Pump_001.Setpoint",
    "Setpoint"
)
setpoint_node.set_writable()

# Safety status node
safety_node = server.nodes.objects.add_object(
    f"ns={namespace_index};s=PumpStations.Station_001.Pumps.Pump_001.SafetyStatus",
    "SafetyStatus"
)
```

### OPC UA Data Types

#### Standard Data Types
- **Float**: Setpoints, measurements
- **Boolean**: Status flags, emergency stops
- **String**: Status messages, identifiers
- **DateTime**: Timestamps, event times

#### Custom Data Types
- **PumpStatusType**: Complex pump status structure
- **SafetyLimitType**: Safety limit configuration
- **OptimizationPlanType**: Optimization plan data

### OPC UA Security Configuration

#### Certificate Management

```python
# Load server certificate
server.load_certificate("server_cert.pem")
server.load_private_key("server_key.pem")

# Configure security policies
server.set_security_policy([
    ua.SecurityPolicyType.Basic256Sha256,
    ua.SecurityPolicyType.Aes256Sha256RsaPss
])
```

#### User Authentication

```python
# Configure user authentication
server.set_user_authentication([
    ("operator", "password123"),
    ("engineer", "secure456")
])
```

## Modbus TCP Integration

### Modbus Server Configuration

#### Server Setup

```python
class ModbusServer:
    def __init__(self, host: str = "0.0.0.0", port: int = 502):
        """Initialize Modbus TCP server."""
        
    def start(self):
        """Start the Modbus server."""
        
    def stop(self):
        """Stop the Modbus server."""
```

#### Connection Management

- **Max Connections**: Configurable connection limit
- **Connection Timeout**: Automatic connection cleanup
- **Session Management**: Secure session handling
- **Rate Limiting**: Request throttling

### Modbus Register Mapping

#### Holding Registers (4xxxx)

| Address Range | Description | Data Type | Access |
|---------------|-------------|-----------|---------|
| 40001-40050 | Pump Setpoints | Float32 | Read/Write |
| 40051-40100 | Actual Speeds | Float32 | Read Only |
| 40101-40150 | Safety Limits | Float32 | Read Only |
| 40151-40200 | Status Flags | Int16 | Read Only |

#### Input Registers (3xxxx)

| Address Range | Description | Data Type | Access |
|---------------|-------------|-----------|---------|
| 30001-30050 | System Metrics | Float32 | Read Only |
| 30051-30100 | Performance Data | Float32 | Read Only |
| 30101-30150 | Audit Counters | Int32 | Read Only |

#### Coils (0xxxx)

| Address Range | Description | Access |
|---------------|-------------|---------|
| 00001-00050 | Emergency Stop | Read/Write |
| 00051-00100 | Pump Control | Read/Write |
| 00101-00150 | System Control | Read/Write |

#### Discrete Inputs (1xxxx)

| Address Range | Description | Access |
|---------------|-------------|---------|
| 10001-10050 | Safety Status | Read Only |
| 10051-10100 | System Status | Read Only |
| 10101-10150 | Alarm Status | Read Only |

### Modbus Data Types

#### Standard Data Types
- **16-bit Integer**: Status flags, counters
- **32-bit Float**: Setpoints, measurements
- **Boolean**: Control flags, status bits

#### Data Conversion

```python
def float_to_registers(value: float) -> List[int]:
    """Convert float to two 16-bit registers."""
    # IEEE 754 floating point conversion
    
def registers_to_float(registers: List[int]) -> float:
    """Convert two 16-bit registers to float."""
    # IEEE 754 floating point conversion
```

### Modbus Security Features

#### Connection Security
- **IP Whitelisting**: Source IP validation
- **Command Validation**: Input sanitization
- **Rate Limiting**: Request throttling
- **Session Tracking**: Connection state monitoring

#### Industrial Security
- **Read-Only Access**: Limited write capabilities
- **Command Validation**: Safe command execution
- **Error Handling**: Graceful error responses
- **Logging**: Comprehensive operation logging

## REST API Integration

### API Endpoints

#### Base URL
```
http://localhost:8080/api/v1
```

#### Authentication

```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "operator",
  "password": "password123"
}
```

Response:
```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

#### Pump Management

```http
GET /api/v1/pump-stations
Authorization: Bearer {token}
```

Response:
```json
{
  "stations": [
    {
      "station_id": "station_001",
      "name": "Main Pump Station",
      "pumps": [
        {
          "pump_id": "pump_001",
          "setpoint": 35.5,
          "actual_speed": 34.8,
          "status": "running",
          "safety_status": "normal"
        }
      ]
    }
  ]
}
```

#### Setpoint Control

```http
PUT /api/v1/pump-stations/{station_id}/pumps/{pump_id}/setpoint
Authorization: Bearer {token}
Content-Type: application/json

{
  "setpoint": 40.0,
  "reason": "Optimization adjustment"
}
```

#### Safety Operations

```http
POST /api/v1/pump-stations/{station_id}/emergency-stop
Authorization: Bearer {token}
Content-Type: application/json

{
  "reason": "Emergency situation detected",
  "operator": "operator_001"
}
```

### API Security

#### Authentication & Authorization
- **JWT Tokens**: Stateless authentication
- **Role-Based Access**: Permission enforcement
- **Token Expiry**: Configurable token lifetime
- **Refresh Tokens**: Token renewal mechanism

#### Rate Limiting

```python
# Rate limiting configuration
RATE_LIMITS = {
    "auth": "10/minute",
    "read": "100/minute",
    "write": "30/minute",
    "admin": "5/minute"
}
```

#### Input Validation

```python
from pydantic import BaseModel, validator

class SetpointRequest(BaseModel):
    setpoint: float
    reason: str
    
    @validator('setpoint')
    def validate_setpoint(cls, v):
        if v < 0 or v > 60:
            raise ValueError('Setpoint must be between 0 and 60 Hz')
        return v
```

### OpenAPI Documentation

#### API Documentation
- **Swagger UI**: Interactive API documentation
- **OpenAPI Specification**: Machine-readable API definition
- **Examples**: Comprehensive usage examples
- **Security Schemes**: Authentication documentation

#### API Versioning
- **URL Versioning**: `/api/v1/` prefix
- **Backward Compatibility**: Maintained across versions
- **Deprecation Policy**: Clear deprecation timeline

## Protocol Comparison

### Feature Comparison

| Feature | OPC UA | Modbus TCP | REST API |
|---------|--------|------------|----------|
| **Security** | High | Medium | High |
| **Performance** | High | Very High | Medium |
| **Complexity** | High | Low | Medium |
| **Interoperability** | High | Medium | Very High |
| **Real-time** | Yes | Yes | Limited |
| **Discovery** | Yes | No | Yes |

### Use Case Recommendations

#### OPC UA Recommended For:
- Modern SCADA systems
- Complex data structures
- High security requirements
- Enterprise integration

#### Modbus TCP Recommended For:
- Legacy SCADA systems
- Simple data exchange
- High-performance requirements
- Industrial networks

#### REST API Recommended For:
- Web applications
- Mobile applications
- Enterprise integration
- Third-party systems

## Integration Patterns

### Multi-Protocol Architecture

```
┌─────────────────────────────────────────────────────────┐
│  Calejo Control Adapter                                 │
│                                                          │
│  ┌─────────────────┐  ┌─────────────────┐               │
│  │  OPC UA Server  │  │  Modbus Server  │               │
│  │  Port: 4840     │  │  Port: 502      │               │
│  └─────────────────┘  └─────────────────┘               │
│                                                          │
│  ┌─────────────────┐                                    │
│  │  REST API       │                                    │
│  │  Port: 8080     │                                    │
│  └─────────────────┘                                    │
│                                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │  Core Application                               │    │
│  │  - Safety Framework                             │    │
│  │  - Setpoint Management                          │    │
│  │  - Data Synchronization                         │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
```

### Data Synchronization

#### Real-time Data Flow

```python
class ProtocolDataSync:
    def __init__(self):
        self.data_cache = {}
        self.protocol_servers = []
    
    def update_setpoint(self, station_id: str, pump_id: str, setpoint: float):
        """Update setpoint across all protocol servers."""
        # Update internal cache
        self.data_cache[f"{station_id}.{pump_id}.setpoint"] = setpoint
        
        # Propagate to all protocol servers
        for server in self.protocol_servers:
            server.update_setpoint(station_id, pump_id, setpoint)
```

#### Consistency Guarantees

- **Atomic Updates**: All-or-nothing updates
- **Order Preservation**: Sequential update processing
- **Conflict Resolution**: Last-write-wins strategy
- **Error Handling**: Graceful failure recovery

### Performance Optimization

#### Caching Strategy

```python
class ProtocolCache:
    def __init__(self):
        self.setpoint_cache = {}
        self.status_cache = {}
        self.cache_ttl = 60  # seconds
    
    def get_setpoint(self, station_id: str, pump_id: str) -> Optional[float]:
        """Get cached setpoint value."""
        key = f"{station_id}.{pump_id}"
        if key in self.setpoint_cache:
            cached_value, timestamp = self.setpoint_cache[key]
            if time.time() - timestamp < self.cache_ttl:
                return cached_value
        return None
```

#### Connection Pooling

```python
class ConnectionPool:
    def __init__(self, max_connections: int = 100):
        self.max_connections = max_connections
        self.active_connections = 0
        self.connection_pool = []
```

## Configuration Examples

### OPC UA Configuration

```yaml
opcua:
  endpoint: "opc.tcp://0.0.0.0:4840"
  security_policies:
    - "Basic256Sha256"
    - "Aes256Sha256RsaPss"
  certificate:
    server_cert: "/path/to/server_cert.pem"
    server_key: "/path/to/server_key.pem"
  users:
    - username: "operator"
      password: "${OPCUA_OPERATOR_PASSWORD}"
    - username: "engineer"
      password: "${OPCUA_ENGINEER_PASSWORD}"
```

### Modbus Configuration

```yaml
modbus:
  host: "0.0.0.0"
  port: 502
  max_connections: 100
  connection_timeout: 30
  security:
    allowed_ips:
      - "192.168.1.0/24"
      - "10.0.0.0/8"
    rate_limit: 1000  # requests per minute
```

### REST API Configuration

```yaml
rest_api:
  host: "0.0.0.0"
  port: 8080
  cors_origins:
    - "https://dashboard.calejo.com"
    - "https://admin.calejo.com"
  rate_limits:
    auth: "10/minute"
    read: "100/minute"
    write: "30/minute"
  security:
    jwt_secret: "${JWT_SECRET_KEY}"
    token_expire_minutes: 60
```

## Troubleshooting

### Common Issues

#### OPC UA Connection Issues
- **Certificate Problems**: Verify certificate validity
- **Security Policy Mismatch**: Check client-server compatibility
- **Firewall Blocking**: Verify port 4840 accessibility

#### Modbus Communication Issues
- **Network Connectivity**: Verify TCP connectivity
- **Register Mapping**: Check address mapping consistency
- **Data Type Mismatch**: Verify data type compatibility

#### REST API Issues
- **Authentication Failures**: Check token validity
- **Rate Limiting**: Monitor request frequency
- **Input Validation**: Verify request payload format

### Diagnostic Tools

#### OPC UA Diagnostics
```bash
# Test OPC UA connectivity
opcua-client connect opc.tcp://localhost:4840

# Browse address space
opcua-client browse opc.tcp://localhost:4840
```

#### Modbus Diagnostics
```bash
# Test Modbus connectivity
modbus-tcp read 127.0.0.1 502 40001 10

# Monitor Modbus traffic
modbus-sniffer -i eth0 -p 502
```

#### REST API Diagnostics
```bash
# Test API connectivity
curl -X GET http://localhost:8080/api/v1/health

# Test authentication
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"operator","password":"password123"}'
```

---

*This protocol integration guide provides comprehensive documentation for integrating with the Calejo Control Adapter using OPC UA, Modbus TCP, and REST API protocols. Each protocol offers unique advantages for different integration scenarios.*