firmware-base/docs/Joystick.md

title	description	keywords
Joystick Component	Documentation for the Joystick input component for ESP32 platform	joystick input device ESP32 modbus industrial

Joystick

Path: ./src/components/Joystick.cpp

Revision History: Initial documentation

The Joystick component provides an interface for a 4-position digital joystick (Up, Down, Left, Right) with a center position. It supports both local physical input and remote control via Modbus, allowing for integration into industrial control systems.

REQUIREMENTS

Hardware

• 4 digital input pins connected to joystick switches
• ESP32 microcontroller

Software

• Arduino framework
• ArduinoLog library
• Platform.io environment

FEATURES

• 5-position detection (UP, DOWN, LEFT, RIGHT, CENTER)
• Local and remote operation modes
• Position override capability via Modbus
• Input debouncing for reliable operation
• Position hold time tracking
• State change notification system
• Modbus integration for industrial control systems

DEPENDENCIES

• Component - Base component class
• ModbusTCP - Modbus TCP protocol implementation
• Bridge - Serial communication bridge
• config.h - System configuration

graph TD
  Joystick --> Component
  Joystick --> ModbusTCP
  Joystick --> Bridge
  Joystick --> Config

BEHAVIOUR

The Joystick operates in two modes: LOCAL and REMOTE. In LOCAL mode, it reads physical inputs from pins. In REMOTE mode, it uses an override position set via Modbus.

stateDiagram-v2
  [*] --> Setup
  Setup --> Idle
  Idle --> ReadPosition: If LOCAL mode
  ReadPosition --> Debounce: Read inputs
  Debounce --> UpdatePosition: Confirmed
  Debounce --> Idle: Not confirmed
  UpdatePosition --> Notify: Position changed
  Notify --> Idle
  Idle --> CheckRemote: If REMOTE mode
  CheckRemote --> UpdatePosition: Override changed
  CheckRemote --> Idle: No change

TODOS

PERFORMANCE

• Consider optimizing the debouncing algorithm for faster response in time-critical applications
• Evaluate interrupt-based approach instead of polling for reduced CPU overhead

SECURITY

• Add input validation for Modbus commands to prevent unexpected behavior
• Consider adding authentication for remote control mode switching

COMPLIANCE

• Ensure compliance with industrial standards for joystick controls
• Consider implementing emergency stop functionality

RECOMMENDATIONS

• Use pull-up or pull-down resistors with the input pins to ensure stable readings
• When using in industrial environments, consider adding hardware debouncing
• Implement application-level validation for critical operations controlled by the joystick

EXAMPLE

This example shows how to initialize and mount a Joystick component:

#ifdef PIN_JOYSTICK_UP
  joystick = new Joystick(
      this,               // owner
      PIN_JOYSTICK_UP,    // UP pin
      PIN_JOYSTICK_DOWN,  // DOWN pin
      PIN_JOYSTICK_LEFT,  // LEFT pin
      PIN_JOYSTICK_RIGHT, // RIGHT pin
      COMPONENT_KEY_JOYSTICK_0 // modbus address
  );
  if (joystick)
  {
    components.push_back(joystick);
    Log.infoln(F("Joystick initialized. Pins: UP=%d, DOWN=%d, LEFT=%d, RIGHT=%d, ID=%d"),
               PIN_JOYSTICK_UP, PIN_JOYSTICK_DOWN, 
               PIN_JOYSTICK_LEFT, PIN_JOYSTICK_RIGHT, 
               COMPONENT_KEY_JOYSTICK_0);
  }
  else
  {
    Log.errorln(F("Joystick initialization failed."));
  }
#endif

References