firmware-base/docs-c/components/PlungerSettings.md

title	description	keywords
Plunger Settings Component	Configuration management for plunger mechanism parameters with persistence capabilities	plunger settings configuration ESP32 json persistence

PlungerSettings

Path: src/PlungerSettings.h

Revision History: Initial documentation

PlungerSettings is a configuration management component for plunger mechanisms. It provides a structured way to define, store, and retrieve operational parameters for plunger controls, including speeds, timeouts, current thresholds, and behavioral settings. The component supports JSON serialization for persistent storage in the filesystem.

REQUIREMENTS

• LittleFS filesystem support for persistent storage
• JSON processing capabilities (via ArduinoJson)
• Logging functionality (ArduinoLog)

FEATURES

• Comprehensive parameter set for plunger operation control
• Default values based on predefined constants
• JSON serialization and deserialization
• Persistent storage in LittleFS
• Type-safe parameter parsing with error handling
• Detailed diagnostic logging

DEPENDENCIES

• Arduino.h
• ArduinoJson
• LittleFS
• ArduinoLog
• Plunger.h (for default constants)

graph TD
    PlungerSettings --> Arduino
    PlungerSettings --> ArduinoJson
    PlungerSettings --> LittleFS
    PlungerSettings --> ArduinoLog
    PlungerSettings --> Plunger

BEHAVIOUR

flowchart TD
    A[Constructor] --> B{Default Values}
    B -->|From Constants| C[Initialize Settings]
    B -->|From Parameters| D[Initialize Settings]
    
    E[Load Settings] --> F{File Exists?}
    F -->|Yes| G[Parse JSON]
    F -->|No| H[Keep Default Values]
    G --> I{Parse Success?}
    I -->|Yes| J[Update Settings]
    I -->|No| K[Keep Default Values]
    
    L[Save Settings] --> M[Serialize to JSON]
    M --> N[Write to File]
    
    O[fromJson] --> P[Parse Each Setting]
    P --> Q[Type Validation]
    Q -->|Valid| R[Update Setting]
    Q -->|Invalid| S[Keep Default Value]
    
    T[print] --> U[Log All Settings]

TODOS

PERFORMANCE

• Consider using a static JsonDocument with predefined capacity to avoid dynamic memory allocation
• Implement selective parameter updates to minimize file writes
• Add validation ranges for settings to prevent extreme values that might cause hardware issues

SECURITY

• Consider adding checksums or signatures to detect tampering with settings files
• Implement access control mechanisms for settings modification
• Sanitize inputs from external sources before applying to settings

COMPLIANCE

• Ensure parameter ranges comply with hardware specifications
• Add parameter validation to prevent unsafe mechanical operations
• Document any safety-critical parameters and their implications

RECOMMENDATIONS

• Create a web-based configuration interface for easy parameter adjustment
• Implement settings profiles for different operational scenarios
• Add ability to backup/restore settings to/from external storage
• Consider implementing periodic settings validation to detect drift or corruption

EXAMPLE

The PlungerSettings component can be used as follows:

// Create settings object with default values
PlungerSettings settings;

// Load saved settings from filesystem
if (settings.load()) {
  Log.infoln("Loaded plunger settings from filesystem");
} else {
  Log.warningln("Using default plunger settings");
  
  // Save current defaults to create the settings file
  settings.save();
}

// Access settings
uint16_t speed = settings.speedMediumHz;

// Update a setting
settings.currentJamThresholdMa = 1200;

// Save updated settings
settings.save();

// Debug output all settings
settings.print();

References

Documentation for the PlungerSettings class including JSON serialization and deserialization methods, persistent storage capabilities, and configuration parameters for plunger operation control.