38 KiB
38 KiB
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.