samastek/Tempering-Machine-Control-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive data management and configuration specification documentation; introduce analysis of tempering machine control system architecture and behavior

Browse Source
This commit is contained in:
Sami Alzein
2025-08-06 21:35:53 +02:00
parent f539289f45
commit 4a49f78da4
6 changed files with 2338 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
docs/01-system-overview.md Normal file
View File

@@ -0,0 +1,203 @@
# System Overview - Chocolate Tempering Machine Control System
## Executive Summary
This is an industrial chocolate tempering machine control system that manages the precise heating, cooling, and pouring processes required for chocolate tempering. The system runs on a single-board computer with a touch interface and communicates with hardware via Modbus RTU over serial communication.
## High-Level Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ AVALONIA UI LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────────────┐ │
│ │ Home │ │ Settings │ │ Diagnostics │ │
│ │ Screen │ │ Screen │ │ Screen │ │
│ └─────────────┘ └─────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ CONTROL LOGIC LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ Recipe │ │ Motor │ │ Temperature │ │
│ │ Manager │ │ Controller │ │ Controller │ │
│ └──────────────┘ └──────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ COMMUNICATION LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ Modbus │ │ Serial │ │ Queue │ │
│ │ Master │ │ Port │ │ Manager │ │
│ └──────────────┘ └──────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ HARDWARE LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ Temperature │ │ Motors │ │ I/O │ │
│ │ Sensors │ │ & Pumps │ │ Controls │ │
│ └──────────────┘ └──────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## System Components
### 1. User Interface Layer
- **Technology**: Avalonia UI (.NET 8)
- **Purpose**: Touch-based operator interface
- **Key Features**:
- Recipe selection and management
- Real-time temperature monitoring
- Motor control and status
- Error display and diagnostics
- Auto-dimming and power management
### 2. Control Logic Layer
- **Architecture**: Multi-threaded event-driven system
- **Key Components**:
- Recipe execution engine
- Temperature control system
- Motor coordination logic
- Safety and error handling
### 3. Communication Layer
- **Protocol**: Modbus RTU over RS-485
- **Features**:
- Queue-based message handling
- Automatic retry with exponential backoff
- CRC validation
- Timeout management
### 4. Data Persistence Layer
- **Technology**: CSV files
- **Storage**:
- Recipe definitions
- Machine configuration
- Hardware mapping
- PID parameters
## Threading Model
```
MainWindow Process
├── MonitorPortsLoop Thread (Priority: Highest)
│ ├── Hardware Communication
│ ├── Recipe Phase Management
│ ├── Temperature Monitoring
│ └── Motor Control
├── ScreenLoop Thread
│ ├── Error Handling
│ ├── UI State Management
│ └── Button Enable/Disable Logic
├── InteractiveUILoop Thread
│ ├── Visual Feedback
│ └── Status Indicators
├── TouchLoop Thread
│ ├── Activity Tracking
│ └── Screen Dimming
├── CheckInternetLoop Thread
│ └── Network Connectivity
└── SerialThreadLoop Thread
├── Queue Management
├── Message Retry Logic
└── Communication Timing
```
## Key Business Processes
### 1. Chocolate Tempering Process
The system follows a precise three-phase tempering process:
```
Pre-heating → Heating → Cooling → Pouring → Complete
│ │ │ │
▼ ▼ ▼ ▼
Warm up Reach goal Cool to Maintain
hardware temperature precise pouring
to working temp temperature
temperature
```
### 2. Motor Coordination
Multiple motors must be coordinated for proper operation:
- **Mixer Motor**: Tank agitation
- **Fountain Motor**: Chocolate circulation
- **Pump Motors**: Fluid transfer
- **Vibrator**: Mold preparation
- **Compressor**: Cooling system
### 3. Safety Systems
- Real-time error monitoring
- Automatic motor shutoff on errors
- Temperature limit enforcement
- Communication timeout handling
- Grid power monitoring
## Deployment Architecture
```
┌─────────────────────────────────────────┐
│ Single Board Computer │
│ ┌─────────────────────────────────────┐│
│ │ Linux Operating System ││
│ │ ┌─────────────────────────────────┐││
│ │ │ .NET 8 Runtime │││
│ │ │ ┌─────────────────────────────┐│││
│ │ │ │ Avalonia Application ││││
│ │ │ └─────────────────────────────┘│││
│ │ └─────────────────────────────────┘││
│ └─────────────────────────────────────┘│
│ │ │
│ Serial Port │
└─────────────────────────────────────────┘
│
RS-485 Interface
│
┌─────────────────────────────────────────┐
│ Industrial Hardware │
│ ┌───────────┐ ┌─────────┐ ┌────────────┐│
│ │Temperature│ │ Motors │ │ I/O ││
│ │ Sensors │ │& Pumps │ │ Controls ││
│ └───────────┘ └─────────┘ └────────────┘│
└─────────────────────────────────────────┘
```
## Critical System Requirements
### Performance Requirements
- **Real-time Response**: < 100ms for safety-critical operations
- **Temperature Accuracy**: ±0.1°C measurement precision
- **Communication Latency**: < 500ms for Modbus operations
- **UI Responsiveness**: < 50ms touch response time
### Reliability Requirements
- **Uptime**: 99.9% availability during production hours
- **Error Recovery**: Automatic recovery from communication failures
- **Data Integrity**: No loss of configuration or recipe data
- **Safety**: Fail-safe operation on any system error
### Environmental Requirements
- **Operating Temperature**: 0°C to 50°C
- **Humidity**: 10% to 90% non-condensing
- **Vibration**: Industrial environment tolerance
- **Power**: 24V DC industrial power supply
## Migration Considerations
### Current Architecture Issues
1. **Monolithic Design**: Single large class handling multiple concerns
2. **Thread Safety**: Shared state without proper synchronization
3. **Error Handling**: Inconsistent exception management
4. **Testing**: No unit tests for critical control logic
5. **Configuration**: CSV-based storage lacks validation
6. **Communication**: Limited error recovery mechanisms
### Recommended Target Architecture
1. **Microservices**: Separate services for UI, control, and communication
2. **Message Queue**: Decoupled communication between components
3. **Database**: Structured configuration and recipe storage
4. **State Machine**: Formal recipe phase management
5. **Logging**: Comprehensive system monitoring
6. **Testing**: Full test coverage for control logic
This specification provides the foundation for understanding the current system and planning a migration to a more maintainable and robust architecture.

300
docs/02-hardware-communication.md Normal file
View File

