CalejoControl/docs/DASHBOARD_CONFIGURATION_GUIDE.md

# Dashboard Configuration Guide

## Overview

This guide explains how to configure your Calejo Control Adapter entirely through the web dashboard - no manual configuration required!

## 🎯 Your Vision Achieved

**Before**: Manual configuration files, SSH access, complex setup
**After**: One-click setup → Dashboard configuration → Ready to use

## 🚀 Getting Started

### Step 1: Run One-Click Setup

```bash
# Local development
./setup-server.sh

# Remote server
./setup-server.sh -h your-server.com -u ubuntu -k ~/.ssh/id_rsa
```

### Step 2: Access Dashboard

Open your browser and navigate to:
```
http://your-server:8080/dashboard
```

## 🔧 Complete Configuration Workflow

### 1. Configure SCADA Protocols

#### OPC UA Configuration

1. Navigate to **Protocols** → **OPC UA**
2. Configure settings:
   - **Endpoint**: `opc.tcp://0.0.0.0:4840` (default)
   - **Security Policy**: Basic256Sha256
   - **Certificate**: Auto-generated
3. Test connection

**Example Configuration**:
```json
{
  "protocol_type": "opcua",
  "enabled": true,
  "name": "Main OPC UA Server",
  "endpoint": "opc.tcp://192.168.1.100:4840",
  "security_policy": "Basic256Sha256"
}
```

#### Modbus TCP Configuration

1. Navigate to **Protocols** → **Modbus TCP**
2. Configure settings:
   - **Host**: `0.0.0.0` (listen on all interfaces)
   - **Port**: `502` (standard Modbus port)
   - **Unit ID**: `1` (device address)
3. Test connection

**Example Configuration**:
```json
{
  "protocol_type": "modbus_tcp",
  "enabled": true,
  "name": "Primary Modbus Network",
  "host": "192.168.1.200",
  "port": 502,
  "unit_id": 1
}
```

### 2. Auto-Discover Hardware

1. Navigate to **Hardware** → **Auto-Discovery**
2. Select protocols to scan
3. Review discovered equipment
4. Import discovered stations and pumps

**Discovery Results**:
```json
{
  "success": true,
  "discovered_stations": [
    {
      "station_id": "station_001",
      "name": "Main Pump Station",
      "location": "Building A",
      "max_pumps": 4
    }
  ],
  "discovered_pumps": [
    {
      "pump_id": "pump_001",
      "station_id": "station_001",
      "name": "Primary Pump",
      "type": "centrifugal",
      "power_rating": 55.0
    }
  ]
}
```

### 3. Configure Pump Stations

1. Navigate to **Stations** → **Add Station**
2. Enter station details:
   - **Station ID**: Unique identifier
   - **Name**: Descriptive name
   - **Location**: Physical location
   - **Capacity**: Maximum pumps and power

**Example Station Configuration**:
```json
{
  "station_id": "main_station",
  "name": "Main Wastewater Pump Station",
  "location": "123 Industrial Park",
  "max_pumps": 6,
  "power_capacity": 300.0,
  "flow_capacity": 1000.0
}
```

### 4. Configure Individual Pumps

1. Navigate to **Pumps** → **Add Pump**
2. Select station
3. Enter pump specifications:
   - **Pump ID**: Unique identifier
   - **Type**: Centrifugal, submersible, etc.
   - **Power Rating**: kW
   - **Speed Range**: Min/max Hz

**Example Pump Configuration**:
```json
{
  "pump_id": "primary_pump",
  "station_id": "main_station",
  "name": "Primary Centrifugal Pump",
  "type": "centrifugal",
  "power_rating": 75.0,
  "max_speed": 60.0,
  "min_speed": 20.0,
  "vfd_model": "ABB ACS880",
  "manufacturer": "Grundfos"
}
```

### 5. Set Safety Limits

1. Navigate to **Safety** → **Limits**
2. Select pump
3. Configure safety parameters:
   - **Speed Limits**: Min/max Hz
   - **Power Limits**: Maximum kW
   - **Rate of Change**: Hz per minute

