# Protocol Mapping Configuration UI Design

## Overview
This document outlines the comprehensive UI design for configuring database-to-protocol mappings through the dashboard interface, supporting Modbus, OPC UA, and other industrial protocols.

## 🎯 Design Goals
- **Intuitive**: Easy for both technical and non-technical users
- **Visual**: Clear representation of database-to-protocol data flow
- **Configurable**: Flexible mapping configuration without code changes
- **Validated**: Real-time conflict detection and validation
- **Scalable**: Support for multiple stations, pumps, and protocols
- **Protocol-Agnostic**: Unified interface for Modbus, OPC UA, and other protocols

## 🏗️ Architecture

### Data Flow
```
Database Sources → Mapping Configuration → Protocol Endpoints
    ↓                    ↓                    ↓
pump_plans.speed_hz → Setpoint mapping → Modbus: Holding register 40001
pumps.status_code   → Status mapping   → OPC UA: ns=2;s=Station.Pump.Status
safety.flags        → Safety mapping   → Modbus: Coil register 0
flow_meters.rate    → Flow mapping     → OPC UA: ns=2;s=Station.Flow.Rate
```

### Component Structure
```javascript
<ProtocolMappingDashboard>
  <ProtocolSelector />
  <StationSelector />
  <PumpSelector />
  <MappingGrid />
  <MappingConfigurationModal />
  <RealTimePreview />
  <ValidationPanel />
  <TemplateGallery />
  <BulkOperations />
</ProtocolMappingDashboard>
```

## 📋 UI Components

### 1. Main Dashboard Layout
```
┌─────────────────────────────────────────────────────────────────┐
│                    PROTOCOL MAPPING CONFIGURATION               │
├─────────────────────────────────────────────────────────────────┤
│  [Protocols] [Stations] [Pumps] [Mapping View] [Templates]      │
└─────────────────────────────────────────────────────────────────┘
```

### 2. Visual Protocol Mapping View

#### **Layout**:
```
┌─────────────────┐  ┌─────────────────────────────────────────────┐
│                 │  │              PROTOCOL MAPPING               │
│   PUMP LIST     │  │ ┌───┬─────────────┬─────────────┬─────────┐ │
│                 │  │ │ # │ DATA TYPE   │ DB SOURCE   │ ADDRESS │ │
│  STATION_001    │  │ ├───┼─────────────┼─────────────┼─────────┤ │
│   ├─ PUMP_001   │  │ │ 0 │ Setpoint    │ speed_hz    │ 40001   │ │
│   ├─ PUMP_002   │  │ │ 1 │ Status      │ status_code │ 40002   │ │
│   ├─ PUMP_003   │  │ │ 2 │ Power       │ power_kw    │ 40003   │ │
│                 │  │ │ 3 │ Level       │ level_m     │ 40004   │ │
│  STATION_002    │  │ │ 4 │ Flow        │ flow_m3h    │ 40005   │ │
│   ├─ PUMP_004   │  │ │ 5 │ Safety      │ safety_flag │ 40006   │ │
│                 │  │ └───┴─────────────┴─────────────┴─────────┘ │
└─────────────────┘  └─────────────────────────────────────────────┘
```

### 3. Multi-Protocol Configuration Form

#### **Modal/Form Layout**:
```
┌─────────────────────────────────────────────────────────────────┐
│                    CONFIGURE PROTOCOL MAPPING                   │
├─────────────────────────────────────────────────────────────────┤
│ Protocol:   [Modbus TCP ▼]    [OPC UA ▼]    [Custom Protocol]   │
│                                                                 │
│ Station:    [STATION_001 ▼]    Pump:      [PUMP_001 ▼]          │
│                                                                 │
│ Data Type:  [Setpoint ▼]       Protocol Address:                │
│                                                                 │
│ MODBUS:     [40001] (Holding Register)                         │
│ OPC UA:     [ns=2;s=Station.Pump.Setpoint]                     │
│                                                                 │
│ Database Source:                                                │
│   [●] pump_plans.suggested_speed_hz                            │
│   [ ] pumps.default_setpoint_hz                                │
│   [ ] Custom SQL: [___________________________]                │
│                                                                 │
│ Data Transformation:                                            │
│   [●] Direct value              [ ] Scale: [×10] [÷10]         │
│   [ ] Offset: [+___]            [ ] Clamp: [min___] [max___]   │
│                                                                 │
│ Validation: ✅ No conflicts detected                            │
│                                                                 │
│           [SAVE MAPPING]      [TEST MAPPING]    [CANCEL]       │
└─────────────────────────────────────────────────────────────────┘
```

### 4. Protocol-Specific Address Configuration

