---
title: Joystick Component
description: Documentation for the Joystick input component for ESP32 platform
keywords: [joystick, input device, ESP32, modbus, industrial]
---

## Joystick

**Path**: [`./src/components/Joystick.cpp`](../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](./Component.md) - Base component class
- [ModbusTCP](./ModbusTCP.md) - Modbus TCP protocol implementation
- [Bridge](./Bridge.md) - Serial communication bridge
- [config.h](./config.md) - System configuration

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

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

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