FCI_WaterMaker_API/WATERMAKER_API_REBUILD_SPECIFICATION.md

Watermaker PLC API - Complete Rebuild Specification

Overview

This document provides a comprehensive specification for rebuilding the Watermaker PLC API from scratch while maintaining exact functionality with improved code structure and documentation.

Current API Version: 1.1
PLC Target: 198.18.100.141:502 (Modbus TCP)
Protocol: Modbus TCP/IP

Table of Contents

1. API Routes Specification
2. PLC Register Specifications
3. DTS Process Documentation
4. Timer Usage and Progress Monitoring
5. Rebuild Architecture Plan
6. Implementation Guidelines

---

API Routes Specification

System & Status Endpoints

Method	Endpoint	Description	Response Time
GET	/api/status	Connection and system status	< 100ms
GET	/api/all	All PLC data in one response	< 500ms
GET	/api/select	Selective data retrieval (bandwidth optimized)	< 200ms
GET	/api/errors	Recent errors (last 10)	< 50ms
GET	/api/config	API configuration and available endpoints	< 50ms
POST	/api/write/register	Write single holding register	< 100ms

Data Monitoring Endpoints

Method	Endpoint	Description	Response Time
GET	/api/sensors	All sensor data	< 100ms
GET	/api/sensors/category/<category>	Sensors by category	< 100ms
GET	/api/timers	All timer data	< 100ms
GET	/api/timers/dts	DTS timer data	< 100ms
GET	/api/timers/fwf	Fresh Water Flush timer data	< 100ms
GET	/api/rtc	Real-time clock data	< 100ms
GET	/api/outputs	Output control data	< 100ms
GET	/api/outputs/active	Active output controls only	< 100ms
GET	/api/runtime	Runtime hours data (IEEE 754 float)	< 100ms
GET	/api/water_counters	Water production counters (gallon totals)	< 100ms

Valid Categories for /api/sensors/category/<category>:

• system - System status and operational mode
• pressure - Water pressure sensors
• temperature - Temperature monitoring
• flow - Flow rate meters
• quality - Water quality (TDS) sensors

DTS Control Endpoints

Method	Endpoint	Description	Response Time
POST	/api/dts/start	Start DTS watermaker sequence (async)	< 100ms
POST	/api/dts/stop	Stop watermaker sequence (async, mode-dependent)	< 100ms
POST	/api/dts/skip	Skip current step automatically (async)	< 100ms
GET	/api/dts/status	Get latest DTS operation status	< 50ms
GET	/api/dts/status/<task_id>	Get specific DTS task status (legacy)	< 50ms
POST	/api/dts/cancel	Cancel running DTS operation	< 50ms
POST	/api/dts/cancel/<task_id>	Cancel DTS task (legacy)	< 50ms
GET	/api/dts/current-step-progress	Get current DTS step progress based on timers	< 100ms
GET	/api/dts/r1000-monitor	Get R1000 monitoring status and recent changes	< 100ms

---

PLC Register Specifications

System Control Registers

Register	Name	Type	Values	Description
R1000	System Mode	Direct	See mode table below	Main system operational mode
R1036	System Status	Direct	0=Standby, 5=FWF, 7=Service Mode	Current system status
R71	Control Commands	Direct	Various command codes	Used for valve control and system commands
R67	Step Skip Commands	Direct	32841, 32968	Used for skipping DTS steps

R1000 System Mode Values:

• 2 - Home/Standby
• 3 - Alarm List
• 5 - DTS Prime
• 6 - DTS Initialization
• 7 - DTS Running/Production
• 8 - Fresh Water Flush
• 9 - Settings
• 15 - Service Mode (Quality & Flush Valves / Pumps)
• 16 - Service Mode (Double Pass & Feed Valves)
• 17 - Service Mode (APC Need Valves)
• 18 - Service Mode (Sensors - TDS, PPM, Flow, Temperature)
• 31 - Overview Schematic
• 32 - Contact Support
• 33 - Seawater (Choose Single or Double Pass)
• 34 - DTS Request
• 65535 - Standby

Sensor Registers

