paulg/FCI_WaterMaker_API
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

check point - creating API specification and task management files

Browse Source
This commit is contained in:
Paul Golownia
2025-06-13 22:26:53 +00:00
parent 39aadf2af9
commit e279ee7415
5 changed files with 814 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

651
API_SPEC.md Normal file
View File

@@ -0,0 +1,651 @@
# Watermaker PLC API
RESTful API for monitoring and controlling watermaker PLC systems. Provides access to sensors, timers, controls, and watermaker operation sequences.
## Features
- **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
```bash
# 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:
```bash
export PLC_IP=198.18.100.141
export PLC_PORT=502
export DATA_UPDATE_INTERVAL=5
export LOG_LEVEL=INFO
```
### Running the API
```bash
# 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/start?mode={mode}` - Start watermaker sequence in specified mode (async)
- `POST /api/stop` - Stop watermaker sequence
- `POST /api/skip` - Skip current step
- `GET /api/status` - Get DTS operation status
- `POST /api/write/register` - Write single register
**Supported modes:** `dts`, `single_pass`, `double_pass`, `fw_flush`
### Selective API Examples
```bash
# 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 Sequence
The control API supports starting, stopping, skipping, and checking the status of watermaker operations in multiple modes. All operations use URL parameters for mode selection, ensuring a consistent and simple interface.
Start a sequence in a specific mode by specifying the `mode` as a URL query parameter. Supported modes: `dts`, `single_pass`, `double_pass`, `fw_flush`.
```bash
# Start Dockside Treatment (DTS) sequence
curl -X POST "http://localhost:5000/api/start?mode=dts"
# Start Single Pass Sea Water sequence
curl -X POST "http://localhost:5000/api/start?mode=single_pass"
# Start Double Pass Sea Water sequence
curl -X POST "http://localhost:5000/api/start?mode=double_pass"
# Start Fresh Water Flush sequence
curl -X POST "http://localhost:5000/api/start?mode=fw_flush"
```
#### Stop Sequence
Stop the currently running sequence, regardless of mode. The stop process will imedatly return true. Stop sequence initiates a fresh water flush which can take up to 180 seconds to complete.
```bash
curl -X POST http://localhost:5000/api/stop
```
#### Skip Current Step
Skip the current step in the active sequence if allowed. Trying to skip a step that cannot be skipped or when an operation is not running will return an error.
```bash
curl -X POST http://localhost:5000/api/skip
```
#### Check Sequence Status
Poll for the status of the current operation (optionally by operation ID):
```bash
curl http://localhost:5000/api/status
```
**Notes:**
- The `mode` query parameter is required for starting a new sequence and must be one of: `dts`, `single_pass`, `double_pass`, `fw_flush`.
- Only one sequence can run at a time. Attempting to start a new sequence while another is active will return an error.
- The skip operation is only available during certain steps, as described in the logic tables below.
## Architecture
The project follows a modular architecture to ensure maintainability, scalability, and clear separation of concerns:
```
watermaker_plc_api/
├── app.py # Flask application entry point and factory
├── config.py # Configuration management (env vars, defaults)
├── controllers/ # API route handlers (REST endpoints)
├── services/ # Business logic and PLC communication
├── models/ # Data models, register maps, and schemas
└── utils/ # Utility functions and helpers
```
- **app.py**: Initializes the Flask app, registers blueprints, and sets up middleware.
- **config.py**: Loads and manages configuration from environment variables or files.
- **controllers/**: Contains route handlers for all API endpoints (e.g., status, sensors, control).
- **services/**: Implements core logic for PLC communication, data caching, and background tasks.
- **models/**: Defines data structures, register mappings, and validation schemas.
- **utils/**: Provides helper functions for logging, error handling, and common tasks.
This structure supports clean separation between the API layer, business logic, and hardware communication, making it easier to extend and maintain.
### 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
## Watermaker PLC Operation
### 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 |
### Screen Values (R1000)
The watermaker system operates through various modes, DTS (Dockside Treatment System), Sea Water Single Pass, Sea Water Double Pass and Fresh Water Flush modes controlled by register R1000. Understanding these modes is essential for UI modeling and system monitoring.
| Value | Name | Description | Timer | Duration |
|------|------|-------------|-------|----------|
| 65535 | Standby/Screen Saver | System in standby mode | - | - |
| 2 | Home | System idle at home screen | - | - |
| 3 | Alarm List | Displaying system alarms | - | - |
| 34 | DTS Request | Press and hold DTS to START | R138 | 15 sec timer starts after DTS requested |
| 5 | DTS Priming | Prime with shore water | R128 | 180 sec |
| 6 | DTS Initilizing| High pressure pump on, allow pressure to stabalize | R129 | 60 sec |
| 7 | DTS Run | High pressure pump on, water flowing to tank | - | Variable |
| 8 | Fresh Water Flush | Post-production Flush | R135 DTS Stop / R139 DTS Flush / R136 Manual Flush | 10 sec / 60 sec / 180 sec |
| 9 | Setup Screen | System configuration interface | - | Manual |
| 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 Request Home | Long press - Single or double pass | - | Manual |
### Water Maker Logic Tables
#### Step Detection Table
| Step | Register 1036 | Register 1037 |
|------|---------------|---------------|
| PRIME | 1 | 1 |
| INIT | 2 | 2 |
| RUN | 3 | 2 |
| STOP | 5 | 4 |
| FLUSH | 5 | 7 |
#### Mode Detection Table
| Mode | Register 1040 | Register 1039 | Register 1038 | Notes |
|------|---------------|---------------|---------------|-------|
| Dockside Treatment (DTS) | 2 | 0 | 4 | Uses city water through freshwater membrane |
| Single Pass Sea Water | 0 | 0 | 2 (during RUN)<br>4 (other steps) | Uses single sea water membrane |
| Double Pass Sea Water | 0 | 1 (most steps)<br>2 (during INIT) | 4 | Uses sea water membrane + freshwater membrane |
#### Detection Algorithm:
1. **First, determine the step** using registers 1036 and 1037
2. **Then, determine the mode**:
- If register 1040 = 2 → Dockside Treatment mode
- If register 1040 = 0 and register 1039 = 0 → Single Pass mode
- If register 1040 = 0 and register 1039 > 0 → Double Pass mode
#### Operating Mode (R1036)
The `R1036` register indicates the current operating mode and is used across all modes (Sea Water Single Pass, Sea Water Double Pass, Dockside Treatment System).
- **Starting a new mode:**
You can only start a new operating mode when `R1036 = 0` (Idle).
- **Stopping the watermaker:**
A stop command can be issued when `R1036` is `1`, `2`, `3` or `4` (Priming, Initializing, Running, Flushing). The watermaker will then automatically proceed to the Stop and Flush steps.
- **Skipping steps:**
A skip command can be issued when `R1036` is `1` or `2` (Priming or Initializing). The watermaker will automatically proceed to the next available step.
This logic ensures safe transitions between watermaker operation steps and prevents mode changes during critical processes.
## Watermaker Mode Sequence of Operations
### Detailed DTS Mode Operation Sequence (from owners manual)
#### 1. Prime Sequence (Screen 5, Mode 1)
System configuration:
- LPP: Off (can be enabled for dockwater pressure regulation)
- HPP: Off
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed to quality valve
- Feed Valve: Directed to dock water
- APC #1 (Single-Pass/DTS): Open
- APC #2 (Double-Pass): Open
Operating parameters:
- Low pressure must be >5 PSI and <60 PSI
- Prime timer countdown from setpoint 180 seconds
- Monitored values: Low Pressure, Brine Flow
#### 2. Initialize Sequence (Screen 6, Mode 2)
System configuration:
- LPP: Off (can be enabled)
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed to quality valve
- Feed Valve: Directed to dock water
- APC #1: Gradually closing to production rate
- APC #2: Open
Operating parameters:
- Low pressure must be >5 PSI
- Initialize timer countdown from setpoint
- High Pressure Control Valve slowly closes
- Monitored values: Low/High Pressure, Brine Flow
#### 3. Run Sequence (Screen 7, Mode 3)
System configuration during stabilization and production:
- LPP: Off (can be enabled)
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed to quality valve
- Feed Valve: Directed to dock water
- APC #1: Stabilized at production rate
- APC #2: Open
Monitored values:
- Low/High Pressure
- Brine/Product Flow
- Product TDS
- System Temperature
#### 4. Flush Sequence (Screen 8, Mode 4/5)
Initial 10-second delay configuration:
- All pumps: Off
- All valves: Initial positions
- APC #1 & #2: Open
Final flush configuration:
- LPP: Off
- HPP: Off
- FWF Valve: Open
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed to quality valve
- Feed Valve: Directed to dock water
- APC #1 & #2: Open
Monitored values:
- Flush timer countdown
- Low pressure (confirms FWF pressure)
- Brine flow (confirms FWF flow)
DTS Mode can only be requested when current operating mode is 0.
The typical DTS watermaker sequence follows this progression:
1. **Screen 34** → **Screen 5** → **Screen 6** → **Screen 7** → **Screen 8** → **Screen 2**
### Detailed Single-Pass Mode Operation Sequence (from owners manual)
#### 1. Prime Sequence (Single-Pass Mode)
System configuration:
- LPP: On
- HPP: Off
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards quality valve
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Open position
- APC #2 (Double-Pass): Open position
Operating parameters:
- Low pressure must be >5 PSI and <60 PSI or system will shutdown
- Prime timer countdown from setpoint (Prime Timer Setpoint)
- LPP pump status verified by Low Pressure Transducer
Monitored values:
- Timer: Time left in seconds for Prime Sequence
- Low Pressure: Low Pressure Transducer reading
- Brine Flow: Brine Flow Meter reading
#### 2. Initialize Sequence (Single-Pass Mode)
System configuration:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards quality valve
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Starting to close
- APC #2 (Double-Pass): Open position
Operating parameters:
- Low pressure must be >5 PSI or system will shutdown
- High Pressure Control Valve slowly closes until desired production rate achieved
- Initialize timer countdown from setpoint (Initialize Timer Setpoint)
Monitored values:
- Timer: Time left in seconds for Initialize Sequence
- Low Pressure: Low Pressure Transducer reading
- High Pressure: High Pressure Transducer reading
- Brine Flow: Brine Flow Meter reading
- Product Flow: Product Flow Meter reading
#### 3. Run Sequence (Single-Pass Mode)
System configuration during stabilization:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards quality valve
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Stabilizing
- APC #2 (Double-Pass): Open position
System configuration when stabilized:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed to product tank
- Double-Pass Valve: Directed towards quality valve
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Stabilized
- APC #2 (Double-Pass): Open position
Operating parameters:
- High Pressure Control Valve stabilizes once desired production rate achieved
- System waits for time period to allow TDS sensor to verify PPM reading
- PPM reading below Product Quality Setpoint for 10 seconds → Quality Valve diverts to product tank
- PPM reading above setpoint for >60 seconds → High TDS Alarm
- PPM reading above setpoint for High TDS Shutdown Time → System shutdown
- Quality Valve immediately diverts overboard if water quality goes above setpoint
Monitored values:
- Low Pressure: Low Pressure Transducer reading
- High Pressure: High Pressure Transducer reading
- Brine Flow: Brine Flow Meter reading
- Product Flow: Product Flow Meter reading
- Product TDS: Product TDS meter reading
- System Temp: Temperature of product water
#### 4. Flush Sequence (Single-Pass Mode)
System configuration during delay timer:
- LPP: Off
- HPP: Off
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards quality valve
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Open position
- APC #2 (Double-Pass): Open position
System configuration during fresh water flush:
- LPP: Off
- HPP: Off
- FWF Valve: Open
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards quality valve
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Open position
- APC #2 (Double-Pass): Open position
Operating parameters:
- Stop button can be pressed at any point during system operation
- Quality Valve diverts overboard when stop pressed
- High Pressure Control Valve goes to open position
- 10 second delay prior to starting flush
- Fresh Water Flush valve opens until Fresh Water Flush Timer expires
- System returns to Home Screen in Standby Mode when complete
Monitored values:
- Timer Delay: Time in seconds prior to fresh water flush starting
- Timer: Time in seconds left in fresh water flush sequence
- Low Pressure: Low pressure transducer reading (confirms FWF pressure)
- Brine Flow: Brine flow meter reading (confirms FWF flow)
Single-Pass Mode can only be requested when current operating mode is 0.
The typical Single-Pass watermaker sequence follows this progression:
1. **Prime Sequence** → **Initialize Sequence** → **Run Sequence** → **Flush Sequence** → **Standby Mode**
### Detailed Double-Pass Mode Operation Sequence (from owners manual)
#### 1. Prime Sequence (Double-Pass Mode)
System configuration:
- LPP: On
- HPP: Off
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Open position
- APC #2 (Double-Pass): Open position
Operating parameters:
- Low pressure must be >5 PSI and <60 PSI or system will shutdown
- Prime timer countdown from setpoint (Prime Timer Setpoint)
- LPP pump status verified by Low Pressure Transducer
Monitored values:
- Timer: Time left in seconds for Prime Sequence
- Low Pressure: Low Pressure Transducer reading
- Brine Flow: Brine Flow Meter reading
#### 2. Initialize Sequence (Double-Pass Mode)
System configuration during Initialize Sequence #1:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Starting to close
- APC #2 (Double-Pass): Open position
System configuration during Initialize Sequence #2:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Starting to close
- APC #2 (Double-Pass): Starting to close
Operating parameters:
- Low pressure must be >5 PSI or system will shutdown
- High Pressure Control Valve slowly closes until desired production rate achieved
- Initialize timers countdown from setpoints (Initialize Timer Setpoints)
Monitored values:
- Timer #1: Time left in seconds for Initialize Sequence #1
- Timer #2: Time left in seconds for Initialize Sequence #2
- Low Pressure: Low Pressure Transducer reading
- High Pressure #1: First-Pass High Pressure Transducer reading
- High Pressure #2: Second-Pass High Pressure Transducer reading
- Brine Flow: Brine Flow Meter reading
- Product Flow #1: First-Pass Product Flow Meter reading
- Product Flow #2: Second-Pass Product Flow Meter reading
#### 3. Run Sequence (Double-Pass Mode)
System configuration during stabilization:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Stabilizing
- APC #2 (Double-Pass): Stabilizing
System configuration when stabilized:
- LPP: On
- HPP: On
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Stabilized
- APC #2 (Double-Pass): Stabilized
Operating parameters:
- High Pressure Control Valve stabilizes once desired production rate achieved
- Unit's production rate can be found in info section under contact screen
Monitored values:
- Low Pressure: Low Pressure Transducer reading
- High Pressure #1: First-Pass High Pressure Transducer reading
- High Pressure #2: Second-Pass High Pressure Transducer reading
- Brine Flow: Brine Flow Meter reading
- Product Flow #1: First-Pass Product Flow Meter reading
- Product Flow #2: Second-Pass Product Flow Meter reading
- Product TDS #1: First-Pass Product TDS Meter reading
- Product TDS #2: Second-Pass Product TDS Meter reading
- System Temp: Temperature of product water
#### 4. Flush Sequence (Double-Pass Mode)
System configuration during delay timer:
- LPP: Off
- HPP: Off
- FWF Valve: Closed
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Open position
- APC #2 (Double-Pass): Open position
System configuration during fresh water flush:
- LPP: Off
- HPP: Off
- FWF Valve: Open
- Quality Valve: Directed overboard
- Double-Pass Valve: Directed towards second pass
- Feed Valve: Directed towards sea water feed
- APC #1 (Single-Pass/DTS): Open position
- APC #2 (Double-Pass): Open position
Operating parameters:
- Stop button can be pressed at any point during system operation
- Quality Valve diverts overboard when stop pressed
- High Pressure Control Valve goes to open position
- 10 second delay prior to starting flush
- Fresh Water Flush valve opens until Fresh Water Flush Timer expires
- System returns to Home Screen in Standby Mode when complete
Monitored values:
- Timer Delay: Time in seconds prior to fresh water flush starting
- Timer: Time in seconds left in fresh water flush sequence
- Low Pressure: Low pressure transducer reading (confirms FWF pressure)
- Brine Flow: Brine flow meter reading (confirms FWF flow)
Double-Pass Mode can only be requested when current operating mode is 0.
The typical Double-Pass watermaker sequence follows this progression:
1. **Prime Sequence** → **Initialize Sequence #1** → **Initialize Sequence #2** → **Run Sequence** → **Flush Sequence** → **Standby Mode**
### Timer Mappings
Each DTS step with a timer has specific screen register addresses and expected durations:
| Timer Register | Operating Mode (R1036) | Screen (R1000) | Step Name | Expected Duration | Purpose |
|----------------|-----|-----|-----------|-------------------|---------|
| R138 | 0 | 34 | Step 1 | 15 seconds | Timer Active when DTS mode is initated. Timer allows valves to open |
| R128 | 1 | 5 | Step 2 | 180 seconds | Priming sequence. Shore pressured water flushes the system in DTS mode. Sea water mode LPP is turned on |
| R129 | 2 | 6 | Step 3 | 60 seconds | Initializing |
| R133 | 3 | 7 | Step 4 | 60 seconds | TDS Shutdown window. Allows TDS of product water to stabalize |
| R135 | 4/5 | 8 | Step 5 | 10 seconds | Stop sequence |
| R139 | 4/5 | 8 | Step 6 | 60 seconds | Freshwater Flush |
| R136 | 5 | 8 | Manual Fresh Water Flush | 180 seconds | Start value in seconds /10 based on R1153 |
**Note**: Screen 7 (Run) begins with a 60 second timer allowing the product water TDS to stabalize. When the timer completes the watermaker continues to operate on screen 7 until stopped.
### Control Operations by Screen
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
```bash
python -m pytest tests/
```
### Environment Setup
```bash
# 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.

