Add comprehensive data management and configuration specification documentation; introduce analysis of tempering machine control system architecture and behavior
This commit is contained in:
203
docs/01-system-overview.md
Normal file
203
docs/01-system-overview.md
Normal 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.
|
||||
Reference in New Issue
Block a user