**Example Safety Configuration**:
```json
{
  "station_id": "main_station",
  "pump_id": "primary_pump",
  "hard_min_speed_hz": 20.0,
  "hard_max_speed_hz": 55.0,
  "hard_max_power_kw": 80.0,
  "max_speed_change_hz_per_min": 25.0
}
```

### 6. Map Data Points

1. Navigate to **Data Mapping** → **Add Mapping**
2. Configure protocol-to-internal mappings:
   - **Protocol**: OPC UA, Modbus, etc.
   - **Data Type**: Setpoint, actual speed, status
   - **Protocol Address**: Node ID, register address

**Example Data Mapping**:
```json
{
  "protocol_type": "opcua",
  "station_id": "main_station",
  "pump_id": "primary_pump",
  "data_type": "setpoint",
  "protocol_address": "ns=2;s=MainStation.PrimaryPump.Setpoint"
}
```

## 🎛️ Dashboard Features

### Real-time Monitoring

- **System Status**: Application health, protocol status
- **Performance Metrics**: CPU, memory, network usage
- **Safety Status**: Current limits, violations, emergency stop
- **Protocol Activity**: Active connections, data flow

### Operations Management

- **Emergency Stop**: Activate/deactivate through dashboard
- **Setpoint Control**: Manual override with safety enforcement
- **User Management**: Add/remove users, set roles
- **Audit Logs**: View security and operational events

### Configuration Management

- **Validation**: Check configuration completeness
- **Export/Import**: Backup and restore configurations
- **Version Control**: Track configuration changes
- **Templates**: Save and reuse configuration patterns

## 🔄 Configuration Workflow Examples

### Complete SCADA Integration

```bash
# 1. Setup server
./setup-server.sh -h scada-server.company.com -u admin -k ~/.ssh/scada_key

# 2. Access dashboard
http://scada-server.company.com:8080/dashboard

# 3. Configure protocols
- OPC UA: opc.tcp://plc-network:4840
- Modbus TCP: 192.168.1.100:502

# 4. Discover hardware
- Auto-discover connected PLCs and pumps

# 5. Set safety limits
- Min speed: 20 Hz, Max speed: 50 Hz
- Max power: 75 kW

# 6. Map data points
- OPC UA nodes to internal pump controls

# 7. Validate configuration
- Check for completeness and errors

# 8. Start operations!
```

### Quick Configuration Template

```json
{
  "protocols": {
    "opcua": {
      "enabled": true,
      "endpoint": "opc.tcp://plc-network:4840"
    },
    "modbus_tcp": {
      "enabled": true,
      "host": "192.168.1.100",
      "port": 502
    }
  },
  "stations": [
    {
      "station_id": "main_station",
      "name": "Main Pump Station"
    }
  ],
  "pumps": [
    {
      "pump_id": "pump_1",
      "station_id": "main_station",
      "name": "Primary Pump"
    }
  ],
  "safety_limits": [
    {
      "pump_id": "pump_1",
      "hard_min_speed_hz": 20.0,
      "hard_max_speed_hz": 50.0
    }
  ]
}
```

## 🛠️ Troubleshooting

### Common Issues

1. **Protocol Connection Failed**
   - Check network connectivity
   - Verify protocol settings
   - Test with protocol client

2. **Hardware Not Discovered**
   - Ensure protocols are configured
   - Check hardware connectivity
   - Verify network permissions

3. **Safety Limits Not Applied**
   - Validate configuration
   - Check pump mappings
   - Review audit logs

### Validation Checklist

- [ ] All required protocols configured
- [ ] Pump stations defined
- [ ] Individual pumps configured
- [ ] Safety limits set for each pump
- [ ] Data mappings established
- [ ] Configuration validated
- [ ] Test connections successful

## 📞 Support

- **Dashboard Help**: Click help icons throughout the interface
- **Documentation**: Full documentation in `docs/` directory
- **Community**: Join our user community for support
- **Issues**: Report problems via GitHub issues

---

*Your Calejo Control Adapter is now fully configured and ready for SCADA integration! All configuration is managed through the intuitive web dashboard - no manual file editing required.*