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

15 KiB
Raw Blame History

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

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

# 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

# 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

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

Modbus TCP Integration

Modbus Server Configuration

Server Setup

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

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

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

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

Response:

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

Pump Management

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

Response:

{
  "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

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

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

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

Input Validation

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

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

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

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

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

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

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

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

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

Modbus Diagnostics

# 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

# 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.