124 lines
3.5 KiB
Markdown
124 lines
3.5 KiB
Markdown
---
|
|
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
|
|
|