firmware-base/docs/Plunger.md

title	description	keywords
Plunger Component	Documentation for the Plunger component that controls plunging operations with a SAKO VFD	plunger VFD SAKO filling industrial component ESP32

Plunger

Path: src/components/Plunger.cpp

Revision History: Initial documentation

The Plunger component provides control for a plunger mechanism driven by a SAKO Variable Frequency Drive (VFD). It manages plunging, homing, filling operations, and detects jams through current monitoring. The component supports both manual joystick control and automated operational modes.

Requirements

Hardware

• SAKO Variable Frequency Drive (VFD)
• Joystick for manual control
• Two potentiometers (POTs):
  • Speed POT for controlling plunging speed
  • Torque POT for controlling jam sensitivity
• ESP32 with appropriate GPIO pins for interfaces

Configuration

• Plunger component uses the component ID 760 (PLUNGER_COMPONENT_ID)
• Modbus base address is configured using COMPONENT_KEY_PLUNGER (670)
• VFD must be properly configured to report current values

Features

• Manual Control: Direct joystick-based plunger movement control
• Automatic Operations: Timed automatic plunging and homing
• Record and Replay: Ability to record plunging operations and replay them (up to 20 seconds)
• Filling Cycle: Automated fill procedure with configurable parameters
• Post-Flow Control: Additional material flow control after main operations
• Jam Detection: Current-based jam detection with automatic recovery
• Modbus Interface: Remote control and monitoring via Modbus TCP
• Configurable Settings: Adjustable speed, current thresholds, and timing parameters
• Persistence: Settings can be saved to and loaded from JSON files

Dependencies

• SAKO_VFD - Controls the Variable Frequency Drive
• Joystick - Provides manual control input
• POT - Analog inputs for speed and torque control
• Component - Base component class
• ModbusTCP - For Modbus communication
• ArduinoJson - For settings management
• PlungerSettings - Configuration parameters

graph TD
    Plunger --> SAKO_VFD
    Plunger --> Joystick
    Plunger --> POT
    Plunger --> Component
    Plunger --> ModbusTCP
    Plunger --> PlungerSettings

Behaviour

The Plunger component implements a state machine that manages different operational states:

stateDiagram-v2
    IDLE --> HOMING_MANUAL: Joystick DOWN
    IDLE --> PLUNGING_MANUAL: Joystick UP
    IDLE --> RECORD: Hold Joystick RIGHT
    IDLE --> FILLING: Hold Joystick LEFT
    IDLE --> REPLAY: Command
    
    HOMING_MANUAL --> HOMING_AUTO: Hold time reached
    HOMING_MANUAL --> IDLE: Joystick released
    HOMING_AUTO --> IDLE: Complete/Stop
    
    PLUNGING_MANUAL --> PLUNGING_AUTO: Hold time reached
    PLUNGING_MANUAL --> IDLE: Joystick released
    PLUNGING_AUTO --> IDLE: Complete/Stop
    
    PLUNGING_AUTO --> POST_FLOW: Enable post-flow
    POST_FLOW --> IDLE: Complete
    
    PLUNGING_AUTO --> JAMMED: High current
    HOMING_AUTO --> JAMMED: High current
    JAMMED --> RESETTING_JAM: Auto-recovery
    RESETTING_JAM --> IDLE: Reset complete
    
    RECORD --> IDLE: Complete/Stop
    REPLAY --> IDLE: Complete/Stop
    
    FILLING --> IDLE: Complete/Stop
    
    STOPPING --> IDLE: VFD stopped

TODOs

Performance

• Consider optimizing the current monitoring frequency to reduce CPU load
• Evaluate the need for additional filtering of current readings to avoid false jam detections
• Profile the performance impact of JSON operations for settings management
• Optimize state transition logic to reduce processing overhead

Security

• Implement validation of Modbus command values to prevent unexpected operations
• Consider adding authentication for settings modification via REST API
• Ensure proper bounds checking for all user-configurable parameters
• Add protection against invalid state transitions triggered by external commands

Compliance

• Verify compliance with relevant industrial safety standards for automated machinery
• Ensure emergency stop functionality meets IEC 60204-1 requirements
• Consider implementing logging for operational data to support audit requirements
• Add failure mode analysis and redundant safety mechanisms

Recommendations

• Implement a calibration procedure for current thresholds based on actual plunger load
• Consider adding temperature monitoring to detect VFD overheating
• Add additional sensor inputs (e.g., limit switches) for improved position feedback
• Implement more sophisticated jam detection based on current trend analysis rather than fixed thresholds
• Consider expanding the configuration options to support different materials and plunger sizes
• Add persistent logging of jam events to identify patterns

Example

This example shows how to initialize the Plunger component in a system:

#ifdef ENABLE_PLUNGER
  // Check if required components are available
  if (sakoVfd && joystick && speedPot && torquePot) {
    plunger = new Plunger(
      this,       // owner
      sakoVfd,    // VFD controller
      joystick,   // joystick for manual control
      speedPot,   // POT for speed control
      torquePot   // POT for torque/jam sensitivity
    );
    
    if (plunger) {
      components.push_back(plunger);
      Log.infoln(F("Plunger initialized with VFD, Joystick, and POTs"));
      
      // Load stored settings or use defaults
      plunger->loadDefaultSettings();
    } else {
      Log.errorln(F("Plunger initialization failed."));
    }
  } else {
    Log.warningln(F("Plunger not initialized - missing required components."));
  }
#endif

References

${DOXYGEN_PLACEHOLDER}

${VENDOR_PLACEHOLDER}