@@ -0,0 +1,300 @@
# Hardware Communication Specification
## Overview
The system communicates with industrial hardware using Modbus RTU protocol over RS-485 serial communication. This document details the communication architecture, protocols, and data structures.
## Communication Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Recipe │ │ Motor │ │ Temperature │ │
│ │ Control │ │ Control │ │ Control │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ COMMUNICATION LAYER │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Write │────▶│ Queue │────▶│ Read │ │
│ │ Queue │ │ Manager │ │ Queue │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Serial Thread │ │
│ │ (Queue Processor) │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ MODBUS RTU LAYER │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Message │ │ CRC │ │ Timeout │ │
│ │ Framing │ │ Validation │ │ Handling │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ PHYSICAL LAYER │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Serial Port │─────RS485────│ Hardware │ │
│ │ Driver │ │ Controller │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Modbus RTU Implementation
### Supported Function Codes
| Function Code | Name | Purpose | Usage in System |
|---------------|------|---------|-----------------|
| 0x01 | Read Coils | Read discrete outputs | Motor status monitoring |
| 0x03 | Read Holding Registers | Read output registers | System status, setpoints |
| 0x04 | Read Input Registers | Read input registers | Temperature sensors, digital inputs |
| 0x05 | Write Single Coil | Write single output | Individual motor control |
| 0x06 | Write Single Register | Write single register | Individual setpoint updates |
| 0x0F | Write Multiple Coils | Write multiple outputs | Batch motor control |
| 0x10 | Write Multiple Registers | Write multiple registers | Configuration updates |
### Message Structure
```
Standard Modbus RTU Frame:
┌──────────┬─────────────┬──────────────┬──────────┬──────────┐
│ Slave ID │ Function │ Data │ CRC-16 │ End │
│ (1 byte) │ Code │ (N bytes) │ (2 bytes)│ Frame │
│ │ (1 byte) │ │ │ │
└──────────┴─────────────┴──────────────┴──────────┴──────────┘
Example - Read Input Registers:
┌──────────┬─────────────┬──────────┬──────────┬──────────┬──────────┐
│ 0x01 │ 0x04 │ 0x00 │ 0x00 │ 0x00 │ 0x12 │
│ Slave ID │ Read Input │ Start │ Start │ Number │ Number │
│ │ Registers │ Addr Hi │ Addr Lo │ Regs Hi │ Regs Lo │
└──────────┴─────────────┴──────────┴──────────┴──────────┴──────────┘
```
### CRC-16 Calculation
The system implements Modbus standard CRC-16 calculation:
```
Algorithm: CRC-16-IBM (polynomial 0xA001)
Initial Value: 0xFFFF
Final XOR: None
Bit Order: LSB first
```
## Register Mapping
### Holding Registers (Write/Read)
| Address | Name | Type | Range | Units | Purpose |
|---------|------|------|-------|-------|---------|
| 0 | Reset Error | uint16 | 0-65535 | Bitfield | Error reset flags |
| 1 | HV Output | uint16 | 0-65535 | Bitfield | High voltage outputs |
| 2 | LV Output | uint16 | 0-65535 | Bitfield | Low voltage outputs |
| 3 | Motor Control | uint16 | 0-65535 | Bitfield | Motor on/off states |
| 4-5 | Set Temperature 1 | int32 | -10000 to 6500 | Deciselsius | Tank bottom heater |
| 6-7 | Set Temperature 2 | int32 | -10000 to 6500 | Deciselsius | Tank wall heater |
| 8-9 | Set Temperature 3 | int32 | -10000 to 6500 | Deciselsius | Pump heater |
| 10-11 | Set Temperature 4 | int32 | -10000 to 6500 | Deciselsius | Fountain heater |
### Input Registers (Read Only)
| Address | Name | Type | Range | Units | Purpose |
|---------|------|------|-------|-------|---------|
| 0 | Board Flags | uint16 | 0-65535 | Bitfield | System status flags |
| 1 | Input States | uint16 | 0-65535 | Bitfield | Digital input states |
| 2-4 | Grid Voltages | uint16 | 0-3000 | Volts | L1, L2, L3 voltages |
| 5 | Neutral Current | uint16 | 0-1000 | Deciselsius | Neutral line current |
| 6-7 | Motor Currents | uint16 | 0-1000 | Deciselsius | Motor 1, 2 currents |
| 8-11 | Temperatures | int16 | -1400 to 650 | Deciselsius | T1, T2, T3, T4 readings |
| 12-13 | Analog Inputs | uint16 | 0-65535 | Raw ADC | General purpose analog |
| 14-15 | System Temps | uint16 | 0-1000 | Deciselsius | Heat sink, internal |
| 16 | External Power | uint16 | 0-1000 | Deciselsius | External power voltage |
| 17 | Grid Frequency | uint16 | 0-1000 | Decideciseconds | Line frequency |
## Hardware Mapping System
### Mapping Configuration
The system uses a CSV-based mapping file to associate logical names with hardware addresses:
```csv
Id,Name,Address,IsRead,BitNumbers
1,Pedal,1,1,0
2,Cover Sensor,1,1,1
3,E-Stop,1,1,2
4,Tank Bottom Temp,8,1,8
5,Tank Wall Temp,9,1,9
6,Pump Temp,10,1,10
7,Fountain Temp,11,1,11
8,Vibrator Heater,2,0,0
9,Mold Heater,2,0,1
10,Alarm,2,0,2
11,Vibrator,1,0,0
12,Mixer,3,0,0
13,Pump,3,0,1
```
### Bit Field Operations
Motor control uses bit manipulation for individual motor control:
```
Motor Control Register (Address 3):
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│15 │14 │13 │12 │11 │10 │ 9 │ 8 │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─ Mixer
│ │ │ │ │ │ │ │ │ │ │ │ │ │ └───── Pump
│ │ │ │ │ │ │ │ │ │ │ │ │ └─────── Helix
│ │ │ │ │ │ │ │ │ │ │ │ └─────────── Reserved
│ │ │ │ │ │ │ │ │ │ │ └───────────────── Reserved
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴─────────────────────── Reserved
```
### Temperature Data Format
Temperature values are transmitted as signed 16-bit integers in deciselsius:
```
Temperature Conversion:
Raw Value: -273 (deciselsius)
Actual Temperature: -27.3°C
Special Values:
-10000: Heater disabled/off
Values > 6500: Invalid/error condition
Values < -1400: Sensor error
```
## Communication Timing
### Message Scheduling
```
Communication Timeline:
┌─────────────────────────────────────────────────────────────┐
│ Message Cycle │
│ │
│ ┌─────┐ ┌──────┐ ┌─────┐ ┌──────────────────────┐ │
│ │Write│ │ 4-Char│ │Read │ │ Wait for Next │ │
│ │ Req │ │ Delay │ │Resp │ │ Cycle │ │
│ └─────┘ └──────┘ └─────┘ └──────────────────────┘ │
│ │ │ │ │ │
│ 10ms varies 50ms configurable │
│ │ │
│ Based on baud rate │
│ (4 chars * 11 bits/char) / baud │
└─────────────────────────────────────────────────────────────┘
```
### Retry Logic
```
Retry Sequence:
Attempt 1 ──┐
│ Failure
▼
Wait 1s ──┐
│
Attempt 2 ─────────┘──┐
│ Failure
▼
Wait 1s ──┐
│
Attempt 3 ───────────────────┘──┐
│ Failure
▼
Set Error Flag
(Communication Timeout)
```
### Error Detection and Recovery
| Error Condition | Detection Method | Recovery Action |
|-----------------|------------------|-----------------|
| CRC Mismatch | Frame validation | Immediate retry |
| Timeout | No response in 1s | Retry up to 3 times |
| Invalid Length | Frame size check | Discard and retry |
| Communication Loss | 3+ consecutive failures | Set error flag, continue retrying |
| Port Error | Serial port exception | Reset port, retry |
## Queue Management
### Write Queue (Priority Operations)
```
Write Queue Structure:
┌─────────────────────────────────────────────────────────────┐
│ Priority: Motor Control, Temperature Setpoints, Errors │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Motor │ │ Temperature │ │ Error │ │
│ │ Commands │ │ Setpoints │ │ Reset │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │ │
│ └───────────────┼─────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Serial Transmit │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Read Queue (Monitoring Operations)
```
Read Queue Structure:
┌─────────────────────────────────────────────────────────────┐
│ Regular Monitoring: Sensors, Status, Diagnostics │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Temperature │ │ Digital │ │ Analog │ │
│ │ Sensors │ │ Inputs │ │ Inputs │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │ │
│ └───────────────┼─────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Process Response│ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Configuration Parameters
### Serial Port Settings
| Parameter | Default | Range | Description |
|-----------|---------|-------|-------------|
| Baud Rate | 9600 | 1200-115200 | Communication speed |
| Data Bits | 8 | 7-8 | Character size |
| Stop Bits | 1 | 1-2 | Frame termination |
| Parity | None | None/Odd/Even/Mark/Space | Error detection |
| Timeout | 1000ms | 100-5000ms | Response timeout |
| Retry Count | 3 | 1-10 | Maximum retry attempts |
| Send Interval | 100ms | 50-1000ms | Minimum time between messages |
### Modbus Parameters
| Parameter | Default | Description |
|-----------|---------|-------------|
| Slave ID | 1 | Target device address |
| Function Codes | 0x01,0x03,0x04,0x05,0x06,0x0F,0x10 | Supported operations |
| Max Register Count | 125 | Maximum registers per request |
| CRC Validation | Enabled | Frame integrity checking |
| Broadcast Support | Disabled | Multi-device communication |
This communication specification provides the complete details needed to implement a robust Modbus RTU communication system for the tempering machine hardware interface.

440
docs/03-recipe-management.md Normal file
View File