#### **Modbus Configuration**:
```
┌─────────────────────────────────────────────────────────────────┐
│                    MODBUS ADDRESS CONFIGURATION                 │
├─────────────────────────────────────────────────────────────────┤
│ Register Type: [● Holding  ○ Input  ○ Coil  ○ Discrete]        │
│                                                                 │
│ Address:       [40001]                                         │
│ Size:          [1 register]                                    │
│ Data Type:     [16-bit integer]                                │
│                                                                 │
│ Byte Order:    [Big Endian] [Little Endian]                    │
│ Word Order:    [High Word First] [Low Word First]              │
└─────────────────────────────────────────────────────────────────┘
```

#### **OPC UA Configuration**:
```
┌─────────────────────────────────────────────────────────────────┐
│                    OPC UA NODE CONFIGURATION                    │
├─────────────────────────────────────────────────────────────────┤
│ Node ID:      [ns=2;s=Station.Pump.Setpoint]                   │
│                                                                 │
│ Namespace:    [2]                                              │
│ Browse Name:  [Setpoint]                                       │
│ Display Name: [Pump Setpoint]                                  │
│                                                                 │
│ Data Type:    [Double] [Float] [Int32] [Int16] [Boolean]       │
│ Access Level: [CurrentRead] [CurrentWrite] [HistoryRead]       │
└─────────────────────────────────────────────────────────────────┘
```

### 5. Drag & Drop Interface

#### **Visual Design**:
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   DATABASE      │    │   MAPPING       │    │   PROTOCOL      │
│   SOURCES       │    │   WORKSPACE     │    │   ENDPOINTS     │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ pump_plans  │ │    │ │ Setpoint    │ │    │ │ Modbus      │ │
│ │   speed_hz  │──────▶│ speed_hz     │──────▶│ 40001       │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ pumps       │ │    │ │ Status      │ │    │ │ OPC UA      │ │
│ │   status    │──────▶│ status_code  │──────▶│ ns=2;s=...  │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │ safety      │ │    │ │ Safety      │ │    │ │ Modbus      │ │
│ │   flags     │──────▶│ safety_flag  │──────▶│ Coil 0      │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 6. Real-time Preview Panel

#### **Layout**:
```
┌─────────────────────────────────────────────────────────────────┐
│                      REAL-TIME PREVIEW                          │
├─────────────────┬─────────────┬─────────────┬───────────────────┤
│ Database Value  │ Transform   │ Protocol    │ Current Value     │
├─────────────────┼─────────────┼─────────────┼───────────────────┤
│ 42.3 Hz         │ ×10 →       │ Modbus 40001│ 423               │
│ Running         │ Direct      │ OPC UA Node │ 1                 │
│ 15.2 kW         │ Direct      │ Modbus 40003│ 15                │
│ 2.1 m           │ ×100 →      │ OPC UA Node │ 210               │
└─────────────────┴─────────────┴─────────────┴───────────────────┘
```

### 7. Protocol-Specific Templates

#### **Template Gallery**:
```
┌─────────────────────────────────────────────────────────────────┐
│                        PROTOCOL TEMPLATES                       │
├─────────────────┬─────────────────┬─────────────────────────────┤
│ Modbus Standard │ OPC UA Standard │ Custom Template             │
│                 │                 │                             │
│ • Holding Regs  │ • Analog Items  │ • Import from file          │
│ • Input Regs    │ • Digital Items │ • Export current            │
│ • Coils         │ • Complex Types │ • Save as template          │
│ • Discrete      │ • Methods       │                             │
│                 │                 │                             │
│ [APPLY]         │ [APPLY]         │ [CREATE]                    │
└─────────────────┴─────────────────┴─────────────────────────────┘
```

## 🔧 Technical Implementation

### Data Models
```typescript
interface ProtocolMapping {
  id: string;
  protocolType: 'modbus_tcp' | 'opcua' | 'custom';
  stationId: string;
  pumpId: string;
  dataType: 'setpoint' | 'status' | 'power' | 'flow' | 'level' | 'safety';
  protocolAddress: string; // Register address or OPC UA node
  dbSource: string;
  transformation: TransformationRule[];
  
  // Protocol-specific properties
  modbusConfig?: {
    registerType: 'holding' | 'input' | 'coil' | 'discrete';
    size: number;
    dataType: 'int16' | 'int32' | 'float' | 'boolean';
    byteOrder: 'big_endian' | 'little_endian';
  };
  
  opcuaConfig?: {
    namespace: number;
    browseName: string;
    displayName: string;
    dataType: string;
    accessLevel: string[];
  };
}

interface TransformationRule {
  type: 'scale' | 'offset' | 'clamp' | 'round';
  parameters: any;
}
```

