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