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

title	description	keywords
Joystick 4-Position Component	Documentation for the Joystick component, a 4-position joystick controller with local and remote operation modes.	joystick, ESP32, modbus, component, controller, input device

Joystick

Path: src/components/Joystick.cpp

Revision History: Initial documentation

The Joystick component provides an interface for a 4-position joystick (up, down, left, right) with support for both local physical operation and remote control via Modbus. It features position debouncing for reliable readings, position state tracking, and seamless switching between local and remote operation modes.

REQUIREMENTS

• Four GPIO pins for joystick inputs (up, down, left, right)
• Pull-up resistors (internal or external) for each input
• Modbus support for remote operation

FEATURES

• 5 distinct positions: UP, DOWN, LEFT, RIGHT, and CENTER
• Configurable debouncing for reliable position readings
• Position state tracking with timing information
• Switchable operation modes:
  • LOCAL: reads physical joystick position
  • REMOTE: accepts position commands via Modbus
• Complete Modbus integration
• Position holding time tracking

DEPENDENCIES

• ArduinoLog
• ModbusTCP
• Component

graph TD
    Joystick --> Component
    Joystick --> ModbusTCP
    Joystick --> ArduinoLog
    Component --> ArduinoLog

BEHAVIOUR

stateDiagram-v2
    [*] --> Setup
    Setup --> LocalMode
    Setup --> RemoteMode
    
    LocalMode --> ReadPosition
    LocalMode --> RemoteMode: setMode(REMOTE)
    
    ReadPosition --> Debouncing: useDebouncing true
    ReadPosition --> UpdatePosition: useDebouncing false
    
    Debouncing --> UpdatePosition: confirmCount >= threshold
    UpdatePosition --> NotifyChange: position changed
    
    RemoteMode --> LocalMode: setMode(LOCAL)
    RemoteMode --> OverridePosition: setOverridePosition()
    OverridePosition --> NotifyChange
    
    NotifyChange --> LocalMode
    NotifyChange --> RemoteMode

TODOS

PERFORMANCE

• Consider optimizing the debouncing algorithm for specific application needs
• Evaluate if READ_INTERVAL_MS (25ms) can be adjusted based on application requirements

SECURITY

• Implement input validation for Modbus commands
• Consider adding authentication for remote mode switching

COMPLIANCE

• Ensure compliance with relevant industrial control standards
• Review electrical safety requirements for the connected joystick hardware

RECOMMENDATIONS

• Use hardware debouncing circuits when possible to reduce CPU load
• Implement additional position combinations if needed (e.g., diagonal positions)
• Consider adding filter capacitors on input pins for noisy environments

EXAMPLE

#ifdef PIN_JOYSTICK_UP
  joystick = new Joystick(
      this,                // owner
      PIN_JOYSTICK_UP,     // pinUp
      PIN_JOYSTICK_DOWN,   // pinDown
      PIN_JOYSTICK_LEFT,   // pinLeft
      PIN_JOYSTICK_RIGHT,  // pinRight
      JOYSTICK_MB_ADDR     // modbusAddress
  );
  if (joystick) {
    components.push_back(joystick);
    Log.infoln(F("Joystick initialized. Pins - Up:%d Down:%d Left:%d Right:%d, MB:%d"),
               PIN_JOYSTICK_UP, PIN_JOYSTICK_DOWN, 
               PIN_JOYSTICK_LEFT, PIN_JOYSTICK_RIGHT, 
               JOYSTICK_MB_ADDR);
  } else {
    Log.errorln(F("Joystick initialization failed."));
  }
#endif

References