### API Endpoints
```
GET    /api/v1/dashboard/protocol-mappings
POST   /api/v1/dashboard/protocol-mappings
PUT    /api/v1/dashboard/protocol-mappings/{id}
DELETE /api/v1/dashboard/protocol-mappings/{id}
POST   /api/v1/dashboard/protocol-mappings/validate
POST   /api/v1/dashboard/protocol-mappings/test
GET    /api/v1/dashboard/protocol-mappings/templates
POST   /api/v1/dashboard/protocol-mappings/import
GET    /api/v1/dashboard/protocol-mappings/export

# Protocol-specific endpoints
GET    /api/v1/dashboard/protocol-mappings/modbus
GET    /api/v1/dashboard/protocol-mappings/opcua
POST   /api/v1/dashboard/protocol-mappings/modbus/discover
POST   /api/v1/dashboard/protocol-mappings/opcua/browse
```

### Integration Points

#### 1. Configuration Manager Integration
```python
class ConfigurationManager:
    def __init__(self):
        self.protocol_mappings: List[ProtocolMapping] = []
    
    def add_protocol_mapping(self, mapping: ProtocolMapping) -> bool:
        # Validate and add mapping
        pass
    
    def get_protocol_mappings(self, 
                            protocol_type: str = None, 
                            station_id: str = None, 
                            pump_id: str = None) -> List[ProtocolMapping]:
        # Filter mappings by protocol/station/pump
        pass
```

#### 2. Protocol Server Integration
```python
# Modbus Server Integration
class ModbusServer:
    def __init__(self, configuration_manager: ConfigurationManager):
        self.configuration_manager = configuration_manager
        
    async def _update_registers(self):
        modbus_mappings = self.configuration_manager.get_protocol_mappings('modbus_tcp')
        for mapping in modbus_mappings:
            value = self._get_database_value(mapping.dbSource)
            transformed_value = self._apply_transformations(value, mapping.transformation)
            self._write_register(mapping.protocolAddress, transformed_value, mapping.modbusConfig.registerType)

# OPC UA Server Integration  
class OPCUAServer:
    def __init__(self, configuration_manager: ConfigurationManager):
        self.configuration_manager = configuration_manager
        
    async def update_nodes(self):
        opcua_mappings = self.configuration_manager.get_protocol_mappings('opcua')
        for mapping in opcua_mappings:
            value = self._get_database_value(mapping.dbSource)
            transformed_value = self._apply_transformations(value, mapping.transformation)
            await self._write_node(mapping.protocolAddress, transformed_value)
```

## 🎨 Visual Design System

### Color Scheme by Protocol
- **Modbus**: Blue (#2563eb)
- **OPC UA**: Green (#16a34a)  
- **Custom Protocols**: Purple (#9333ea)
- **Success**: Green (#16a34a)
- **Warning**: Yellow (#d97706)
- **Error**: Red (#dc2626)

### Icons
- 🔌 Modbus
- 🌐 OPC UA
- ⚙️ Custom Protocol
- ✅ Valid mapping
- ⚠️ Warning
- ❌ Error
- 🔄 Active/live data
- 📊 Data preview

## 🔍 Validation Rules

### Protocol-Specific Validation

#### Modbus Validation:
- Register addresses: 0-65535
- Address ranges must not overlap
- Data type compatibility with register type
- Valid byte/word order combinations

#### OPC UA Validation:
- Valid Node ID format
- Namespace exists and accessible
- Data type compatibility
- Access level permissions

### Cross-Protocol Validation
- Database source must exist and be accessible
- Transformation rules must be valid
- No duplicate mappings for same data point

## 📊 Performance Considerations

### Protocol-Specific Optimizations
- **Modbus**: Batch register writes for efficiency
- **OPC UA**: Use subscription model for frequent updates
- **All**: Cache transformed values and mapping configurations

## 🔒 Security Considerations

### Protocol Security
- **Modbus**: Validate register access permissions
- **OPC UA**: Certificate-based authentication
- **All**: Role-based access to mapping configuration

## 🚀 Implementation Phases

### Phase 1: Core Protocol Mapping
- Basic mapping configuration for all protocols
- Protocol-specific address configuration
- Real-time preview and validation
- Integration with existing protocol servers

### Phase 2: Enhanced Features
- Drag & drop interface
- Protocol templates
- Bulk operations
- Advanced transformations

### Phase 3: Advanced Features
- Protocol discovery and auto-configuration
- Mobile responsiveness
- Performance optimizations
- Advanced security features

## 📝 Testing Strategy

### Protocol-Specific Testing
- **Modbus**: Register read/write operations, address validation
- **OPC UA**: Node browsing, data type conversion, security
- **Cross-Protocol**: Data consistency, transformation accuracy

## 📚 Documentation

### Protocol-Specific Guides
- Modbus Mapping Configuration Guide
- OPC UA Node Configuration Guide
- Custom Protocol Integration Guide

---

*This document provides the comprehensive design for the Protocol Mapping UI, supporting multiple industrial protocols with a unified interface.*