Real-time Data Monitoring: Sensors, timers, outputs, runtime hours, water counters
Selective Data Retrieval: Bandwidth-optimized API for specific data groups/keys
Asynchronous Control Operations: DTS start/stop/skip sequences with progress tracking
Background Data Updates: Continuous PLC monitoring with configurable intervals
Thread-safe Data Caching: Centralized cache with concurrent access support
Comprehensive Error Handling: Structured error responses and logging
Modular Architecture: Clean separation of concerns with service layers

Quick Start

Installation

# Clone repository
git clone <repository-url>
cd watermaker-plc-api

# Install dependencies
pip install -r requirements.txt

# Install package
pip install -e .

Configuration

Set environment variables:

export PLC_IP=198.18.100.141
export PLC_PORT=502
export DATA_UPDATE_INTERVAL=5
export LOG_LEVEL=INFO

Running the API

# Using the command line entry point
watermaker-api --host 0.0.0.0 --port 5000

# Or run directly
python -m watermaker_plc_api.main

API Endpoints

Data Monitoring

GET /api/status - Connection and system status
GET /api/all - All PLC data in one response
GET /api/select - Selective data retrieval (bandwidth optimized)
GET /api/sensors - All sensor data
GET /api/timers - All timer data
GET /api/outputs - Output control data
GET /api/runtime - Runtime hours data
GET /api/water_counters - Water production counters

Control Operations

POST /api/dts/start - Start DTS watermaker sequence (async)
POST /api/dts/stop - Stop watermaker sequence (async)
POST /api/dts/skip - Skip current step (async)
GET /api/dts/status - Get DTS operation status
POST /api/write/register - Write single register

Selective API Examples

# Get temperature and pressure sensors only
curl "http://localhost:5000/api/select?groups=temperature,pressure"

# Get specific registers
curl "http://localhost:5000/api/select?keys=1036,1003,1017,1121"

# Combined approach
curl "http://localhost:5000/api/select?groups=dts_timer&keys=1036"

Control Examples

# Start DTS sequence (returns immediately with task_id)
curl -X POST http://localhost:5000/api/dts/start

# Poll for progress
curl http://localhost:5000/api/dts/status/abc12345

# Stop watermaker
curl -X POST http://localhost:5000/api/dts/stop

Architecture

watermaker_plc_api/
├── app.py                 # Flask application factory
├── config.py              # Configuration management
├── controllers/           # API route handlers
├── services/              # Business logic layer
├── models/                # Data models and mappings
└── utils/                 # Utilities and helpers

Key Components

PLCConnection: Thread-safe Modbus TCP communication
DataCache: Centralized, thread-safe data storage
RegisterReader: Service for reading PLC registers
RegisterWriter: Service for writing PLC registers
BackgroundTaskManager: Continuous data updates
Controllers: RESTful API endpoints

Variable Groups

Group	Description	Count
system	System status and mode	2
pressure	Water pressure sensors	3
temperature	Temperature monitoring	2
flow	Flow rate meters	3
quality	Water quality (TDS) sensors	2
fwf_timer	Fresh water flush timers	1
dts_timer	DTS process step timers	6
rtc	Real-time clock data	6
outputs	Digital output controls	6
runtime	System runtime hours	1
water_counters	Water production counters	4

DTS Modes

The watermaker system operates through various DTS (Desalination Treatment System) modes controlled by register R1000. Understanding these modes is essential for UI modeling and system monitoring.

System Mode Values (R1000)

Mode	Name	Description	Timer	Duration
65535	Standby/Screen Saver	System in standby mode	-	-
2	Idle/Home	System idle at home screen	-	-
3	Alarm List	Displaying system alarms	-	-
34	DTS Requested	Step 1 - Press and hold DTS to START	-	Manual
5	DTS Step 1	Step 2 - Flush with shore pressure	R138	15 sec
6	DTS Step 2	Step 3 - High pressure pump on, product valve divert	R128	180 sec
7	DTS Production	Step 4 - High pressure pump on, water flowing to tank	-	Variable
8	Fresh Water Flush	Post-production flush sequence	R133	60 sec
9	Setup Screen	System configuration interface	R135	10 sec
10	DTS Step 6	Final flush sequence	R139	60 sec
15	Service Toggle	Toggle pumps, valves, service mode	-	Manual
16	Feed Valve Toggle	Toggle double pass/feed valve	-	Manual
17	Needle Valve Control	Manual needle valve adjustment	-	Manual
18	Sensor Overview	Sensor reading display	-	Manual
31	System Diagram	Overview system diagram map	-	Manual
32	Contact Support	Support contact screen	-	Manual
33	Seawater Home	Pick single or double pass	-	Manual

DTS Process Flow

The typical DTS watermaker sequence follows this progression:

Mode 34 → Mode 5 → Mode 6 → Mode 7 → Mode 8 → Mode 10 → Mode 2

Timer Mappings

Each DTS step with a timer has specific register addresses and expected durations:

Timer Register	DTS Mode	Step Name	Expected Duration	Purpose
R138	5	DTS Step 1	15 seconds	Initial processing
R128	6	DTS Step 2	180 seconds	Priming sequence
R133	8	DTS Step 4	60 seconds	Processing
R135	9	DTS Step 5	10 seconds	Stop sequence
R139	10	DTS Step 6	60 seconds	Final flush

Note: Mode 7 (Production) has no timer as it runs until manually stopped or conditions change.

Control Operations by Mode

Different stop sequences are executed based on the current mode:

Mode 5: R71=512 → R71=0 → R1000=8
Mode 7: R71=513 → R71=0 → R1000=8
Mode 8: R71=1024 → R71=0 → R1000=2

Skip Operations

Skip functionality is available for specific modes:

From Mode 5: Skip to Step 3 via R67=32841 (advances to Mode 6)
From Mode 6: Skip to Step 4 via R67=32968 → R1000=7

Development

Running Tests

python -m pytest tests/

Environment Setup

# Development environment
export FLASK_ENV=development
export DEBUG=true
export PLC_IP=127.0.0.1  # For simulator

# Production environment
export FLASK_ENV=production
export SECRET_KEY=your-secret-key
export PLC_IP=198.18.100.141

License

MIT License - see LICENSE file for details.