219
README.md
View File

@@ -1,219 +0,0 @@
# Watermaker PLC API
RESTful API for monitoring and controlling watermaker PLC systems. Provides access to sensors, timers, controls, and watermaker operation sequences.
## Features
- **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
```bash
# 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:
```bash
export PLC_IP=198.18.100.141
export PLC_PORT=502
export DATA_UPDATE_INTERVAL=5
export LOG_LEVEL=INFO
```
### Running the API
```bash
# 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
```bash
# 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
```bash
# 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:
1. **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
```bash
python -m pytest tests/
```
### Environment Setup
```bash
# 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.

61
create-prd.mdc Normal file
View File

@@ -0,0 +1,61 @@
---
description:
globs:
alwaysApply: false
---
# Rule: Generating a Product Requirements Document (PRD)
## Goal
To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement the feature.
## Process
1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
2. **Ask Clarifying Questions:** Before writing the PRD, the AI *must* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out).
3. **Generate PRD:** Based on the initial prompt and the user's answers to the clarifying questions, generate a PRD using the structure outlined below.
4. **Save PRD:** Save the generated document as `prd-[feature-name].md` inside the `/tasks` directory.
## Clarifying Questions (Examples)
The AI should adapt its questions based on the prompt, but here are some common areas to explore:
* **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?"
* **Target User:** "Who is the primary user of this feature?"
* **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?"
* **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)"
* **Acceptance Criteria:** "How will we know when this feature is successfully implemented? What are the key success criteria?"
* **Scope/Boundaries:** "Are there any specific things this feature *should not* do (non-goals)?"
* **Data Requirements:** "What kind of data does this feature need to display or manipulate?"
* **Design/UI:** "Are there any existing design mockups or UI guidelines to follow?" or "Can you describe the desired look and feel?"
* **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?"
## PRD Structure
The generated PRD should include the following sections:
1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
2. **Goals:** List the specific, measurable objectives for this feature.
3. **User Stories:** Detail the user narratives describing feature usage and benefits.
4. **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements.
5. **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope.
6. **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable.
7. **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module").
8. **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X").
9. **Open Questions:** List any remaining questions or areas needing further clarification.
## Target Audience
Assume the primary reader of the PRD is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.
## Output
* **Format:** Markdown (`.md`)
* **Location:** `/tasks/`
* **Filename:** `prd-[feature-name].md`
## Final instructions
1. Do NOT start implementing the PRD
2. Make sure to ask the user clarifying questions
3. Take the user's answers to the clarifying questions and improve the PRD

64
generate-tasks.mdc Normal file
View File

@@ -0,0 +1,64 @@
---
description:
globs:
alwaysApply: false
---
# Rule: Generating a Task List from a PRD
## Goal
To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Product Requirements Document (PRD). The task list should guide a developer through implementation.
## Output
- **Format:** Markdown (`.md`)
- **Location:** `/tasks/`
- **Filename:** `tasks-[prd-file-name].md` (e.g., `tasks-prd-user-profile-editing.md`)
## Process
1. **Receive PRD Reference:** The user points the AI to a specific PRD file
2. **Analyze PRD:** The AI reads and analyzes the functional requirements, user stories, and other sections of the specified PRD.
3. **Phase 1: Generate Parent Tasks:** Based on the PRD analysis, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on the PRD. Ready to generate the sub-tasks? Respond with 'Go' to proceed."
4. **Wait for Confirmation:** Pause and wait for the user to respond with "Go".
5. **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the PRD.
6. **Identify Relevant Files:** Based on the tasks and PRD, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable.
7. **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
8. **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[prd-file-name].md`, where `[prd-file-name]` matches the base name of the input PRD file (e.g., if the input was `prd-user-profile-editing.md`, the output is `tasks-prd-user-profile-editing.md`).
## Output Format
The generated task list _must_ follow this structure:
```markdown
## Relevant Files
- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature).
- `path/to/file1.test.ts` - Unit tests for `file1.ts`.
- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission).
- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`.
- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations).
- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`.
### Notes
- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory).
- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration.
## Tasks
- [ ] 1.0 Parent Task Title
- [ ] 1.1 [Sub-task description 1.1]
- [ ] 1.2 [Sub-task description 1.2]
- [ ] 2.0 Parent Task Title
- [ ] 2.1 [Sub-task description 2.1]
- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)
```
## Interaction Model
The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.
## Target Audience
Assume the primary reader of the task list is a **junior developer** who will implement the feature.

