6.4 KiB
6.4 KiB
| title | description | keywords | ||||||
|---|---|---|---|---|---|---|---|---|
| Plunger Component Documentation | Documentation for the Plunger component in an ESP-32 industrial device with Modbus-485 capability |
|
Plunger
Path: src/Plunger.cpp
Revision History: Initial documentation
The Plunger component controls a motor-driven plunger mechanism through a Variable Frequency Drive (VFD). It manages various states including homing, plunging, filling operations, and post-flow sequences while allowing both manual and automatic operation modes.
Requirements
Hardware
- VFD-controlled motor connected to plunger mechanism
- Joystick peripheral for manual control
- Modbus-485 communication interface
Configuration
- Multiple configurable speed settings
- Operation timing parameters
- Auto mode hold durations
Features
- Multiple operation modes:
- Manual control via joystick
- Auto mode via joystick hold
- Replay of recorded plunge sequences
- Filling sequence with configurable parameters
- Post-flow sequence for pressure maintenance
- State machine design with comprehensive state transitions
- Jam detection and recovery
- Modbus control interface
- Configurable timings and speeds
- Recording and replaying of plunge operations
Dependencies
graph TD
Plunger --> VFD
Plunger --> Joystick
Plunger --> Ticker
Plunger --> ModbusTCP
Plunger --> Arduino
Behavior
The Plunger component operates as a state machine with the following states:
stateDiagram-v2
[*] --> IDLE
IDLE --> HOMING_MANUAL: Joystick UP
IDLE --> PLUNGING_MANUAL: Joystick DOWN
IDLE --> FILLING: Joystick LEFT + HOLD
IDLE --> RECORD: Joystick RIGHT + HOLD
IDLE --> REPLAY: Joystick RIGHT + BRIEF
HOMING_MANUAL --> HOMING_AUTO: HOLD > autoModeHoldDuration
HOMING_MANUAL --> STOPPING: Joystick release
PLUNGING_MANUAL --> PLUNGING_AUTO: HOLD > autoModeHoldDuration
PLUNGING_MANUAL --> STOPPING: Joystick release
HOMING_AUTO --> STOPPING: Joystick non-center after release
PLUNGING_AUTO --> STOPPING: Joystick non-center after release
RECORD --> IDLE: Joystick non-RIGHT
REPLAY --> STOPPING: Joystick non-CENTER
REPLAY --> POST_FLOW: Plunge completed, post-flow enabled
REPLAY --> IDLE: Plunge completed, post-flow disabled
FILLING --> STOPPING: Joystick non-CENTER after release
JAMMED --> RESETTING_JAM
RESETTING_JAM --> HOMING_MANUAL: Joystick UP
RESETTING_JAM --> IDLE: Joystick non-UP/non-CENTER
POST_FLOW --> STOPPING: Joystick non-CENTER after release
POST_FLOW --> IDLE: Post-flow completed
STOPPING --> IDLE
state FILLING {
[*] --> PLUNGING
PLUNGING --> PLUNGED: Plunge completed
PLUNGED --> HOMING: Plunged wait timeout
HOMING --> HOMED: Home completed
HOMED --> [*]: Homed wait timeout
}
state POST_FLOW {
[*] --> POST_FLOW_STOPPING
POST_FLOW_STOPPING --> POST_FLOW_STARTING: Stopping wait timeout
POST_FLOW_STARTING --> POST_FLOW_COMPLETE: Duration timeout
POST_FLOW_COMPLETE --> [*]: Complete wait timeout
}
note right of IDLE: Default state waiting for input
note right of JAMMED: Detected overcurrent condition
note right of STOPPING: Transitional state to IDLE
TODOs
Performance
- Consider optimizing timer usage to reduce RAM footprint
- Evaluate performance impact of multiple state transitions during operation
- Implement configurable acceleration/deceleration profiles for smoother operation
- Assess VFD command frequency to prevent communication bottlenecks
Security
- Implement validation of Modbus command sources
- Add access control to prevent unauthorized command execution
- Consider adding confirmation requirements for critical operations
- Log and alert on suspicious command patterns
Compliance
- Ensure compliance with relevant machine safety standards
- Consider implementing additional safety interlocks
- Document safety requirements and certifications
- Follow applicable electrical code requirements for industrial equipment
Recommendations
- Monitor VFD current to detect potential mechanical issues before jam events
- Implement a maintenance log for plunger operations
- Consider adding physical position sensing for more precise control
- Develop UX guidelines for joystick operation to minimize user error
- Create a calibration routine for optimal performance with different materials
Example
The following example shows how to initialize and mount a Plunger component:
#ifdef PIN_PLUNGER_1_ENABLE
vfd_1 = new VFD(
this, // owner
PIN_PLUNGER_1_ENABLE, // enablePin
PIN_PLUNGER_1_FORWARD, // forwardPin
PIN_PLUNGER_1_COM, // communicationPin
PIN_PLUNGER_1_ALARM, // alarmPin
PLUNGER_1_ID_VFD // id
);
joystick_1 = new Joystick(
this, // owner
PIN_PLUNGER_1_JOYSTICK_X, // pinX
PIN_PLUNGER_1_JOYSTICK_Y, // pinY
PLUNGER_1_ID_JOYSTICK // id
);
if (vfd_1 && joystick_1)
{
plunger_1 = new Plunger(
this, // owner
vfd_1, // vfd
joystick_1, // joystick
PLUNGER_1_ID // id
);
// Configure plunger settings
plunger_1->settings.speedRampHz = PLUNGER_1_SPEED_RAMP_HZ;
plunger_1->settings.speedSlowHz = PLUNGER_1_SPEED_SLOW_HZ;
plunger_1->settings.speedMaxHz = PLUNGER_1_SPEED_MAX_HZ;
plunger_1->settings.autoModeHoldDurationMs = PLUNGER_1_AUTO_MODE_HOLD_DURATION_MS;
plunger_1->settings.defaultMaxOperationDurationMs = PLUNGER_1_MAX_OPERATION_DURATION_MS;
plunger_1->settings.enablePostFlow = PLUNGER_1_ENABLE_POST_FLOW;
// Add to components list
if (plunger_1) {
components.push_back(vfd_1);
components.push_back(joystick_1);
components.push_back(plunger_1);
Log.infoln(F("Plunger_1 initialized with VFD and Joystick"));
}
else {
Log.errorln(F("Plunger_1 initialization failed."));
}
}
else {
Log.errorln(F("VFD_1 or Joystick_1 initialization failed, cannot create Plunger_1."));
}
#endif