seb/saltylab-firmware
1
0
Fork 0
Code Issues Pull Requests 5 Actions Packages Projects Releases Wiki Activity
saltylab-firmware/phone/MOTOR_TEST_JOYSTICK.md
sl-android f49e84b8bb feat: Phone-based motor test joystick app (Issue #513) 
Implements terminal-based curses UI for interactive bench testing of SaltyBot motors via Termux.

Features:
- Interactive keyboard-based joystick (W/A/S/D or arrow keys)
- Conservative velocity defaults: 0.1 m/s linear, 0.3 rad/s angular
- Real-time velocity feedback with bar graphs
- Spacebar e-stop (instantly zeros velocity)
- 500ms timeout safety (sends zero velocity if idle)
- Dual backend: ROS2 (/cmd_vel) or WebSocket
- Graceful fallback if ROS2 unavailable

Safety Features:
- Conservative defaults (0.1/0.3 m/s)
- E-stop button (spacebar)
- 500ms timeout (sends zero if idle)
- Input clamping and exponential decay
- Status/warning displays

Files:
- motor_test_joystick.py: Main application
- MOTOR_TEST_JOYSTICK.md: User documentation
- INSTALL_MOTOR_TEST.md: Installation guide

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-03-06 11:47:15 -05:00

1.7 KiB
Raw Blame History

Motor Test Joystick (Issue #513)

Terminal-based interactive joystick for bench testing SaltyBot motors via Termux.

Quick Start

python3 motor_test_joystick.py  # ROS2 mode
python3 motor_test_joystick.py --backend websocket --host <jetson-ip>  # WebSocket mode

Controls

Key Action
W / ↑ Forward (linear +X)
S / ↓ Reverse (linear -X)
A / ← Turn left (angular +Z)
D / → Turn right (angular -Z)
SPACE E-stop toggle
R Reset velocities
Q Quit

Features

  • Real-time velocity feedback with bar graphs
  • Spacebar e-stop (instantly zeros velocity)
  • 500ms timeout safety (sends zero if idle)
  • Conservative defaults: 0.1 m/s linear, 0.3 rad/s angular
  • Dual backend: ROS2 (/cmd_vel) or WebSocket
  • Graceful fallback if ROS2 unavailable

Usage Examples

# Standard ROS2 mode
python3 motor_test_joystick.py

# WebSocket mode (fallback)
python3 motor_test_joystick.py --backend websocket --host 192.168.1.100

# Custom velocity limits
python3 motor_test_joystick.py --linear-max 0.5 --angular-max 1.0

Architecture

  • MotorTestController: State machine, velocity limiting, timeout enforcement
  • MotorTestNode (ROS2): Twist publisher to /cmd_vel
  • WebSocketController (fallback): JSON messages to Jetson
  • Curses UI: Non-blocking input, real-time feedback, status display

Safety

  • Conservative defaults (0.1/0.3 m/s)
  • E-stop button (spacebar)
  • 500ms timeout (auto-zero velocity)
  • Input clamping & exponential decay

Related Issues

  • #420 — Termux bootstrap & Android phone node
  • #512 — Autonomous arming (uses /cmd_vel)