Register	Name	Scale	Unit	Category	Description
R1003	Feed Pressure	Direct	PSI	pressure	Water feed pressure
R1007	High Pressure #2	Direct	PSI	pressure	High pressure sensor 2
R1008	High Pressure #1	Direct	PSI	pressure	High pressure sensor 1
R1017	Water Temperature	÷10	°F	temperature	Water temperature
R1125	System Temperature	÷10	°F	temperature	System temperature
R1120	Brine Flowmeter	÷10	GPM	flow	Brine flow rate
R1121	1st Pass Product Flowmeter	÷10	GPM	flow	First pass product flow
R1122	2nd Pass Product Flowmeter	÷10	GPM	flow	Second pass product flow
R1123	Product TDS #1	Direct	PPM	quality	Total dissolved solids sensor 1
R1124	Product TDS #2	Direct	PPM	quality	Total dissolved solids sensor 2

Timer Registers

Register	Name	Scale	Unit	Category	Expected Start	Description
R136	FWF Flush Timer	÷10	sec	fwf_timer	600	Fresh water flush timer
R138	DTS Valve Positioning Timer	÷10	sec	dts_timer	150	Valve positioning during DTS start
R128	DTS Priming Timer	÷10	sec	dts_timer	1800	DTS priming phase timer
R129	DTS Initialize Timer	÷10	sec	dts_timer	600	DTS initialization timer
R133	DTS Fresh Water Flush Timer	÷10	sec	dts_timer	600	DTS fresh water flush timer
R135	DTS Stop Timer	÷10	sec	dts_timer	100	DTS stop sequence timer
R139	DTS Flush Timer	÷10	sec	dts_timer	600	DTS flush timer

Output Control Registers

Register	Name	Bit Position	Description
R257	Low Pressure Pump	0	Low pressure pump control
R258	High Pressure Pump	1	High pressure pump control
R259	Product Divert Valve	2	Product divert valve control
R260	Flush Solenoid	3	Flush solenoid control
R264	Double Pass Solenoid	7	Double pass solenoid control
R265	Shore Feed Solenoid	8	Shore feed solenoid control

Runtime & Counter Registers (32-bit IEEE 754 Float Pairs)

Register	Name	Pair Register	Unit	Description
R5014	Runtime Hours	R5015	hours	Total system runtime
R5024	Single-Pass Total Gallons	R5025	gallons	Total single-pass water produced
R5026	Single-Pass Since Last	R5027	gallons	Single-pass water since last reset
R5028	Double-Pass Total Gallons	R5029	gallons	Total double-pass water produced
R5030	Double-Pass Since Last	R5031	gallons	Double-pass water since last reset
R5032	DTS Total Gallons	R5033	gallons	Total DTS water produced
R5034	DTS Since Last Gallons	R5035	gallons	DTS water since last reset

Real-Time Clock Registers

Register	Name	Unit	Description
R513	RTC Minutes	min	Real-time clock minutes
R514	RTC Seconds	sec	Real-time clock seconds
R516	RTC Year	-	Real-time clock year
R517	RTC Month	-	Real-time clock month
R518	RTC Day	-	Real-time clock day
R519	RTC Month (Alt)	-	Alternative month register

---

DTS Process Documentation

DTS Screen Flow Sequence

graph TD
    A[Mode 34: DTS Requested] --> B[Mode 5: Priming Screen]
    B --> C[Mode 6: Init Screen]
    C --> D[Mode 7: Production Screen]
    D --> E[Mode 8: Fresh Water Flush]
    E --> F[Mode 2: Standby]
    
    B -.->|Skip R67=32841| D
    C -.->|Skip R67=32968| D
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style E fill:#fce4ec
    style F fill:#f5f5f5

DTS Screen Definitions

Mode	Screen Name	Description	Timer	Duration	Skippable
34	DTS Requested	Press and hold DTS to START	None	Manual	No
5	Priming	Flush with shore pressure	R128	180 sec	Yes
6	Init	High pressure pump initialization	R129	60 sec	Yes
7	Production	Water flowing to tank	None	Manual	No
8	Fresh Water Flush	End of DTS process	R133	60 sec	No

DTS Process Start Sequence

API Endpoint: POST /api/dts/start

Sequence Steps (as implemented in execute_dts_sequence()):

1. Check R1000 value - Read current system mode
2. If not 34, set R1000=34 - Set preparation mode
3. Wait 2 seconds - Allow mode change to settle
4. Set R71=256 - Send valve positioning command
5. Wait 2 seconds - Allow command processing
6. Set R71=0 - Complete valve command sequence
7. Monitor R138 - Wait for valve positioning (up to 15 seconds)
8. Set R1000=5 - Start DTS priming mode

Total Sequence Time: ~10 seconds (excluding valve positioning)

DTS Process Stop Sequences

API Endpoint: POST /api/dts/stop

Stop sequence varies by current system mode (as implemented in execute_stop_sequence()):

