components
This commit is contained in:
@@ -0,0 +1,540 @@
|
||||
# Machine Constants Manager Component Specification
|
||||
|
||||
**Component ID:** C-MC-001
|
||||
**Component Name:** Machine Constants Manager
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
|
||||
## 1. Component Overview
|
||||
|
||||
### 1.1 Purpose
|
||||
The Machine Constants Manager is responsible for managing static and semi-static configuration parameters for the Sensor Hub, including sensor configuration, calibration parameters, communication settings, and system identity information. It provides centralized configuration management with support for remote updates and controlled reinitialization.
|
||||
|
||||
### 1.2 Scope
|
||||
- Machine Constants dataset management
|
||||
- Sensor configuration and calibration parameters
|
||||
- Communication identifiers and settings
|
||||
- System identity and addressing parameters
|
||||
- Configuration validation and integrity checking
|
||||
- Remote configuration updates with controlled application
|
||||
|
||||
### 1.3 Responsibilities
|
||||
- Load and validate Machine Constants during system initialization
|
||||
- Provide configuration data to system components
|
||||
- Support remote Machine Constants updates from Main Hub
|
||||
- Implement controlled teardown and reinitialization for updates
|
||||
- Maintain configuration version control and rollback capability
|
||||
- Ensure configuration data integrity and consistency
|
||||
|
||||
## 2. Component Architecture
|
||||
|
||||
### 2.1 Static View
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Machine Constants Manager"
|
||||
MCM[MC Controller]
|
||||
MCL[MC Loader]
|
||||
MCV[MC Validator]
|
||||
MCU[MC Updater]
|
||||
MCS[MC Storage]
|
||||
end
|
||||
|
||||
subgraph "Configuration Data"
|
||||
SC[Sensor Config]
|
||||
CC[Communication Config]
|
||||
CAL[Calibration Data]
|
||||
SID[System Identity]
|
||||
end
|
||||
|
||||
subgraph "External Interfaces"
|
||||
FS[File System]
|
||||
CM[Communication Manager]
|
||||
STM[System State Manager]
|
||||
end
|
||||
|
||||
MCM --> MCL
|
||||
MCM --> MCV
|
||||
MCM --> MCU
|
||||
MCM --> MCS
|
||||
|
||||
MCL --> SC
|
||||
MCL --> CC
|
||||
MCL --> CAL
|
||||
MCL --> SID
|
||||
|
||||
MCS --> FS
|
||||
MCU --> CM
|
||||
MCU --> STM
|
||||
```
|
||||
|
||||
### 2.2 Internal Components
|
||||
|
||||
#### 2.2.1 MC Controller
|
||||
- Central coordination of Machine Constants operations
|
||||
- Configuration access control and policy enforcement
|
||||
- Component lifecycle management
|
||||
|
||||
#### 2.2.2 MC Loader
|
||||
- Configuration file loading and parsing
|
||||
- Schema validation and compatibility checking
|
||||
- Default configuration handling
|
||||
|
||||
#### 2.2.3 MC Validator
|
||||
- Configuration data validation and consistency checking
|
||||
- Cross-reference validation between configuration sections
|
||||
- Range and format validation
|
||||
|
||||
#### 2.2.4 MC Updater
|
||||
- Remote configuration update handling
|
||||
- Update validation and staging
|
||||
- Controlled application of configuration changes
|
||||
|
||||
#### 2.2.5 MC Storage
|
||||
- Configuration persistence and retrieval
|
||||
- Backup and rollback management
|
||||
- Configuration versioning
|
||||
|
||||
## 3. Interfaces
|
||||
|
||||
### 3.1 Provided Interfaces
|
||||
|
||||
#### 3.1.1 IMachineConstantsManager
|
||||
```cpp
|
||||
class IMachineConstantsManager {
|
||||
public:
|
||||
virtual ~IMachineConstantsManager() = default;
|
||||
|
||||
// Initialization and Lifecycle
|
||||
virtual Result<void> initialize() = 0;
|
||||
virtual Result<void> reload() = 0;
|
||||
virtual Result<void> shutdown() = 0;
|
||||
|
||||
// Configuration Access
|
||||
virtual Result<SensorConfig> getSensorConfig(SensorId sensor_id) const = 0;
|
||||
virtual Result<CommunicationConfig> getCommunicationConfig() const = 0;
|
||||
virtual Result<CalibrationData> getCalibrationData(SensorId sensor_id) const = 0;
|
||||
virtual Result<SystemIdentity> getSystemIdentity() const = 0;
|
||||
|
||||
// Configuration Queries
|
||||
virtual std::vector<SensorId> getConfiguredSensors() const = 0;
|
||||
virtual bool isSensorConfigured(SensorId sensor_id) const = 0;
|
||||
virtual ConfigurationVersion getConfigurationVersion() const = 0;
|
||||
virtual ConfigurationSummary getConfigurationSummary() const = 0;
|
||||
|
||||
// Configuration Updates
|
||||
virtual Result<void> receiveConfigurationUpdate(const ConfigurationUpdate& update) = 0;
|
||||
virtual Result<void> validateConfigurationUpdate(const ConfigurationUpdate& update) const = 0;
|
||||
virtual Result<void> applyConfigurationUpdate() = 0;
|
||||
virtual Result<void> rollbackConfiguration() = 0;
|
||||
|
||||
// Configuration Management
|
||||
virtual Result<void> backupConfiguration() = 0;
|
||||
virtual Result<void> restoreConfiguration(ConfigurationVersion version) = 0;
|
||||
virtual std::vector<ConfigurationVersion> getAvailableVersions() const = 0;
|
||||
};
|
||||
```
|
||||
|
||||
#### 3.1.2 ICalibrationProvider
|
||||
```cpp
|
||||
class ICalibrationProvider {
|
||||
public:
|
||||
virtual ~ICalibrationProvider() = default;
|
||||
virtual Result<CalibrationData> getCalibrationData(SensorId sensor_id) const = 0;
|
||||
virtual Result<void> updateCalibrationData(SensorId sensor_id,
|
||||
const CalibrationData& data) = 0;
|
||||
virtual bool isCalibrationValid(SensorId sensor_id) const = 0;
|
||||
virtual std::chrono::system_clock::time_point getCalibrationDate(SensorId sensor_id) const = 0;
|
||||
};
|
||||
```
|
||||
|
||||
#### 3.1.3 IConfigurationManager
|
||||
```cpp
|
||||
class IConfigurationManager {
|
||||
public:
|
||||
virtual ~IConfigurationManager() = default;
|
||||
virtual Result<ConfigValue> getConfigValue(const std::string& key) const = 0;
|
||||
virtual Result<void> setConfigValue(const std::string& key, const ConfigValue& value) = 0;
|
||||
virtual bool hasConfigValue(const std::string& key) const = 0;
|
||||
virtual std::vector<std::string> getConfigKeys() const = 0;
|
||||
};
|
||||
```
|
||||
|
||||
### 3.2 Required Interfaces
|
||||
|
||||
#### 3.2.1 IPersistenceManager
|
||||
- Configuration file storage and retrieval
|
||||
- Backup and versioning support
|
||||
- Data integrity verification
|
||||
|
||||
#### 3.2.2 ICommunicationManager
|
||||
- Reception of configuration updates from Main Hub
|
||||
- Configuration update acknowledgment
|
||||
- Update status reporting
|
||||
|
||||
#### 3.2.3 ISystemStateManager
|
||||
- System state management for configuration updates
|
||||
- Controlled teardown initiation
|
||||
- System reinitialization coordination
|
||||
|
||||
#### 3.2.4 IDiagnosticsManager
|
||||
- Configuration error reporting
|
||||
- Update status logging
|
||||
- Configuration validation results
|
||||
|
||||
## 4. Dynamic View
|
||||
|
||||
### 4.1 Configuration Loading Sequence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant SYS as System Controller
|
||||
participant MCM as MC Manager
|
||||
participant MCL as MC Loader
|
||||
participant MCV as MC Validator
|
||||
participant FS as File System
|
||||
|
||||
SYS->>MCM: initialize()
|
||||
MCM->>MCL: loadConfiguration()
|
||||
MCL->>FS: readConfigurationFile()
|
||||
FS-->>MCL: configuration_data
|
||||
MCL->>MCL: parseConfiguration()
|
||||
MCL->>MCV: validateConfiguration(config)
|
||||
MCV->>MCV: performValidation()
|
||||
|
||||
alt Validation Success
|
||||
MCV-->>MCL: validation_success
|
||||
MCL-->>MCM: configuration_loaded
|
||||
MCM-->>SYS: initialization_complete
|
||||
else Validation Failed
|
||||
MCV-->>MCL: validation_errors
|
||||
MCL->>MCL: loadDefaultConfiguration()
|
||||
MCL-->>MCM: default_configuration_loaded
|
||||
MCM-->>SYS: initialization_with_defaults
|
||||
end
|
||||
```
|
||||
|
||||
### 4.2 Configuration Update Sequence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant MH as Main Hub
|
||||
participant CM as Communication Manager
|
||||
participant MCM as MC Manager
|
||||
participant MCU as MC Updater
|
||||
participant STM as System State Manager
|
||||
participant MCS as MC Storage
|
||||
|
||||
MH->>CM: sendConfigurationUpdate(update_data)
|
||||
CM->>MCM: receiveConfigurationUpdate(update_data)
|
||||
MCM->>MCU: processUpdate(update_data)
|
||||
MCU->>MCU: validateUpdate(update_data)
|
||||
|
||||
alt Update Valid
|
||||
MCU->>MCS: stageUpdate(update_data)
|
||||
MCS-->>MCU: staging_complete
|
||||
MCU->>STM: requestTeardown(MC_UPDATE)
|
||||
STM->>STM: executeTeardown()
|
||||
STM-->>MCU: teardown_complete
|
||||
MCU->>MCS: applyUpdate()
|
||||
MCS-->>MCU: update_applied
|
||||
MCU->>STM: requestReinitialization()
|
||||
STM->>STM: reinitializeSystem()
|
||||
STM-->>MCU: reinitialization_complete
|
||||
MCU->>CM: sendUpdateAcknowledgment(SUCCESS)
|
||||
else Update Invalid
|
||||
MCU->>CM: sendUpdateAcknowledgment(VALIDATION_FAILED)
|
||||
end
|
||||
```
|
||||
|
||||
### 4.3 Configuration Access Sequence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant SM as Sensor Manager
|
||||
participant MCM as MC Manager
|
||||
participant SC as Sensor Config
|
||||
participant CAL as Calibration Data
|
||||
|
||||
SM->>MCM: getSensorConfig(TEMP_SENSOR_01)
|
||||
MCM->>SC: retrieveConfig(TEMP_SENSOR_01)
|
||||
SC-->>MCM: sensor_config
|
||||
MCM-->>SM: configuration_data
|
||||
|
||||
SM->>MCM: getCalibrationData(TEMP_SENSOR_01)
|
||||
MCM->>CAL: retrieveCalibration(TEMP_SENSOR_01)
|
||||
CAL-->>MCM: calibration_data
|
||||
MCM-->>SM: calibration_parameters
|
||||
```
|
||||
|
||||
## 5. Configuration Data Model
|
||||
|
||||
### 5.1 Machine Constants Structure
|
||||
```cpp
|
||||
struct MachineConstants {
|
||||
ConfigurationHeader header;
|
||||
SystemIdentity system_identity;
|
||||
CommunicationConfig communication;
|
||||
std::map<SensorId, SensorConfig> sensors;
|
||||
std::map<SensorId, CalibrationData> calibrations;
|
||||
SystemParameters system_parameters;
|
||||
SecurityConfig security;
|
||||
};
|
||||
```
|
||||
|
||||
### 5.2 Configuration Header
|
||||
```cpp
|
||||
struct ConfigurationHeader {
|
||||
std::string version;
|
||||
std::chrono::system_clock::time_point created_timestamp;
|
||||
std::chrono::system_clock::time_point modified_timestamp;
|
||||
std::string created_by;
|
||||
std::string description;
|
||||
uint32_t checksum;
|
||||
std::string schema_version;
|
||||
};
|
||||
```
|
||||
|
||||
### 5.3 System Identity
|
||||
```cpp
|
||||
struct SystemIdentity {
|
||||
std::string site_id;
|
||||
std::string house_id;
|
||||
std::string node_id;
|
||||
std::string hardware_version;
|
||||
std::string firmware_version;
|
||||
std::string serial_number;
|
||||
std::string installation_date;
|
||||
std::string location_description;
|
||||
};
|
||||
```
|
||||
|
||||
### 5.4 Sensor Configuration
|
||||
```cpp
|
||||
struct SensorConfig {
|
||||
SensorId sensor_id;
|
||||
SensorType sensor_type;
|
||||
std::string sensor_model;
|
||||
HardwareSlot hardware_slot;
|
||||
CommunicationInterface interface_type;
|
||||
std::map<std::string, ConfigValue> interface_parameters;
|
||||
SamplingConfig sampling;
|
||||
FilterConfig filtering;
|
||||
ValidationConfig validation;
|
||||
bool enabled;
|
||||
std::string description;
|
||||
};
|
||||
```
|
||||
|
||||
### 5.5 Calibration Data
|
||||
```cpp
|
||||
struct CalibrationData {
|
||||
SensorId sensor_id;
|
||||
CalibrationMethod method;
|
||||
std::vector<CalibrationPoint> calibration_points;
|
||||
PolynomialCoefficients coefficients;
|
||||
TemperatureCompensation temperature_compensation;
|
||||
std::chrono::system_clock::time_point calibration_date;
|
||||
std::chrono::system_clock::time_point expiry_date;
|
||||
std::string calibrated_by;
|
||||
std::string certificate_number;
|
||||
CalibrationAccuracy accuracy;
|
||||
};
|
||||
```
|
||||
|
||||
### 5.6 Communication Configuration
|
||||
```cpp
|
||||
struct CommunicationConfig {
|
||||
// MQTT Configuration
|
||||
MQTTConfig mqtt;
|
||||
|
||||
// ESP-NOW Configuration
|
||||
ESPNOWConfig espnow;
|
||||
|
||||
// Network Configuration
|
||||
NetworkConfig network;
|
||||
|
||||
// Security Configuration
|
||||
SecurityConfig security;
|
||||
|
||||
// Protocol Settings
|
||||
ProtocolSettings protocols;
|
||||
};
|
||||
```
|
||||
|
||||
## 6. Configuration Validation
|
||||
|
||||
### 6.1 Validation Rules
|
||||
```cpp
|
||||
class ConfigurationValidator {
|
||||
public:
|
||||
struct ValidationResult {
|
||||
bool is_valid;
|
||||
std::vector<ValidationError> errors;
|
||||
std::vector<ValidationWarning> warnings;
|
||||
};
|
||||
|
||||
ValidationResult validateConfiguration(const MachineConstants& config) const;
|
||||
ValidationResult validateSensorConfig(const SensorConfig& config) const;
|
||||
ValidationResult validateCalibrationData(const CalibrationData& data) const;
|
||||
ValidationResult validateCommunicationConfig(const CommunicationConfig& config) const;
|
||||
|
||||
private:
|
||||
bool validateSensorSlotMapping(const std::map<SensorId, SensorConfig>& sensors) const;
|
||||
bool validateCalibrationConsistency(const CalibrationData& data) const;
|
||||
bool validateNetworkParameters(const NetworkConfig& config) const;
|
||||
bool validateSecuritySettings(const SecurityConfig& config) const;
|
||||
};
|
||||
```
|
||||
|
||||
### 6.2 Validation Categories
|
||||
- **Schema Validation**: JSON schema compliance
|
||||
- **Range Validation**: Parameter value ranges
|
||||
- **Consistency Validation**: Cross-reference validation
|
||||
- **Hardware Validation**: Hardware compatibility checking
|
||||
- **Security Validation**: Security parameter validation
|
||||
|
||||
## 7. Configuration Storage
|
||||
|
||||
### 7.1 File Format
|
||||
- **Primary Format**: JSON for human readability and editability
|
||||
- **Schema Version**: Versioned schema for backward compatibility
|
||||
- **Encoding**: UTF-8 with optional compression
|
||||
- **Integrity**: CRC32 checksum for corruption detection
|
||||
|
||||
### 7.2 Storage Locations
|
||||
```cpp
|
||||
namespace ConfigPaths {
|
||||
constexpr const char* PRIMARY_CONFIG = "/config/machine_constants.json";
|
||||
constexpr const char* BACKUP_CONFIG = "/config/machine_constants.backup.json";
|
||||
constexpr const char* STAGING_CONFIG = "/config/machine_constants.staging.json";
|
||||
constexpr const char* DEFAULT_CONFIG = "/config/machine_constants.default.json";
|
||||
constexpr const char* VERSION_HISTORY = "/config/versions/";
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 Version Management
|
||||
- **Version Numbering**: Semantic versioning (major.minor.patch)
|
||||
- **Version History**: Configurable retention of previous versions
|
||||
- **Rollback Support**: Ability to revert to previous versions
|
||||
- **Backup Strategy**: Automatic backup before updates
|
||||
|
||||
## 8. Configuration Updates
|
||||
|
||||
### 8.1 Update Types
|
||||
```cpp
|
||||
enum class UpdateType {
|
||||
FULL_REPLACEMENT, // Complete configuration replacement
|
||||
PARTIAL_UPDATE, // Update specific sections
|
||||
SENSOR_ADDITION, // Add new sensor configuration
|
||||
SENSOR_REMOVAL, // Remove sensor configuration
|
||||
CALIBRATION_UPDATE, // Update calibration data only
|
||||
COMMUNICATION_UPDATE // Update communication settings
|
||||
};
|
||||
```
|
||||
|
||||
### 8.2 Update Process
|
||||
1. **Reception**: Receive update from Main Hub
|
||||
2. **Validation**: Validate update against current configuration
|
||||
3. **Staging**: Store update in staging area
|
||||
4. **Teardown**: Execute controlled system teardown
|
||||
5. **Application**: Apply staged configuration
|
||||
6. **Reinitialization**: Reinitialize system with new configuration
|
||||
7. **Verification**: Verify successful application
|
||||
8. **Acknowledgment**: Send update result to Main Hub
|
||||
|
||||
### 8.3 Rollback Mechanism
|
||||
- **Automatic Rollback**: On validation or application failure
|
||||
- **Manual Rollback**: Via diagnostic session or remote command
|
||||
- **Rollback Verification**: Ensure system stability after rollback
|
||||
- **Rollback Reporting**: Report rollback events and reasons
|
||||
|
||||
## 9. Error Handling
|
||||
|
||||
### 9.1 Error Categories
|
||||
- **File System Errors**: Configuration file access failures
|
||||
- **Parsing Errors**: JSON parsing or schema validation failures
|
||||
- **Validation Errors**: Configuration validation failures
|
||||
- **Update Errors**: Configuration update process failures
|
||||
- **Consistency Errors**: Configuration inconsistency detection
|
||||
|
||||
### 9.2 Error Recovery Strategies
|
||||
- **Default Configuration**: Fall back to default configuration
|
||||
- **Previous Version**: Rollback to last known good configuration
|
||||
- **Partial Recovery**: Use valid portions of configuration
|
||||
- **Safe Mode**: Minimal configuration for basic operation
|
||||
|
||||
## 10. Performance Characteristics
|
||||
|
||||
### 10.1 Timing Requirements
|
||||
- **Configuration Loading**: < 2 seconds during startup
|
||||
- **Configuration Access**: < 1ms for cached values
|
||||
- **Update Validation**: < 5 seconds for typical updates
|
||||
- **Update Application**: < 30 seconds including teardown/restart
|
||||
|
||||
### 10.2 Resource Usage
|
||||
- **Memory**: < 8KB for configuration cache
|
||||
- **Storage**: Configurable with version retention limits
|
||||
- **CPU**: Minimal impact during normal operation
|
||||
|
||||
## 11. Security Considerations
|
||||
|
||||
### 11.1 Configuration Security
|
||||
- **Access Control**: Restricted access to configuration files
|
||||
- **Integrity Protection**: Checksums and digital signatures
|
||||
- **Encryption**: Optional encryption for sensitive parameters
|
||||
- **Audit Trail**: Logging of configuration changes
|
||||
|
||||
### 11.2 Update Security
|
||||
- **Authentication**: Verify update source authenticity
|
||||
- **Authorization**: Validate update permissions
|
||||
- **Integrity**: Verify update data integrity
|
||||
- **Rollback Protection**: Prevent unauthorized rollbacks
|
||||
|
||||
## 12. Testing Strategy
|
||||
|
||||
### 12.1 Unit Tests
|
||||
- Configuration loading and parsing
|
||||
- Validation logic and error handling
|
||||
- Update processing and application
|
||||
- Rollback mechanisms
|
||||
|
||||
### 12.2 Integration Tests
|
||||
- End-to-end configuration update process
|
||||
- System reinitialization with new configuration
|
||||
- Cross-component configuration consistency
|
||||
- Error recovery scenarios
|
||||
|
||||
### 12.3 System Tests
|
||||
- Configuration update under various system states
|
||||
- Performance impact of configuration operations
|
||||
- Stress testing with large configurations
|
||||
- Security validation of update process
|
||||
|
||||
## 13. Dependencies
|
||||
|
||||
### 13.1 Internal Dependencies
|
||||
- Persistence Manager for file operations
|
||||
- System State Manager for teardown/restart coordination
|
||||
- Communication Manager for remote updates
|
||||
- Diagnostics Manager for error reporting
|
||||
|
||||
### 13.2 External Dependencies
|
||||
- JSON parsing library (e.g., nlohmann/json)
|
||||
- File system support (SPIFFS, FAT)
|
||||
- Cryptographic library for integrity verification
|
||||
- Schema validation library
|
||||
|
||||
## 14. Constraints and Assumptions
|
||||
|
||||
### 14.1 Constraints
|
||||
- Configuration size limited by available storage
|
||||
- Update process requires system restart
|
||||
- Configuration changes require controlled teardown
|
||||
- Version history limited by storage capacity
|
||||
|
||||
### 14.2 Assumptions
|
||||
- Reliable storage medium for configuration persistence
|
||||
- Sufficient system resources for configuration operations
|
||||
- Valid default configuration available as fallback
|
||||
- Proper authentication for configuration updates
|
||||
Reference in New Issue
Block a user