# 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.