Mode 5 (Priming) Stop Sequence

1. Set R71=512
2. Wait 1 second
3. Set R71=0
4. Set R1000=8 (Fresh Water Flush)

Mode 7 (Production) Stop Sequence

1. Set R71=513
2. Wait 1 second
3. Set R71=0
4. Set R1000=8 (Fresh Water Flush)

Mode 8 (Flush) Stop Sequence

1. Set R71=1024
2. Wait 1 second
3. Set R71=0
4. Set R1000=2 (Standby)

DTS Step Skip Sequences

API Endpoint: POST /api/dts/skip

Skip sequences automatically determine next step (as implemented in execute_skip_sequence()):

Skip from Mode 5 (Priming)

• Command: R67=32841
• Result: PLC advances to Mode 6 then Mode 7 (Production)

Skip from Mode 6 (Init)

• Command: R67=32968
• Wait: 1 second
• Command: R1000=7 (Production)

---

Timer Usage and Progress Monitoring

Timer-Based Progress Calculation

Formula (as implemented in calculate_timer_progress_percent()):

Progress % = (Initial_Value - Current_Value) / Initial_Value * 100

Special Values:

• Timer value 65535 = Timer not active (0% progress)
• Timer value 0 = Timer complete (100% progress)

DTS Mode to Timer Mapping

DTS Mode	Timer Register	Expected Duration	Progress Monitoring
5 (Priming)	R128	180 seconds	Yes
6 (Init)	R129	60 seconds	Yes
7 (Production)	None	Manual	No
8 (Flush)	R133	60 seconds	Yes

Background Timer Monitoring

The system continuously monitors timers via update_dts_progress_from_timers() which:

1. Reads current R1000 mode
2. Maps mode to timer register
3. Reads timer value
4. Calculates progress percentage
5. Updates operation state
6. Detects external changes

---

Rebuild Architecture Plan

High-Level Architecture

graph TB
    subgraph "API Layer"
        A[Flask Application]
        B[Route Controllers]
        C[Request/Response Handlers]
        D[Middleware & Validation]
    end
    
    subgraph "Business Logic Layer"
        E[DTS Process Manager]
        F[Data Processing Service]
        G[Validation Service]
        H[Operation State Manager]
    end
    
    subgraph "Data Access Layer"
        I[PLC Connection Manager]
        J[Register Reader/Writer]
        K[Data Cache Repository]
        L[Configuration Manager]
    end
    
    subgraph "Infrastructure Layer"
        M[Background Task Manager]
        N[R1000 Monitor]
        O[Timer Progress Monitor]
        P[Error Handler & Logger]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> L
    M --> N
    N --> O
    O --> P
    E --> M

Improved Project Structure

watermaker_plc_api/
├── api/
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── system_routes.py          # System & status endpoints
│   │   ├── sensor_routes.py          # Sensor data endpoints  
│   │   ├── timer_routes.py           # Timer & RTC endpoints
│   │   ├── output_routes.py          # Output control endpoints
│   │   └── dts_routes.py             # DTS control endpoints
│   ├── middleware/
│   │   ├── __init__.py
│   │   ├── error_handler.py          # Global error handling
│   │   ├── request_validator.py      # Request validation
│   │   ├── response_formatter.py     # Response formatting
│   │   └── cors_handler.py           # CORS configuration
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── request_schemas.py        # Pydantic request models
│   │   ├── response_schemas.py       # Pydantic response models
│   │   └── validation_schemas.py     # Validation rules
│   └── __init__.py
├── core/
│   ├── services/
│   │   ├── __init__.py
│   │   ├── plc_service.py            # PLC communication service
│   │   ├── dts_service.py            # DTS process management
│   │   ├── data_service.py           # Data processing & caching
│   │   ├── monitoring_service.py     # System monitoring
│   │   └── validation_service.py     # Business logic validation
│   ├── models/
│   │   ├── register_models.py
│   │   ├── sensor_models.py
│   │   ├── timer_models.py
│   │   └── dts_models.py
│   └── repositories/
│       ├── plc_repository.py
│       └── cache_repository.py
├── infrastructure/
│   ├── plc/
│   │   ├── connection.py
│   │   ├── register_reader.py
│   │   └── register_writer.py
│   ├── cache/
│   │   └── data_cache.py
│   └── background/
│       ├── task_manager.py
│       └── monitors.py
├── config/
│   ├── settings.py
│   ├── register_mappings.py
│   └── dts_config.py
└── utils/
    ├── logger.py
    ├── validators.py
    └── converters.py