Tempering-Machine-Control-System/docs/01-system-overview.md

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.