firmware-base/docs/Plunger.md

---
title: "Plunger Component"
description: "Documentation for the Plunger component that controls plunging operations with a SAKO VFD"
keywords: ["plunger", "VFD", "SAKO", "filling", "industrial", "component", "ESP32"]
---

# Plunger

**Path**: [src/components/Plunger.cpp](../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](./SAKO_VFD.md) - Controls the Variable Frequency Drive
- [Joystick](./Joystick.md) - Provides manual control input
- [POT](./POT.md) - Analog inputs for speed and torque control
- [Component](./Component.md) - Base component class
- [ModbusTCP](./ModbusTCP.md) - For Modbus communication
- [ArduinoJson](https://arduinojson.org/) - For settings management
- [PlungerSettings](./PlungerSettings.md) - Configuration parameters

```mermaid
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:

```mermaid
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:

```cpp
#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}