38
process-task-list.mdc Normal file
View File

@@ -0,0 +1,38 @@
---
description:
globs:
alwaysApply: false
---
# Task List Management
Guidelines for managing task lists in markdown files to track progress on completing a PRD
## Task Implementation
- **One sub-task at a time:** Do **NOT** start the next sub‑task until you ask the user for permission and they say “yes” or "y"
- **Completion protocol:**
1. When you finish a **sub‑task**, immediately mark it as completed by changing `[ ]` to `[x]`.
2. If **all** subtasks underneath a parent task are now `[x]`, also mark the **parent task** as completed.
- Stop after each sub‑task and wait for the user’s go‑ahead.
## Task List Maintenance
1. **Update the task list as you work:**
- Mark tasks and subtasks as completed (`[x]`) per the protocol above.
- Add new tasks as they emerge.
2. **Maintain the “Relevant Files” section:**
- List every file created or modified.
- Give each file a one‑line description of its purpose.
## AI Instructions
When working with task lists, the AI must:
1. Regularly update the task list file after finishing any significant work.
2. Follow the completion protocol:
- Mark each finished **sub‑task** `[x]`.
- Mark the **parent task** `[x]` once **all** its subtasks are `[x]`.
3. Add newly discovered tasks.
4. Keep “Relevant Files” accurate and up to date.
5. Before starting work, check which sub‑task is next.
6. After implementing a sub‑task, update the file and then pause for user approval.