@@ -0,0 +1,440 @@
# Recipe Management and Control Logic Specification
## Overview
The recipe management system controls the chocolate tempering process through a sophisticated three-phase state machine. This document details the recipe structure, phase transitions, temperature control logic, and timing mechanisms.
## Recipe Data Structure
### Recipe Definition
```
Recipe Entity:
┌─────────────────────────────────────────────────────────────┐
│ Recipe │
├─────────────────────────────────────────────────────────────┤
│ + ID: int │
│ + Name: string │
│ + HeatingGoal: float (°C) │
│ + CoolingGoal: float (°C) │
│ + PouringGoal: float (°C) │
│ + TankTemp: float (°C) │
│ + FountainTemp: float (°C) │
│ + Mixer: boolean │
│ + Fountain: boolean │
│ + MoldHeater: boolean │
│ + Vibration: boolean │
│ + VibHeater: boolean │
│ + Pedal: boolean (true=manual, false=auto) │
│ + PedalOnTime: int (seconds) │
│ + PedalOffTime: int (seconds) │
└─────────────────────────────────────────────────────────────┘
```
### Temperature Validation Rules
```
Temperature Constraints:
┌─────────────────────────────────────────────────────────────┐
│ Heating Goal: 40°C ≤ HeatingGoal ≤ 60°C │
│ Cooling Goal: 20°C ≤ CoolingGoal ≤ 40°C │
│ Pouring Goal: CoolingGoal ≤ PouringGoal ≤ HeatingGoal │
│ │
│ Logical Constraint: CoolingGoal < HeatingGoal │
│ Safety Constraint: All goals within machine limits │
└─────────────────────────────────────────────────────────────┘
```
## Recipe State Machine
### Phase Overview
```
Recipe Execution Flow:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Pre-heating │───▶│ Heating │───▶│ Cooling │───▶│ Pouring │
│ Phase │ │ Phase │ │ Phase │ │ Phase │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Warm up │ │ Reach target│ │ Cool to │ │ Maintain │
│ hardware to │ │ heating │ │ cooling │ │ pouring │
│ operational │ │ temperature │ │ temperature │ │ temperature │
│ temperature │ │ with delay │ │ with delay │ │ for process │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```
### State Definitions
| State Value | Name | Description |
|-------------|------|-------------|
| -1 | Off/Inactive | Phase not started or completed |
| 1 | Active | Phase is currently running |
| 10 | Paused | Phase is temporarily suspended |
### Phase Transition Conditions
```
State Transition Matrix:
┌─────────────────────────────────────┐
│ CONDITIONS │
├─────────────────────────────────────┤
Pre-heating ───────▶│ Tank >= TankMaxHeat AND │───────▶ Heating
│ Pump >= PumpMaxHeat │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ CONDITIONS │
├─────────────────────────────────────┤
Heating ───────────▶│ Fountain >= HeatingGoal AND │───────▶ Cooling
│ HeatingDelay timer expires │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ CONDITIONS │
├─────────────────────────────────────┤
Cooling ───────────▶│ Fountain <= CoolingGoal AND │───────▶ Pouring
│ CoolingDelay timer expires │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ CONDITIONS │
├─────────────────────────────────────┤
Pouring ───────────▶│ Fountain = PouringGoal AND │───────▶ Complete
│ PouringDelay timer expires │
└─────────────────────────────────────┘
```
## Temperature Control System
### Temperature Zones
```
Temperature Zone Layout:
┌─────────────────────────────────────────────────────────────┐
│ TEMPERING SYSTEM │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MIXING TANK │ │
│ │ ┌───────────┐ ┌───────────┐ │ │
│ │ │Tank Bottom│ │Tank Wall │ │ │
│ │ │ Heater │ │ Heater │ │ │
│ │ │(Zone 1) │ │(Zone 2) │ │ │
│ │ └───────────┘ └───────────┘ │ │
│ └─────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌─────────────▼───────────────────────────────────────┐ │
│ │ PUMP SYSTEM │ │
│ │ ┌───────────┐ │ │
│ │ │ Pump │ │ │
│ │ │ Heater │ │ │
│ │ │(Zone 3) │ │ │
│ │ └───────────┘ │ │
│ └─────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌─────────────▼───────────────────────────────────────┐ │
│ │ FOUNTAIN SYSTEM │ │
│ │ ┌───────────┐ │ │
│ │ │ Fountain │ │ │
│ │ │ Heater │ │ │
│ │ │(Zone 4) │ │ │
│ │ └───────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Temperature Setpoint Calculation
```
Phase-Specific Setpoints:
Pre-heating Phase:
┌─────────────────────────────────────────────────────────────┐
│ Zone 1 (Tank Bottom): Machine.TankMaxHeat │
│ Zone 2 (Tank Wall): Machine.TankMaxHeat │
│ Zone 3 (Pump): Machine.PumpMaxHeat │
│ Zone 4 (Fountain): -10000 (Disabled) │
└─────────────────────────────────────────────────────────────┘
Heating Phase:
┌─────────────────────────────────────────────────────────────┐
│ Zone 1 (Tank Bottom): Machine.TankMaxHeat │
│ Zone 2 (Tank Wall): Machine.TankMaxHeat │
│ Zone 3 (Pump): Machine.PumpMaxHeat │
│ Zone 4 (Fountain): Recipe.HeatingGoal │
└─────────────────────────────────────────────────────────────┘
Cooling Phase:
┌─────────────────────────────────────────────────────────────┐
│ Zone 1 (Tank Bottom): -10000 (Disabled) │
│ Zone 2 (Tank Wall): -10000 (Disabled) │
│ Zone 3 (Pump): Machine.PumpMinHeat │
│ Zone 4 (Fountain): Recipe.CoolingGoal │
└─────────────────────────────────────────────────────────────┘
Pouring Phase:
┌─────────────────────────────────────────────────────────────┐
│ Zone 1 (Tank Bottom): Recipe.PouringGoal + PreHeatingTemp │
│ Zone 2 (Tank Wall): Recipe.PouringGoal + PreHeatingTemp │
│ Zone 3 (Pump): -10000 (Disabled) │
│ Zone 4 (Fountain): Recipe.PouringGoal │
└─────────────────────────────────────────────────────────────┘
```
### Error Tolerance Zones
```
Temperature Error Detection:
Heating Phase:
┌─────────────────────────────────────────────────────────────┐
│ Error Condition: Temperature < (Goal - ErrorLimit) │
│ Warning Zone: Goal - WarningLimit to Goal - ErrorLimit │
│ OK Zone: Temperature >= Goal - ErrorLimit │
└─────────────────────────────────────────────────────────────┘
Cooling Phase:
┌─────────────────────────────────────────────────────────────┐
│ Error Condition: Temperature > (Goal + ErrorLimit) │
│ Warning Zone: Goal + ErrorLimit to Goal + WarningLimit │
│ OK Zone: Temperature <= Goal + ErrorLimit │
└─────────────────────────────────────────────────────────────┘
Pouring Phase:
┌─────────────────────────────────────────────────────────────┐
│ Error Condition: |Temperature - Goal| > ErrorLimit │
│ Warning Zone: ErrorLimit < |Temp - Goal| < WarningLimit │
│ OK Zone: |Temperature - Goal| <= ErrorLimit │
└─────────────────────────────────────────────────────────────┘
```
## Timer Management System
### Timer Types and Purposes
```
Timer Hierarchy:
┌─────────────────────────────────────────────────────────────┐
│ RECIPE TIMERS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Heating │ │ Cooling │ │ Pouring │ │
│ │ Timer │ │ Timer │ │ Timer │ │
│ │ │ │ │ │ │ │
│ │ Counts down │ │ Counts down │ │ Counts down │ │
│ │ heating │ │ cooling │ │ pouring delay │ │
│ │ delay after │ │ delay after │ │ after reaching │ │
│ │ reaching │ │ reaching │ │ pouring goal │ │
│ │ goal temp │ │ goal temp │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Mixer │ │ Fountain │ │ Pedal │ │
│ │ Timer │ │ Timer │ │ Timers │ │
│ │ │ │ │ │ │ │
│ │ Delays │ │ Delays │ │ ┌─────────────────┐ │ │
│ │ mixer │ │ fountain │ │ │ PedalOn │ │ │
│ │ startup │ │ startup │ │ │ Timer │ │ │
│ │ until temp │ │ until temp │ │ └─────────────────┘ │ │
│ │ reached │ │ reached │ │ ┌─────────────────┐ │ │
│ │ │ │ │ │ │ PedalOff │ │ │
│ │ │ │ │ │ │ Timer │ │ │
│ │ │ │ │ │ └─────────────────┘ │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Timer Configuration
| Timer Name | Default Duration | Configuration Source | Purpose |
|------------|------------------|---------------------|---------|
| HeatingTimer | Machine.HeatingDelay | Machine.csv | Delay after reaching heating goal |
| CoolingTimer | Machine.CoolingDelay | Machine.csv | Delay after reaching cooling goal |
| PouringTimer | Machine.PouringDelay | Machine.csv | Delay after reaching pouring goal |
| MixerTimer | Machine.MixerDelay | Machine.csv | Delay before starting mixer |
| FountainTimer | Machine.PumpDelay | Machine.csv | Delay before starting fountain |
| PedalOnTimer | Recipe.PedalOnTime | Recipe.csv | Auto mode on duration |
| PedalOffTimer | Recipe.PedalOffTime | Recipe.csv | Auto mode off duration |
### Timer State Machine
```
Timer Lifecycle:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Created │───▶│ Started │───▶│ Running │───▶│ Expired │
│ │ │ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│ │ │ │
│ │ ▼ │
│ │ ┌─────────────┐ │
│ │ │ Paused │ │
│ │ │ │ │
│ │ └─────────────┘ │
│ │ │ │
│ └──────────────────┘ │
│ │
└────────────────────────────────────────────────────────┘
Reset/Cleanup
```
## Motor Coordination Logic
### Motor Dependencies
```
Motor Coordination Matrix:
Mixer Fountain Vibrator Compressor
Recipe Start Yes Yes Optional Auto
Pre-heating Yes Yes No Auto
Heating Phase Yes Yes Optional Auto
Cooling Phase Yes Yes Optional Yes
Pouring Phase Yes Yes Optional Auto
Error Condition No No No Auto
Motor Startup Sequence:
┌─────────────────────────────────────────────────────────────┐
│ 1. Check temperature prerequisites │
│ 2. Check error conditions │
│ 3. Start mixer (if temperature OK) │
│ 4. Delay based on MixerDelay │
│ 5. Start fountain (if pump temperature OK) │
│ 6. Delay based on PumpDelay │
│ 7. Enable pedal control │
└─────────────────────────────────────────────────────────────┘
```
### Motor Safety Logic
```
Safety Interlocks:
┌─────────────────────────────────────────────────────────────┐
│ SAFETY CONDITIONS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Temperature │ │ Error │ │ Manual │ │
│ │ Limits │ │ Conditions │ │ Override │ │
│ │ │ │ │ │ │ │
│ │ • Tank too │ │ • Grid │ │ • Emergency │ │
│ │ cold │ │ errors │ │ stop │ │
│ │ • Pump too │ │ • Comm │ │ • Maintenance │ │
│ │ cold │ │ timeout │ │ mode │ │
│ │ • Over temp │ │ • Motor │ │ │ │
│ │ protection│ │ overload │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └──────────────────┼────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Motor Control │ │
│ │ Decision │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Pedal Control Modes
### Manual Pedal Mode
```
Manual Mode Operation:
┌─────────────────────────────────────────────────────────────┐
│ User Input ──▶ Pedal State ──▶ Fountain Motor Control │
│ │
│ Pedal Pressed: │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Digital │───▶│ Input │───▶│ Fountain │ │
│ │ Input │ │ Processing │ │ Motor ON │ │
│ │ Reading │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │
│ Pedal Released: │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Digital │───▶│ Input │───▶│ Fountain │ │
│ │ Input │ │ Processing │ │ Motor OFF │ │
│ │ Reading │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Automatic Pedal Mode
```
Auto Mode Timing Cycle:
┌─────────────────────────────────────────────────────────────┐
│ TIME SEQUENCE │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ ON │───▶│ OFF │───▶│ ON │ │
│ │ Period │ │ Period │ │ Period │ │
│ │ │ │ │ │ │ │
│ │ Fountain │ │ Fountain │ │ Fountain │ │
│ │ Motor ON │ │ Motor OFF │ │ Motor ON │ │
│ │ │ │ │ │ │ │
│ │ Duration: │ │ Duration: │ │ Duration: │ │
│ │PedalOnTime │ │PedalOffTime │ │ PedalOnTime │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │
│ Timer Countdown Display: │
│ "Pedal ON: 15" or "Pedal OFF: 8" │
└─────────────────────────────────────────────────────────────┘
```
## Error Handling in Recipe Execution
### Error Classification
| Error Level | Action | Recipe Impact |
|-------------|--------|---------------|
| Warning | Display message | Continue execution |
| Minor Error | Pause recipe | Resume when cleared |
| Critical Error | Stop recipe | Manual restart required |
| Safety Error | Emergency stop | System reset required |
### Recipe Pause/Resume Logic
```
Pause/Resume State Machine:
┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐
│ Running │───▶│ Paused │───▶│ Resumed │
│ (State=1) │ │ (State=10) │ │ (State=1) │
└─────────────┘ └─────────────┘ └─────────────────────┘
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Timers │ │
│ │ Suspended │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────┘
Continue/Stop
```
### Temperature Warning System
```
Temperature Warning Flow:
┌─────────────────────────────────────────────────────────────┐
│ Temperature Reading ──▶ Check Against Limits │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Within │ │ Warning │ │ Error │ │
│ │ Limits │ │ Zone │ │ Zone │ │
│ │ │ │ │ │ │ │
│ │ Continue │ │ Show │ │ Pause Recipe │ │
│ │ Operation │ │ Warning │ │ Show Error │ │
│ │ │ │ Continue │ │ Wait for User │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ User Decision: │ │
│ │ • Accept Risk │ │
│ │ • Stop Recipe │ │
│ │ • Wait & Retry │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
This recipe management specification provides complete details for implementing a robust chocolate tempering control system with proper state management, safety features, and error handling.

539
docs/04-user-interface.md Normal file
View File

@@ -0,0 +1,539 @@
# User Interface and Screen Management Specification
## Overview
The user interface is built with Avalonia UI and provides a touch-based operator interface for controlling the chocolate tempering machine. This document details the UI architecture, screen navigation, and user interaction patterns.
## UI Architecture
### Screen Hierarchy
```
Application Structure:
┌─────────────────────────────────────────────────────────────┐
│ MainWindow │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Navigation Bar │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │
│ │ │Home │ │Recipe│ │Settings│ │Manual│ │Diag │ │Admin│ │Help │ │ │
│ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Content Area │ │
│ │ │ │
│ │ [Dynamic Content Views] │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Footer Bar │ │
│ │ ┌─────────┐ ┌─────────────┐ ┌─────────┐ ┌─────────────┐ │ │
│ │ │ Status │ │ Temperature │ │ Errors │ │ Date/Time │ │ │
│ │ │Message │ │ Display │ │ Icons │ │ Display │ │ │
│ │ └─────────┘ └─────────────┘ └─────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Screen Navigation Flow
```
Navigation State Machine:
┌─────────────┐
│ Home │
│ Screen │
└─────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Recipe │ │ Settings │ │ Manual │
│ Selection │ │ Screen │ │ Control │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ │ │
┌─────────────┐ │ │
│ Recipe │ │ │
│ Editor │ │ │
└─────────────┘ │ │
│ │
┌──────────────────┼──────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Diagnostics │ │ Admin │
│ Screen │ │ Screen │
└─────────────┘ └─────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Advanced │ │ Software │
│ Settings │ │ Config │
└─────────────┘ └─────────────┘
```
## Screen Specifications
### 1. Home Screen
```
Home Screen Layout:
┌─────────────────────────────────────────────────────────────┐
│ HOME SCREEN │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ USER SELECTION │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ OPERATOR │ │ TECHNICIAN│ │ ADMIN │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ [User Icon] │ │ [User Icon] │ │ [User Icon] │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SYSTEM STATUS │ │
│ │ │ │
│ │ • Machine Status: Ready/Running/Error │ │
│ │ • Last Recipe: [Recipe Name] │ │
│ │ • System Temperature: [Temp]°C │ │
│ │ • Communication: Connected/Disconnected │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Purpose: User authentication and system overview
Access: Public (no authentication required)
Navigation: Entry point to all other screens
```
### 2. Settings Screen (Recipe Execution)
```
Settings Screen Layout:
┌─────────────────────────────────────────────────────────────┐
│ SETTINGS SCREEN │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ RECIPE INFORMATION │ │
│ │ Recipe: [Current Recipe Name] │ │
│ │ Heating Goal: XX°C Cooling Goal: XX°C │ │
│ │ Pouring Goal: XX°C │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ TEMPERATURE DISPLAY │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Tank │ │ Fountain │ │ │
│ │ │ XX.X°C │ │ XX.X°C │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MOTOR CONTROLS │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Mixer │ │ Fountain │ │ │
│ │ │ [ON /OFF] │ │ [ON /OFF] │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Vibrator │ │ Pre-Heating │ │ │
│ │ │ [ON /OFF] │ │ [ON /OFF] │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ RECIPE CONTROL │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ [START RECIPE] │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Purpose: Recipe execution and real-time control
Access: Operator level and above
Key Features:
- Real-time temperature monitoring
- Motor control buttons
- Recipe start/stop control
- Visual status indicators
```
### 3. Recipe Selection Screen
```
Recipe Selection Layout:
┌─────────────────────────────────────────────────────────────┐
│ RECIPE SELECTION │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ RECIPE LIST │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────┐ │ │
│ │ │ Recipe Name: MILK CHOCOLATE │ │ │
│ │ │ Heating: 46°C Cooling: 27°C Pouring: 30°C │ │ │
│ │ │ Status: Available [SELECT] [EDIT] │ │ │
│ │ └───────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────┐ │ │
│ │ │ Recipe Name: DARK CHOCOLATE │ │ │
│ │ │ Heating: 50°C Cooling: 29°C Pouring: 32°C │ │ │
│ │ │ Status: Available [SELECT] [EDIT] │ │ │
│ │ └───────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────┐ │ │
│ │ │ Recipe Name: WHITE CHOCOLATE │ │ │
│ │ │ Heating: 45°C Cooling: 26°C Pouring: 29°C │ │ │
│ │ │ Status: Available [SELECT] [EDIT] │ │ │
│ │ └───────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ RECIPE ACTIONS │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ CREATE │ │ DELETE │ │ │
│ │ │ NEW RECIPE │ │ RECIPE │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Purpose: Recipe management and selection
Access: Operator level and above
Features:
- Recipe list with parameters
- Create/Edit/Delete operations
- Recipe validation
```
### 4. Manual Control Screen
```
Manual Control Layout:
┌─────────────────────────────────────────────────────────────┐
│ MANUAL CONTROL │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MOTOR CONTROLS │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ MIXER │ │ FOUNTAIN │ │ VIBRATOR │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ │
│ │ │ │ ON │ │ │ │ ON │ │ │ │ ON │ │ │ │
│ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ │
│ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ │
│ │ │ │ OFF │ │ │ │ OFF │ │ │ │ OFF │ │ │ │
│ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ HEATER CONTROLS │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │MOLD HEATER │ │VIB HEATER │ │ALARM │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ │
│ │ │ │ ON │ │ │ │ ON │ │ │ │ ON │ │ │ │
│ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ │
│ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │ │
│ │ │ │ OFF │ │ │ │ OFF │ │ │ │ OFF │ │ │ │
│ │ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ TEMPERATURE READINGS │ │
│ │ │ │
│ │ Tank: XX.X°C Pump: XX.X°C │ │
│ │ Fountain: XX.X°C Wall: XX.X°C │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Purpose: Direct hardware control without recipes
Access: Technician level and above
Features:
- Individual motor control
- Heater control
- Real-time temperature display
- Safety interlocks
```
### 5. Diagnostics Screen
```
Diagnostics Layout:
┌─────────────────────────────────────────────────────────────┐
│ DIAGNOSTICS │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ SYSTEM STATUS │ │
│ │ │ │
│ │ Grid Status: [●] Normal [○] Error │ │
│ │ Communication: [●] Connected [○] Timeout │ │
│ │ Motors: [●] Normal [○] Overload │ │
│ │ Temperature: [●] Normal [○] Out of Range │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ POWER MONITORING │ │
│ │ │ │
│ │ L1 Voltage: XXX V L2 Voltage: XXX V │ │
│ │ L3 Voltage: XXX V Frequency: XX.X Hz │ │
│ │ Neutral Current: XX.X A │ │
│ │ Motor 1 Current: XX.X A │ │
│ │ Motor 2 Current: XX.X A │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ I/O STATUS │ │
│ │ │ │
│ │ Digital Inputs: [●][○][●][○][●][○][●][○] │ │
│ │ Motor Outputs: [●][○][●][○][●][○][●][○] │ │
│ │ HV Outputs: [●][○][●][○][●][○][●][○] │ │
│ │ LV Outputs: [●][○][●][○][●][○][●][○] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ TEMPERATURE SENSORS │ │
│ │ │ │
│ │ T1 (Tank Bottom): XX.X°C Status: [NORMAL] │ │
│ │ T2 (Tank Wall): XX.X°C Status: [NORMAL] │ │
│ │ T3 (Pump): XX.X°C Status: [NORMAL] │ │
│ │ T4 (Fountain): XX.X°C Status: [NORMAL] │ │
│ │ Internal Temp: XX.X°C Heat Sink: XX.X°C │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Purpose: System diagnostics and troubleshooting
Access: Technician level and above
Features:
- Real-time system monitoring
- Power quality analysis
- I/O status display
- Temperature sensor validation
```
## Visual Feedback System
### Status Indicators
```
Visual Status System:
┌─────────────────────────────────────────────────────────────┐
│ STATUS INDICATORS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ COLORS │ │ ANIMATION │ │ MEANING │ │
│ │ │ │ │ │ │ │
│ │ Green │ │ Solid │ │ Normal/OK │ │
│ │ Red │ │ Solid │ │ Error/Alarm │ │
│ │ Yellow │ │ Solid │ │ Warning │ │
│ │ Blue │ │ Solid │ │ Info/Status │ │
│ │ Gray │ │ Solid │ │ Disabled/Off │ │
│ │ │ │ │ │ │ │
│ │ Any Color │ │ Flashing │ │ Transitioning │ │
│ │ Any Color │ │ Pulsing │ │ User Attention │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Button States
```
Button State Matrix:
┌─────────────────────────────────────────────────────────────┐
│ State │ Background │ Text Color │ Border │ Action │
├─────────────┼────────────┼────────────┼──────────┼──────────┤
│ Normal │ Gray │ Black │ Gray │ Enabled │
│ Active │ Pink │ White │ Pink │ Enabled │
│ Disabled │ Light Gray │ Dark Gray │ Gray │ Disabled │
│ Error │ Red │ White │ Red │ Disabled │
│ Warning │ Yellow │ Black │ Yellow │ Enabled │
│ Flashing │ Alternating│ Contrasting│ Match BG │ Attention│
└─────────────────────────────────────────────────────────────┘
```
## Error Display System
### Error Popup Structure
```
Error Popup Layout:
┌─────────────────────────────────────────────────────────────┐
│ ERROR POPUP │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ┌─────┐ ┌─────┐ │ │
│ │ │Error│ ERROR NUMBER: 3 │ X │ │ │
│ │ │Icon │ │Close│ │ │
│ │ └─────┘ └─────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ERROR DETAILS │ │
│ │ │ │
│ │ - Grid VAC High │ │
│ │ - Communication Timeout │ │
│ │ - Motor Overload (Motor 1) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ACTIONS │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ RESET │ │ RETRY │ │ IGNORE │ │ │
│ │ │ ERRORS │ │ CONNECTION │ │ (Warning) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Error Classification Display
| Error Level | Icon | Color | Sound | Auto-Clear |
|-------------|------|-------|-------|------------|
| Info | ℹ️ | Blue | None | Yes |
| Warning | ⚠️ | Yellow | Beep | Yes |
| Error | ❌ | Red | Alarm | No |
| Critical | 🚨 | Flashing Red | Continuous | No |
## Touch Interface Specifications
### Touch Gestures
```
Supported Touch Gestures:
┌─────────────────────────────────────────────────────────────┐
│ Gesture │ Action │ Application │
├─────────────┼─────────────────────┼───────────────────────┤
│ Tap │ Button activation │ All buttons/controls │
│ Long Press │ Context menu │ Configuration items │
│ Swipe Left │ Previous screen │ Screen navigation │
│ Swipe Right │ Next screen │ Screen navigation │
│ Swipe Up │ Scroll up │ Lists and tables │
│ Swipe Down │ Scroll down │ Lists and tables │
│ Pinch │ Reserved │ Future enhancement │
└─────────────────────────────────────────────────────────────┘
```
### Touch Response
```
Touch Feedback System:
┌─────────────────────────────────────────────────────────────┐
│ Event │ Visual Feedback │ Timing │
├───────────────┼─────────────────────┼─────────────────────┤
│ Touch Down │ Button press effect │ Immediate │
│ Touch Hold │ Highlight │ 100ms │
│ Touch Release │ Action execution │ < 50ms │
│ Invalid Touch │ Red flash │ 200ms │
│ Disabled Item │ No response │ N/A │
└─────────────────────────────────────────────────────────────┘
```
## Screen Management
### Auto-Dimming System
```
Screen Power Management:
┌─────────────────────────────────────────────────────────────┐
│ ACTIVITY TIMELINE │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Normal │───▶│ Dimmed │───▶│ Off │ │
│ │ Brightness │ │ Brightness │ │ (Standby) │ │
│ │ (100%) │ │ (20%) │ │ (0%) │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │ │ │ │
│ Activity No Activity No Activity │
│ for DimSec for OffSec │
│ (default: 30s) (default: 60s) │
│ │
│ ◄─────────────── Touch Activity Resets ──────────────────▶ │
└─────────────────────────────────────────────────────────────┘
```
### Screen Configuration
| Parameter | Default | Range | Description |
|-----------|---------|-------|-------------|
| Brightness | 100% | 10-100% | Normal operating brightness |
| Dim Brightness | 20% | 5-50% | Dimmed state brightness |
| Dim Timeout | 30s | 10-300s | Time to dim after inactivity |
| Off Timeout | 60s | 30-600s | Time to turn off after inactivity |
| Touch Sensitivity | High | Low/Med/High | Touch detection threshold |
## Accessibility Features
### Visual Accessibility
```
Accessibility Support:
┌─────────────────────────────────────────────────────────────┐
│ Feature │ Implementation │
├──────────────────┼─────────────────────────────────────────┤
│ High Contrast │ Alternative color schemes │
│ Large Text │ Scalable font sizes │
│ Color Blind │ Pattern/shape indicators │
│ Low Vision │ High contrast borders │
│ Icon Labels │ Text descriptions for all icons │
│ Status Audio │ Audio feedback for critical events │
└─────────────────────────────────────────────────────────────┘
```
### Operational Accessibility
```
Operational Support:
┌─────────────────────────────────────────────────────────────┐
│ Feature │ Description │
├──────────────────┼─────────────────────────────────────────┤
│ Touch Targets │ Minimum 44px touch targets │
│ Spacing │ Adequate spacing between controls │
│ Feedback │ Clear visual/audio confirmation │
│ Error Messages │ Plain language descriptions │
│ Help System │ Context-sensitive help │
│ Undo/Redo │ Reversible actions where applicable │
└─────────────────────────────────────────────────────────────┘
```
## Internationalization Support
### Language Framework
```
Localization Structure:
┌─────────────────────────────────────────────────────────────┐
│ LANGUAGE RESOURCES │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ English │ │ Spanish │ │ German │ │
│ │ (Default) │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ • UI Labels │ │ • UI Labels │ │ • UI Labels │ │
│ │ • Messages │ │ • Messages │ │ • Messages │ │
│ │ • Errors │ │ • Errors │ │ • Errors │ │
│ │ • Help Text │ │ • Help Text │ │ • Help Text │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Language Engine │ │
│ │ (Runtime) │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Localization Elements
| Element Type | Examples | Localization Method |
|-------------|----------|-------------------|
| Button Labels | "Start Recipe", "Stop", "Settings" | Resource files |
| Error Messages | "Communication timeout", "Temperature high" | Resource files |
| Units | "°C", "°F", "seconds", "minutes" | Configuration |
| Date/Time Format | "DD/MM/YYYY", "MM/DD/YYYY" | Regional settings |
| Number Format | "1,234.56", "1.234,56" | Regional settings |
| Currency | "$", "€", "£" | Not applicable |
This UI specification provides comprehensive details for implementing a robust, accessible, and user-friendly touch interface for the chocolate tempering machine control system.

552
docs/05-data-management.md Normal file
View File

@@ -0,0 +1,552 @@
# Data Management and Configuration Specification
## Overview
The system uses a CSV-based data persistence layer for storing configuration, recipes, hardware mappings, and system parameters. This document details the data structures, validation rules, and management operations.
## Data Architecture
### File-Based Storage System
```
Data Storage Architecture:
┌─────────────────────────────────────────────────────────────┐
│ ROOT DIRECTORY │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ CSV FILES │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Recipe.csv │ │Machine.csv │ │Mapping.csv │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Screen.csv │ │ Config.csv │ │ Users.csv │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ │ │
│ │ │ErrorSet.csv │ │ │
│ │ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ DATA ACCESS LAYER │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │RecipeTable │ │MachineTable │ │MappingTable │ │ │
│ │ │ Class │ │ Class │ │ Class │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ScreenTable │ │ ConfigTable │ │ UserTable │ │ │
│ │ │ Class │ │ Class │ │ Class │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Data Path Management
```
Path Resolution System:
┌─────────────────────────────────────────────────────────────┐
│ DataPathManager │
│ │
│ GetDataFilePath(filename) │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. Check Working Directory │ │
│ │ 2. Check Application Directory │ │
│ │ 3. Check System Config Directory │ │
│ │ 4. Create if not exists │ │
│ │ 5. Return absolute path │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ MigrateCsvFiles() │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. Check file structure │ │
│ │ 2. Add missing columns │ │
│ │ 3. Set default values │ │
│ │ 4. Validate data integrity │ │
│ │ 5. Create backup if needed │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Data Entities
### 1. Recipe Data Structure
```
Recipe.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ ID │ int │ 1-999999 │ Auto │ Yes │
│ Name │ string │ 1-50 chars │ "" │ Yes │
│ TankTemp │ float │ 0-65°C │ 0 │ No │
│ FountainTemp │ float │ 0-65°C │ 0 │ No │
│ Mixer │ bool │ 0/1 │ 0 │ Yes │
│ Fountain │ bool │ 0/1 │ 0 │ Yes │
│ MoldHeater │ bool │ 0/1 │ 0 │ Yes │
│ Vibration │ bool │ 0/1 │ 0 │ Yes │
│ VibHeater │ bool │ 0/1 │ 0 │ Yes │
│ Pedal │ bool │ 0/1 │ 0 │ Yes │
│ PedalOnTime │ int │ 1-999 sec │ 0 │ No │
│ PedalOffTime │ int │ 1-999 sec │ 0 │ No │
│ HeatingGoal │ float │ 40-60°C │ 46 │ Yes │
│ CoolingGoal │ float │ 20-40°C │ 27 │ Yes │
│ PouringGoal │ float │ 20-60°C │ 30 │ Yes │
└─────────────────────────────────────────────────────────────┘
Business Rules:
• CoolingGoal < HeatingGoal
• CoolingGoal ≤ PouringGoal ≤ HeatingGoal
• Name must be unique
• ID auto-increments
```
### 2. Machine Configuration
```
Machine.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ ID │ int │ Always 1 │ 1 │ Yes │
│ TankMaxHeat │ float │ 30-65°C │ 50 │ Yes │
│ PumpMaxHeat │ float │ 30-65°C │ 50 │ Yes │
│ PumpDelay │ int │ 10-300 sec │ 60 │ Yes │
│ MixerDelay │ int │ 10-300 sec │ 60 │ Yes │
│ HeatingDelay │ int │ 10-300 sec │ 60 │ Yes │
│ CoolingDelay │ int │ 10-300 sec │ 60 │ Yes │
│ PouringDelay │ int │ 10-300 sec │ 60 │ Yes │
│ PumpMinHeat │ float │ -20-30°C │ -10 │ Yes │
│ AbsMaxHeat │ float │ 60-80°C │ 65 │ Yes │
│ AbsMinHeat │ float │ -20-0°C │ -14 │ Yes │
│ PreHeatingTemp │ float │ 0-20°C │ 5 │ Yes │
│ setTemp1 │ float │ -20-20°C │ 0 │ No │
│ setTemp2 │ float │ -20-20°C │ -10 │ No │
│ setTemp3 │ float │ -20-20°C │ 5 │ No │
│ setTemp4 │ float │ -20-20°C │ 0 │ No │
└─────────────────────────────────────────────────────────────┘
Business Rules:
• Only one machine configuration (ID=1)
• TankMaxHeat ≤ AbsMaxHeat
• PumpMaxHeat ≤ AbsMaxHeat
• PumpMinHeat ≥ AbsMinHeat
• All delays ≥ 10 seconds
```
### 3. Hardware Mapping
```
Mapping.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ Id │ int │ 1-999 │ Auto │ Yes │
│ Name │ string │ 1-50 chars │ "" │ Yes │
│ Address │ string │ Modbus addr │ "" │ Yes │
│ IsRead │ bool │ 0/1 │ 0 │ Yes │
│ BitNumbers │ string │ Bit list │ "" │ No │
└─────────────────────────────────────────────────────────────┘
BitNumbers Format: "0|1|2" (pipe-separated bit positions)
Hardware Categories:
• Temperature Sensors (IsRead=1, Address=8-11)
• Digital Inputs (IsRead=1, Address=1, BitNumbers=0-15)
• Motor Outputs (IsRead=0, Address=1-3, BitNumbers=0-15)
• Analog Outputs (IsRead=0, Address=2, BitNumbers=0-15)
```
### 4. Screen Configuration
```
Screen.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ Id │ int │ Always 1 │ 1 │ Yes │
│ Port │ string │ COM1-COM99 │ COM1 │ Yes │
│ BoundRate │ int │ 1200-115200 │ 9600 │ Yes │
│ Parity │ int │ 0-4 │ 0 │ Yes │
│ StopBits │ int │ 1-2 │ 1 │ Yes │
│ SendingTime │ int │ 50-1000 ms │ 100 │ Yes │
│ WarningLimit │ float │ 0.1-10°C │ 1.5 │ Yes │
│ ErrorLimit │ float │ 0.5-20°C │ 3.0 │ Yes │
│ Brightness │ int │ 10-100% │ 100 │ Yes │
│ DimSec │ int │ 10-300 sec │ 30 │ Yes │
│ OffSec │ int │ 30-600 sec │ 60 │ Yes │
└─────────────────────────────────────────────────────────────┘
Parity Values:
0 = None, 1 = Odd, 2 = Even, 3 = Mark, 4 = Space
```
### 5. PID Configuration
```
Configuration.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ Id │ int │ 1-4 │ Auto │ Yes │
│ Name │ string │ Zone name │ "" │ Yes │
│ Max │ float │ 30-80°C │ 65 │ Yes │
│ Min │ float │ -20-30°C │ -14 │ Yes │
│ H_out │ int[] │ Bit array │ [] │ No │
│ FC_out │ int[] │ Bit array │ [] │ No │
│ SC_out │ int[] │ Bit array │ [] │ No │
│ FC_Threshold │ float │ 0-100°C │ 50 │ Yes │
│ HeatConRange │ float │ 0.1-10°C │ 2.0 │ Yes │
│ kp │ float │ 0.1-100 │ 1.0 │ Yes │
│ ki │ float │ 0.001-10 │ 0.1 │ Yes │
│ kd │ float │ 0.001-10 │ 0.01 │ Yes │
│ kl │ float │ 0.1-100 │ 10 │ Yes │
│ i_neut │ float │ 0.1-50 A │ 5.0 │ Yes │
│ i_mot1 │ float │ 0.1-50 A │ 10.0 │ Yes │
│ i_mot2 │ float │ 0.1-50 A │ 10.0 │ Yes │
└─────────────────────────────────────────────────────────────┘
PID Zones:
1 = Tank Bottom Heater
2 = Tank Wall Heater
3 = Pump Heater
4 = Fountain Heater
```
### 6. User Management
```
Users.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ Id │ int │ 1-999 │ Auto │ Yes │
│ Username │ string │ 3-20 chars │ "" │ Yes │
│ Password │ string │ Hash/Plain │ "" │ Yes │
│ Role │ string │ User roles │ "" │ Yes │
│ Active │ bool │ 0/1 │ 1 │ Yes │
│ LastLogin │ datetime│ ISO format │ null │ No │
│ CreatedDate │ datetime│ ISO format │ now │ Yes │
└─────────────────────────────────────────────────────────────┘
User Roles:
• Operator: Basic operation, recipe selection
• Technician: Manual control, diagnostics
• Admin: All functions, configuration
```
### 7. Error Settings
```
ErrorSettings.csv Schema:
┌─────────────────────────────────────────────────────────────┐
│ Column Name │ Type │ Range │ Default │ Req'd │
├─────────────────┼─────────┼──────────────┼─────────┼───────┤
│ Id │ int │ Always 1 │ 1 │ Yes │
│ GridFreq │ float │ 45-65 Hz │ 50 │ Yes │
│ PhaseNumber │ int │ 1/3 │ 3 │ Yes │
│ VoltageHigh │ float │ 200-250 V │ 242 │ Yes │
│ VoltageLow │ float │ 180-220 V │ 198 │ Yes │
│ CurrentHigh │ float │ 10-100 A │ 20 │ Yes │
│ TempHigh │ float │ 60-100°C │ 70 │ Yes │
│ TempLow │ float │ -30-0°C │ -20 │ Yes │
└─────────────────────────────────────────────────────────────┘
```
## Data Access Patterns
### CRUD Operations
```
Data Operation Flow:
┌─────────────────────────────────────────────────────────────┐
│ CREATE │
│ │
│ Validate Input ──▶ Check Constraints ──▶ Assign ID ──▶ Save │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Field Types Business Rules Auto-increment CSV │
│ Data Ranges Unique Keys Get Next ID Write│
│ Required Fields Cross-validation Lock File Sync │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ READ │
│ │
│ Query ──▶ Load File ──▶ Parse CSV ──▶ Filter ──▶ Return │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ By ID Open File Split Lines Match Object │
│ By Name Read All Parse Cols Criteria List │
│ All Handle IO Type Convert Sort Entity │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ UPDATE │
│ │
│ Find Record ──▶ Validate ──▶ Update ──▶ Save ──▶ Verify │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Load by ID Check Rules Modify Rewrite Read-back │
│ Lock Record Constraints Values File Confirm │
│ Current State Cross-check Preserve Atomic Changes │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ DELETE │
│ │
│ Find Record ──▶ Check Refs ──▶ Remove ──▶ Compact ──▶ Save │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Verify Exists Foreign Keys Mark Del Rewrite Sync │
│ Load Context Dependencies Filter Rebuild File │
│ Confirm ID Safety Check Lines Index Safe │
└─────────────────────────────────────────────────────────────┘
```
### Transaction Safety
```
File Locking Strategy:
┌─────────────────────────────────────────────────────────────┐
│ OPERATION SAFETY │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ BEGIN │───▶│ LOCK │───▶│ EXECUTE │ │
│ │ Operation │ │ File │ │ Operation │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ RELEASE │◄───│ VERIFY │◄───│ COMMIT │ │
│ │ Lock │ │ Result │ │ Changes │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │
│ Error Handling: │
│ • Timeout: Release lock after 30 seconds │
│ • Crash Recovery: Check for stale locks on startup │
│ • Corruption: Restore from backup if available │
│ • Validation: Verify data integrity after each operation │
└─────────────────────────────────────────────────────────────┘
```
## Data Validation Framework
### Validation Rules Engine
```
Validation Process:
┌─────────────────────────────────────────────────────────────┐
│ VALIDATION LAYERS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ SYNTAX │───▶│ SEMANTIC │───▶│ BUSINESS │ │
│ │ Validation │ │ Validation │ │ Rules │ │
│ │ │ │ │ │ │ │
│ │ • Data Type │ │ • Range │ │ • Cross-field │ │
│ │ • Format │ │ • Enum │ │ • Dependencies │ │
│ │ • Required │ │ • Pattern │ │ • Constraints │ │
│ │ • Length │ │ • Logic │ │ • State Rules │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Validation │ │
│ │ Result │ │
│ │ • Valid/Invalid │ │
│ │ • Error List │ │
│ │ • Warnings │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Recipe Validation Example
```
Recipe Temperature Validation:
┌─────────────────────────────────────────────────────────────┐
│ function ValidateRecipe(recipe): │
│ │
│ errors = [] │
│ │
│ // Syntax validation │
│ if recipe.HeatingGoal == null: │
│ errors.add("Heating goal is required") │
│ │
│ // Semantic validation │
│ if recipe.HeatingGoal < 40 OR recipe.HeatingGoal > 60: │
│ errors.add("Heating goal must be 40-60°C") │
│ │
│ // Business rules │
│ if recipe.CoolingGoal >= recipe.HeatingGoal: │
│ errors.add("Cooling goal must be less than heating") │
│ │
│ if recipe.PouringGoal < recipe.CoolingGoal: │
│ errors.add("Pouring goal must be >= cooling goal") │
│ │
│ if recipe.PouringGoal > recipe.HeatingGoal: │
│ errors.add("Pouring goal must be <= heating goal") │
│ │
│ return errors │
└─────────────────────────────────────────────────────────────┘
```
## Data Migration and Versioning
### Schema Evolution
```
Migration Framework:
┌─────────────────────────────────────────────────────────────┐
│ MIGRATION PROCESS │
│ │
│ Application Start │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Check File │ │
│ │ Versions │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ Version Match? │───▶│ Migration Required │ │
│ │ (Header Check) │ No │ │ │
│ └─────────────────┘ │ 1. Backup existing files │ │
│ │ Yes │ 2. Add missing columns │ │
│ ▼ │ 3. Set default values │ │
│ ┌─────────────────┐ │ 4. Validate data integrity │ │
│ │ Continue Normal │ │ 5. Update version markers │ │
│ │ Operation │ └─────────────────────────────────┘ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Version Control
| File | Current Version | Migration Triggers |
|------|-----------------|-------------------|
| Recipe.csv | 1.2 | New temperature fields |
| Machine.csv | 1.1 | Additional setTemp fields |
| Mapping.csv | 1.0 | Stable schema |
| Screen.csv | 1.1 | Communication parameters |
| Configuration.csv | 1.3 | PID parameter additions |
| Users.csv | 1.0 | Stable schema |
| ErrorSettings.csv | 1.0 | Stable schema |
## Backup and Recovery
### Backup Strategy
```
Backup System:
┌─────────────────────────────────────────────────────────────┐
│ BACKUP LIFECYCLE │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Automatic │ │ Manual │ │ Migration │ │
│ │ Backup │ │ Backup │ │ Backup │ │
│ │ │ │ │ │ │ │
│ │ • Daily │ │ • On-demand │ │ • Pre-migration │ │
│ │ • Startup │ │ • User │ │ • Schema change │ │
│ │ • Critical │ │ │ triggered │ │ • Error recovery│ │
│ │ │ changes │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Backup Storage │ │
│ │ │ │
│ │ • Timestamp │ │
│ │ • Compressed │ │
│ │ • Verified │ │
│ │ • Indexed │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Recovery Procedures
```
Recovery Process:
┌─────────────────────────────────────────────────────────────┐
│ Data Corruption Detected │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Assess Damage │ │
│ │ • File integrity│ │
│ │ • Data validity │ │
│ │ • System state │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ Corruption │───▶│ Recovery Options │ │
│ │ Level? │ │ │ │
│ └─────────────────┘ │ Minor: Repair in place │ │
│ │ │ Major: Restore from backup │ │
│ ▼ │ Total: Factory reset + restore │ │
│ ┌─────────────────┐ └─────────────────────────────────┘ │
│ │ Execute │ │
│ │ Recovery │ │
│ │ • Validate fix │ │
│ │ • Test system │ │
│ │ • Log recovery │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Performance Considerations
### File Access Optimization
```
Performance Strategy:
┌─────────────────────────────────────────────────────────────┐
│ OPTIMIZATION LAYERS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ CACHING │ │ INDEXING │ │ BATCHING │ │
│ │ │ │ │ │ │ │
│ │ • In-memory │ │ • ID lookup │ │ • Bulk reads │ │
│ │ • LRU evict │ │ • Name hash │ │ • Batch writes │ │
│ │ • Write-thru│ │ • Range scan│ │ • Transaction │ │
│ │ • Invalidate│ │ • Sort index│ │ │ grouping │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │
│ Read Performance: │
│ • Cache hit: < 1ms │
│ • File read: < 10ms │
│ • Full scan: < 100ms │
│ │
│ Write Performance: │
│ • Cache write: < 1ms │
│ • File write: < 50ms │
│ • Full rewrite: < 200ms │
└─────────────────────────────────────────────────────────────┘
```
### Memory Management
| Component | Memory Usage | Cache Strategy |
|-----------|--------------|---------------|
| Recipe Cache | < 1MB | LRU, 100 entries |
| Machine Config | < 1KB | Always cached |
| Hardware Mapping | < 10KB | Always cached |
| Screen Settings | < 1KB | Always cached |
| PID Configuration | < 5KB | Always cached |
| User Data | < 100KB | Session-based |
This data management specification provides comprehensive details for implementing a robust, efficient, and reliable data persistence system for the chocolate tempering machine control system.

304
docs/analysis.md Normal file
View File

@@ -0,0 +1,304 @@
I'll analyze this codebase thoroughly to create a comprehensive specification. Let me start by examining the key files to understand the system architecture and behavior. Let me continue reading the rest of this critical file: Let me continue reading the remaining part of this file: Now let me examine some key files to understand the project better: Now let me look at a few more key files to understand the complete architecture: Based on my thorough analysis of this tempering machine control system codebase, I'll now generate a comprehensive specification document. This is indeed a complex industrial control system with significant technical debt, so let me break it down systematically.
# Tempering Machine Control System - Technical Specification
## Executive Summary
This is an industrial chocolate tempering machine control system built with Avalonia UI (.NET 8) that communicates with hardware via Modbus RTU protocol over serial communication. The system controls heating, cooling, and chocolate pouring processes through a multi-threaded architecture with CSV-based configuration storage.
## System Architecture Overview
### Core Components
1. **User Interface Layer**: Avalonia-based touch interface with multiple screens
2. **Control Logic Layer**: Multi-threaded loop system for hardware monitoring and recipe execution
3. **Communication Layer**: Modbus RTU over serial communication
4. **Data Layer**: CSV file-based persistence
5. **Hardware Interface**: Temperature sensors, motors, pumps, and I/O controls
### Threading Architecture
The system operates 5 concurrent background threads initiated from `MainWindow` constructor:
| Thread | Purpose | Priority | Key Responsibilities |
|--------|---------|----------|---------------------|
| **MonitorPortsLoop** | Hardware communication & recipe execution | Highest | Temperature monitoring, motor control, recipe phase management |
| **ScreenLoop** | Error handling & UI state management | Normal | Error display, UI enabling/disabling based on system state |
| **InteractiveUILoop** | Visual feedback | Normal | Button flashing, status indicators |
| **TouchLoop** | Touch input handling | Normal | Screen dimming, activity tracking |
| **CheckInternetLoop** | Network connectivity monitoring | Normal | Internet connection status |
## Hardware Communication System
### Modbus RTU Protocol Implementation
- **Protocol**: Modbus RTU over RS-485/serial
- **Implementation**: Custom `ModBusMaster` class with CRC validation
- **Communication Pattern**: Async queue-based with retry logic
- **Slave ID**: Configurable (default: 0x01)
### Supported Modbus Functions
- **Function 0x03**: Read Holding Registers
- **Function 0x04**: Read Input Registers
- **Function 0x05**: Write Single Coil
- **Function 0x06**: Write Single Register
- **Function 0x0F**: Write Multiple Coils
- **Function 0x10**: Write Multiple Registers
### Hardware Mapping System
All hardware is mapped through a configurable CSV-based mapping system (Mapping.csv):
```csv
Id,Name,Address,IsRead,BitNumbers
1,Pedal,1,1,0
4,Tank Bottom Temp,8,1,8
17,Mixer,3,0,0
18,Pump,3,0,1
```
### Register Layout
The system uses a standardized holding register structure:
| Register | Purpose | Data Type | Range |
|----------|---------|-----------|-------|
| 0 | Reset Error | ushort | Bit flags |
| 1 | HV Output | ushort | Bit flags |
| 2 | LV Output | ushort | Bit flags |
| 3 | Motor Control | ushort | Bit flags |
| 4-7 | Temperature Setpoints | int | -10000 to +6500 (deciselsius) |
## Recipe Management System
### Three-Phase Recipe Process
1. **Heating Phase**: Heat chocolate to target temperature in both mixer tank and fountain
2. **Cooling Phase**: Cool chocolate to precise temperature or show delay countdown
3. **Pouring Phase**: Maintain temperature within tight tolerance range
### Temperature Control Logic
```
Heating Goal: 40-60°C (configurable per recipe)
Cooling Goal: 20-40°C (configurable per recipe)
Pouring Goal: Between cooling and heating goals
```
### Critical Temperature Error Conditions
- **Heating Phase**: Error only if temperature < (goal - errorLimit)
- **Cooling Phase**: Error only if temperature > (goal + errorLimit)
- **Pouring Phase**: Error if temperature outside (goal ± errorLimit)
### Recipe State Management
States use integer values:
- `-1`: Off/Inactive
- `1`: Active/Running
- `10`: Paused
### Motor Control System
Motors are controlled via bit manipulation on holding registers:
```csharp
// Turn on motor
foreach (var bit in motor.BitNumbers)
holdingRegister.motor |= (ushort)(1 << bit);
// Turn off motor
foreach (var bit in motor.BitNumbers)
holdingRegister.motor &= (ushort)~(1 << bit);
```
## Data Persistence Layer
### CSV-Based Configuration
All system configuration is stored in root-level CSV files:
| File | Purpose | Key Data |
|------|---------|----------|
| Recipe.csv | Recipe definitions | Temperature goals, motor settings, pedal timing |
| Machine.csv | Hardware limits & delays | Max temperatures, timer delays, safety limits |
| Mapping.csv | Hardware address mapping | Motor addresses, sensor addresses, I/O mapping |
| Screen.csv | Display configuration | Brightness, timeout settings, communication parameters |
| `Configuration.csv` | PID control parameters | Per-heating-element PID tuning |
### Temperature Sensor Configuration
The system supports 4 configurable temperature zones:
- **Tank Bottom Temperature** (Mixer monitoring)
- **Tank Wall Temperature** (Mixer monitoring)
- **Pump Temperature** (Pump/circulation monitoring)
- **Fountain Temperature** (Chocolate output monitoring)
## Error Handling & Safety System
### Error Classification
The system implements a comprehensive error monitoring system:
| Error Type | Condition | Action |
|------------|-----------|---------|
| Grid VAC High/Low | ±10% of 220V | Display error, disable operations |
| Grid Frequency | ±10% of configured frequency | Display error, disable operations |
| No External Power | Power detection failure | Display error, disable operations |
| Missing Phase | Phase detection (3-phase systems) | Display error, disable operations |
| Communication Timeout | No Modbus response > 3 seconds | Display error, retry communication |
| High Current | Motor overcurrent detection | Display error, disable affected motor |
### Automatic Recovery
- Errors are automatically cleared when conditions return to normal
- System resumes operation after error clearance
- Recipe phases can resume from pause state
## Motor Control Specifications
### Supported Motors
1. **Mixer Motor**: Tank agitation system
2. **Fountain Motor (Helix)**: Chocolate fountain/pump system
3. **Vibrator**: Mold vibration system
4. **Compressor**: Cooling system compressor
5. **Various Pumps**: Circulation and transfer pumps
### Motor Safety Features
- Automatic temperature-based shutoff
- Manual override capability
- Error condition lockout
- Coordinated startup sequences
## User Interface System
### Screen Navigation
- **Home**: User selection and main menu
- **Settings**: Recipe execution and motor control
- **Recipe Management**: Recipe creation and editing
- **Manual Control**: Direct motor and output control
- **Diagnostics**: System status and troubleshooting
- **Admin**: System configuration and advanced settings
### Touch Interface Features
- Auto-dimming based on inactivity
- Error popup overlays
- Real-time temperature display
- Recipe progress indicators
- Motor status indicators
## Serial Communication Implementation
### Queue-Based Communication
The system implements a sophisticated queue-based serial communication system:
```csharp
// Write Queue: Priority operations (motor control, temperature settings)
// Read Queue: Regular monitoring (temperature readings, status updates)
```
### Communication Timing
- **Minimum Interval**: Configurable per-message timing (typically 100-500ms)
- **Retry Logic**: 3 attempts with exponential backoff
- **CRC Validation**: All messages validated with Modbus CRC16
- **Error Recovery**: Automatic retry on communication failure
### Serial Port Configuration
- **Baud Rate**: Configurable (default 9600-115200)
- **Data Bits**: 8
- **Stop Bits**: 1 or 2 (configurable)
- **Parity**: None, Odd, Even, Mark, Space (configurable)
- **Flow Control**: None (hardware handshaking disabled)
## Pedal Control System
The system supports both manual and automatic pedal operation modes:
### Manual Mode
- Direct user control via physical pedal
- Real-time fountain motor control based on pedal state
- Immediate response to pedal press/release
### Automatic Mode
- Timer-based cycling between ON/OFF states
- Configurable ON time and OFF time per recipe
- Automatic fountain motor control during pouring phase
## Temperature Control & PID System
### PID Implementation
Each heating element has independently configurable PID parameters:
- **Kp**: Proportional gain
- **Ki**: Integral gain
- **Kd**: Derivative gain
- **Kl**: Limit parameter
### Temperature Zones
1. **Zone 1**: Tank bottom heating
2. **Zone 2**: Tank wall heating
3. **Zone 3**: Pump heating
4. **Zone 4**: Fountain heating
### Temperature Safety Limits
- **Absolute Maximum**: 65°C (configurable)
- **Absolute Minimum**: -14°C (configurable)
- **Working Range**: Typically 20-60°C depending on recipe
## Recipe Phase Management
### Phase Transition Logic
```
Pre-heating → Heating → Cooling → Pouring → Complete
```
Each phase has specific temperature targets and timing requirements:
1. **Pre-heating**: Bring system to operational temperature
2. **Heating**: Reach recipe heating goal with delay timer
3. **Cooling**: Cool to recipe cooling goal with delay timer
4. **Pouring**: Maintain pouring temperature with tight tolerance
### Timer Management
The system uses multiple Timer objects for phase control:
- `heatingTimer`: Controls heating phase duration
- `coolingTimer`: Controls cooling phase duration
- `pouringTimer`: Controls pouring phase duration
- `pedalOnTimer`/`pedalOffTimer`: Controls automatic pedal cycling
## Deployment Specifications
### Target Platform
- **Operating System**: Linux (embedded single-board computer)
- **Framework**: .NET 8 with Avalonia UI
- **Hardware Interface**: RS-485/Serial communication
- **Display**: Touch screen interface
### System Requirements
- Serial port access for Modbus communication
- File system write access for CSV configuration
- Network access for internet connectivity monitoring
- Real-time capabilities for temperature control
### Build & Deployment
```bash
# Build application
dotnet build
# Run application
dotnet run
# Publish for deployment
dotnet publish -c Release
```
## Critical Implementation Issues
Based on the code analysis, several architectural issues should be addressed in any migration:
1. **Thread Safety**: Multiple threads accessing shared state without proper synchronization
2. **Error Handling**: Inconsistent exception handling throughout the codebase
3. **Code Duplication**: Significant repetition in UI update logic
4. **Magic Numbers**: Hard-coded values throughout instead of configuration
5. **Monolithic Design**: Single large class (MainWindow) handling multiple responsibilities
6. **Resource Management**: Potential memory leaks with Timer objects
7. **Communication Reliability**: Limited error recovery in Modbus communication
## Migration Recommendations
For migrating this system to another technology stack:
1. **Separate Concerns**: Split into distinct services (UI, Control Logic, Communication)
2. **State Management**: Implement proper state machine for recipe phases
3. **Communication Layer**: Abstract Modbus implementation with proper async/await patterns
4. **Configuration**: Replace CSV files with proper database or structured configuration
5. **Error Handling**: Implement comprehensive error handling and logging
6. **Testing**: Add unit tests for critical control logic
7. **Documentation**: Document all hardware interfaces and communication protocols
This specification provides the foundation for understanding the current system and planning a migration to a more maintainable architecture.