Add migration strategy document for chocolate tempering machine control system

- Comprehensive analysis of current system and architectural debt
- Detailed recommendations for target architecture and technology stack
- Phase-based migration approach outlined with timelines and deliverables
- Risk mitigation strategies and data migration processes defined
- Database schema design to replace existing CSV storage
- Implementation recommendations including development best practices and performance optimization strategies
This commit is contained in:
2025-08-06 21:41:21 +02:00
parent e2fab5695b
commit 83b6a25fd5
2 changed files with 1256 additions and 0 deletions

View File

@@ -0,0 +1,507 @@
# Error Handling and Safety Systems Specification
## Overview
The tempering machine control system implements a comprehensive error monitoring and safety system to ensure safe operation of the chocolate tempering process. This document details the error classification, detection mechanisms, safety protocols, and recovery procedures.
## Error Classification System
### Error Categories
```
Error Hierarchy:
┌─────────────────────────────────────────────────────────────┐
│ ERROR CATEGORIES │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ CRITICAL │ │ WARNING │ │ INFORMATIONAL │ │
│ │ ERRORS │ │ ERRORS │ │ ERRORS │ │
│ │ │ │ │ │ │ │
│ │ • Grid power │ │ • Temperature │ │ • Communication │ │
│ │ • Phase issues │ │ approaching │ │ status │ │
│ │ • Overcurrent │ │ limits │ │ • Network │ │
│ │ • Safety │ │ • Recipe │ │ connectivity │ │
│ │ violations │ │ warnings │ │ • System info │ │
│ │ │ │ │ │ │ │
│ │ Action: │ │ Action: │ │ Action: │ │
│ │ STOP ALL │ │ DISPLAY WARNING │ │ LOG ONLY │ │
│ │ OPERATIONS │ │ CONTINUE │ │ CONTINUE │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Error Enumeration
```
Error.GridCondition Enumeration:
┌─────────────────────────────────────────────────────────────┐
│ Error Type │ Trigger Condition │ │
├─────────────────────────┼─────────────────────────────────┤ │
│ GridFrequencyHigh │ Frequency > (setpoint × 1.1) │ │
│ GridFrequencyLow │ Frequency < (setpoint × 0.9) │ │
│ GridVACHigh │ Voltage > 242V (±10%) │ │
│ GridVACLow │ Voltage < 198V (±10%) │ │
│ NoExternalPower │ External power detection fail │ │
│ MissingPhase │ Phase loss in 3-phase systems │ │
│ PhaseSequence │ Incorrect phase rotation │ │
│ LoadDisconnection │ Load circuit open │ │
│ MotorDisconnection │ Motor circuit fault │ │
│ NoBoardCom │ Modbus timeout > 3 seconds │ │
│ NoInternetAccess │ Network connectivity lost │ │
│ ComPort1 │ Communication port 1 error │ │
│ ComPort2 │ Communication port 2 error │ │
│ HiCurrNeut │ Neutral current > threshold │ │
│ HiCurrMot1 │ Motor 1 current > threshold │ │
│ HiCurrMot2 │ Motor 2 current > threshold │ │
└─────────────────────────────────────────────────────────────┘
```
## Error Detection System
### Real-Time Monitoring
```
Error Detection Flow:
┌─────────────────────────────────────────────────────────────┐
│ MONITORING PROCESS │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Hardware Input │───▶│ Value Analysis │ │
│ │ Reading │ │ & Comparison │ │
│ │ │ │ │ │
│ │ • Grid voltage │ │ • Range check │ │
│ │ • Grid freq │ │ • Threshold │ │
│ │ • Motor current │ │ comparison │ │
│ │ • Temperature │ │ • Trend │ │
│ │ • Digital I/O │ │ analysis │ │
│ │ • Com status │ │ • Safety logic │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ERROR DECISION │ │
│ │ │ │
│ │ Condition Met? ──▶ YES ──▶ Error Triggered │ │
│ │ │ │ │ │
│ │ ▼ NO ▼ │ │
│ │ Condition ──▶ Add to Error List │ │
│ │ Cleared? YES Set timestamp │ │
│ │ │ Start safety actions │ │
│ │ ▼ NO │ │
│ │ Continue │ │
│ │ Monitoring │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Detection Implementation
```
MonitorPortsLoop Error Detection:
┌─────────────────────────────────────────────────────────────┐
│ // Grid Voltage Monitoring │
│ if (inputValues[2] > 220 * 1.1 || │
│ inputValues[3] > 220 * 1.1 || │
│ inputValues[4] > 220 * 1.1) { │
│ │
│ if (!errors.Any(x => x.Condition == │
│ Error.GridCondition.GridVACHigh)) { │
│ errors.Add(new Error { │
│ errorDate = DateTime.Now, │
│ Condition = Error.GridCondition.GridVACHigh │
│ }); │
│ } │
│ } else { │
│ // Clear error if condition no longer exists │
│ var existingError = errors.FirstOrDefault( │
│ x => x.Condition == Error.GridCondition.GridVACHigh);│
│ if (existingError != null) { │
│ existingError.isDeleted = true; │
│ } │
│ } │
│ │
│ Detection Frequency: Every MonitorPortsLoop iteration │
│ Response Time: < 100ms │
│ Hysteresis: 10% built into thresholds │
└─────────────────────────────────────────────────────────────┘
```
## Safety Action System
### Immediate Response Actions
```
Safety Response Matrix:
┌─────────────────────────────────────────────────────────────┐
│ Error Type │ Immediate Action │ Recipe Impact│
├─────────────────────┼─────────────────────────┼─────────────┤
│ Grid Power Issues │ • Disable all motors │ Pause recipe│
│ │ • Turn off heaters │ Wait for │
│ │ • Show error popup │ recovery │
├─────────────────────┼─────────────────────────┼─────────────┤
│ Overcurrent │ • Stop affected motor │ Pause if │
│ │ • Disable motor control │ critical │
│ │ • Alert operator │ motor │
├─────────────────────┼─────────────────────────┼─────────────┤
│ Communication Loss │ • Disable new commands │ Continue │
│ │ • Show connection status│ current │
│ │ • Attempt reconnection │ phase │
├─────────────────────┼─────────────────────────┼─────────────┤
│ Temperature Limits │ • Disable heaters │ Pause │
│ │ • Emergency cooling │ recipe │
│ │ • Operator notification │ │
├─────────────────────┼─────────────────────────┼─────────────┤
│ Phase/Safety Issues │ • Emergency stop all │ Abort │
│ │ • Lockout all controls │ recipe │
│ │ • Require manual reset │ │
└─────────────────────────────────────────────────────────────┘
```
### Safety Interlock System
```
Safety Interlock Logic:
┌─────────────────────────────────────────────────────────────┐
│ INTERLOCK SYSTEM │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Error Detection │───▶│ Safety Logic │ │
│ │ │ │ Evaluation │ │
│ │ • Hardware │ │ │ │
│ │ monitoring │ │ if (errors.Count > 0) { │
│ │ • Software │ │ var criticalTime = │
│ │ validation │ │ errors.Min(x => x.errorDate);│ │
│ │ • Communication │ │ │ │
│ │ status │ │ if ((DateTime.Now - │ │
│ │ │ │ criticalTime) │ │
│ └─────────────────┘ │ .TotalSeconds >= 3.5) { │ │
│ │ // Trigger safety actions │ │
│ │ DisableOperations(); │ │
│ │ } │ │
│ │ } │ │
│ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SAFETY ACTIONS │ │
│ │ │ │
│ │ Critical Errors (Immediate): │ │
│ │ • Stop all motor operations │ │
│ │ • Disable heating elements │ │
│ │ • Pause recipe execution │ │
│ │ • Lock user interface controls │ │
│ │ • Display error information │ │
│ │ │ │
│ │ Warning Errors (Delayed): │ │
│ │ • Show warning messages │ │
│ │ • Continue current operations │ │
│ │ • Log event for analysis │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## Error Display and User Interface
### Error Presentation System
```
Error UI Management:
┌─────────────────────────────────────────────────────────────┐
│ DISPLAY SYSTEM │
│ │
│ ScreenLoop Thread (10ms intervals) │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Check Error │ │
│ │ Collection │ │
│ │ │ │
│ │ foreach error: │ │
│ │ age >= 2.5s? │ │
│ └─────────────────┘ │
│ │ YES │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Error Message Construction: │ │
│ │ │ │
│ │ if (!item.isShowen) { │ │
│ │ if (!errorMsg.Text.Contains(errorName)) { │ │
│ │ errorMsg.Text += $"\n- {errorName}"; │ │
│ │ item.isShowen = true; │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ │ if (item.isDeleted) { │ │
│ │ errorMsg.Text = errorMsg.Text │ │
│ │ .Replace($"- {errorName}", ""); │ │
│ │ errors.Remove(item); │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Error Display Components: │
│ • errorLogo: Visual indicator (visible when errors exist) │
│ • errorMsg: Text list of current errors │
│ • errorPopupOverlay: Full-screen error details │
│ • errorTitel: Error count and summary │
└─────────────────────────────────────────────────────────────┘
```
### Error Message Templates
```
Error Display Messages:
┌─────────────────────────────────────────────────────────────┐
│ Error Condition │ Display Message │
├─────────────────────────┼─────────────────────────────────┤
│ GridFrequencyHigh │ "Grid Frequency High" │
│ GridFrequencyLow │ "Grid Frequency Low" │
│ GridVACHigh │ "Grid VAC High" │
│ GridVACLow │ "Grid VAC Low" │
│ NoExternalPower │ "No External Power" │
│ MissingPhase │ "Missing Phase" │
│ PhaseSequence │ "Phase Sequence" │
│ LoadDisconnection │ "Load Disconnection" │
│ MotorDisconnection │ "Motor Disconnection" │
│ NoBoardCom │ "Communication Timeout" │
│ NoInternetAccess │ "No InternetAccess" │
│ ComPort1 │ "Com Port1" │
│ ComPort2 │ "Com Port2" │
│ HiCurrNeut │ "Hi Curr Neut" │
│ HiCurrMot1 │ "Hi Curr Mot1" │
│ HiCurrMot2 │ "Hi Curr Mot2" │
└─────────────────────────────────────────────────────────────┘
Error UI States:
• Hidden: No errors present
• Warning Icon: Errors detected but not critical
• Error Popup: Critical errors requiring attention
• Locked Interface: Safety interlock engaged
```
## Recovery and Reset Procedures
### Automatic Recovery
```
Automatic Recovery Process:
┌─────────────────────────────────────────────────────────────┐
│ RECOVERY SYSTEM │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Condition │───▶│ Automatic │ │
│ │ Monitoring │ │ Recovery │ │
│ │ │ │ │ │
│ │ Continuous │ │ if (condition │ │
│ │ check if error │ │ resolved) { │ │
│ │ conditions │ │ error.is │ │
│ │ still exist │ │ Deleted=true; │ │
│ │ │ │ } │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ UI RESTORATION │ │
│ │ │ │
│ │ When no errors remain: │ │
│ │ • Hide error indicators │ │
│ │ • Re-enable disabled controls │ │
│ │ • Resume recipe if paused │ │
│ │ • Restore normal operation mode │ │
│ │ │ │
│ │ if (errors.Count == 0) { │ │
│ │ errorLogo.IsVisible = false; │ │
│ │ settings.mixerBtn.IsEnabled = true; │ │
│ │ settings.fountainBtn.IsEnabled = true; │ │
│ │ if (recipePaused) ResumeRecipe(); │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Manual Reset Procedures
```
Manual Reset Operations:
┌─────────────────────────────────────────────────────────────┐
│ RESET HIERARCHY │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Operator Reset │ │ Technician │ │
│ │ │ │ Reset │ │
│ │ • Clear │ │ │ │
│ │ warnings │ │ • Clear all │ │
│ │ • Resume │ │ errors │ │
│ │ operations │ │ • Reset safety │ │
│ │ • Restart │ │ interlocks │ │
│ │ paused │ │ • Reinitialize │ │
│ │ recipes │ │ hardware │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Admin Reset │ │ Emergency │ │
│ │ │ │ Reset │ │
│ │ • Factory │ │ │ │
│ │ defaults │ │ • Hardware │ │
│ │ • System │ │ emergency │ │
│ │ configuration │ │ stop │ │
│ │ • Hardware │ │ • Full system │ │
│ │ recalibration │ │ shutdown │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Reset Implementation
```
Error Reset Functions:
┌─────────────────────────────────────────────────────────────┐
│ // Manual Error Reset (UI Button) │
│ private async void ResetErrors(object? sender, args e) { │
│ holdingRegister.resetError = (ushort)(1 << 0); │
│ await WriteToSerialAsync("ResetErrors"); │
│ } │
│ │
│ // Automatic Error Clearing │
│ if (conditionClear) { │
│ var error = errors.FirstOrDefault( │
│ x => x.Condition == targetCondition); │
│ if (error != null) { │
│ error.isDeleted = true; // Mark for removal │
│ } │
│ } │
│ │
│ // System Reset (Complete) │
│ public void resetAll() { │
│ // Stop all timers │
│ // Reset all state variables │
│ // Clear error collections │
│ // Restore default hardware state │
│ // Re-enable UI controls │
│ } │
└─────────────────────────────────────────────────────────────┘
```
## Communication Error Handling
### Modbus Communication Reliability
```
Communication Error Strategy:
┌─────────────────────────────────────────────────────────────┐
│ COMMUNICATION RESILIENCE │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Message Sending │───▶│ Response │ │
│ │ │ │ Validation │ │
│ │ • CRC │ │ │ │
│ │ calculation │ │ • CRC check │ │
│ │ • Timeout │ │ • Length verify │ │
│ │ setting │ │ • Content │ │
│ │ • Queue │ │ validation │ │
│ │ management │ │ │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ Success ◄───┐ Failure ────┐ │
│ │ │ │ │ │
│ ▼ │ ▼ │ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Continue │ │ Retry Logic │ │
│ │ Operation │ │ │ │
│ │ │ │ • Max 3 retries │ │
│ │ • Update state │ │ • Exponential │ │
│ │ • Clear timeout │ │ backoff │ │
│ │ • Next message │ │ • Error logging │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ All Retries Failed │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Communication Error │ │
│ │ • Set NoBoardCom error │ │
│ │ • Disable new commands │ │
│ │ • Continue monitoring │ │
│ │ • Show error status │ │
│ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Network Connectivity Monitoring
```
Network Error Detection:
┌─────────────────────────────────────────────────────────────┐
│ CheckInternetLoop Thread: │
│ │
│ public static bool IsInternetAvailable() { │
│ try { │
│ var networkInterfaces = │
│ NetworkInterface.GetAllNetworkInterfaces(); │
│ │
│ foreach (var ni in networkInterfaces) { │
│ if (ni.OperationalStatus == Up) { │
│ using (var ping = new Ping()) { │
│ var reply = ping.Send("8.8.8.8", 3000);│
│ if (reply.Status == IPStatus.Success) {│
│ return true; │
│ } │
│ } │
│ } │
│ } │
│ } catch (Exception) { │
│ return false; │
│ } │
│ return false; │
│ } │
│ │
│ Error Action: │
│ • Add NoInternetAccess error if ping fails │
│ • Clear error when connectivity restored │
│ • Update network status indicators │
└─────────────────────────────────────────────────────────────┘
```
## Safety System Validation
### Self-Test Procedures
```
System Self-Test:
┌─────────────────────────────────────────────────────────────┐
│ STARTUP VALIDATION │
│ │
│ Application Startup: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 1. Hardware Communication Test │ │
│ │ • Verify serial port access │ │
│ │ • Test Modbus communication │ │
│ │ • Validate hardware responses │ │
│ │ │ │
│ │ 2. Configuration Validation │ │
│ │ • Check CSV file integrity │ │
│ │ • Validate parameter ranges │ │
│ │ • Verify mapping consistency │ │
│ │ │ │
│ │ 3. Safety System Check │ │
│ │ • Test error detection logic │ │
│ │ • Verify safety interlocks │ │
│ │ • Validate emergency stop functions │ │
│ │ │ │
│ │ 4. Sensor Calibration │ │
│ │ • Check temperature sensor readings │ │
│ │ • Validate current measurements │ │
│ │ • Verify voltage monitoring │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ Periodic Testing (During Operation): │
│ • Communication heartbeat monitoring │
│ • Sensor drift detection │
│ • Safety system responsiveness │
│ • Error recovery validation │
└─────────────────────────────────────────────────────────────┘
```
This error handling and safety systems specification provides comprehensive coverage of the current system's approach to error detection, safety enforcement, and recovery procedures, highlighting both strengths and areas for improvement in any migration effort.