# Motor Test Joystick Installation (Issue #513)

Quick setup guide for installing motor_test_joystick.py on Termux.

## Prerequisites

- Android phone with Termux installed
- Python 3.9+ (installed via termux-bootstrap.sh)
- ROS2 Humble OR Jetson bridge running on networked Jetson Orin

## Installation

### 1. Copy script to phone

```bash
# Option A: Via git
cd ~
git clone https://gitea.vayrette.com/seb/saltylab-firmware.git

# Option B: Via adb
adb push phone/motor_test_joystick.py /data/data/com.termux/files/home/
```

### 2. Make executable

```bash
chmod +x ~/saltylab-firmware/phone/motor_test_joystick.py
```

## Quick Test

### 1. Start on phone (Termux)

**ROS2 mode** (requires Jetson ros_core running):
```bash
python3 ~/saltylab-firmware/phone/motor_test_joystick.py
```

**WebSocket mode** (if Jetson IP is 192.168.1.100):
```bash
python3 ~/saltylab-firmware/phone/motor_test_joystick.py \
  --backend websocket \
  --host 192.168.1.100
```

### 2. Verify on Jetson

```bash
ros2 topic echo /cmd_vel
```

### 3. Safety test

1. Move joystick (W key)
2. Watch /cmd_vel values change
3. Press spacebar (E-stop)
4. Verify velocities go to 0.0
5. Press Q to quit

## Configuration

### Adjust velocity limits

```bash
# Conservative (default)
python3 motor_test_joystick.py  # 0.1 m/s, 0.3 rad/s

# Moderate
python3 motor_test_joystick.py --linear-max 0.3 --angular-max 0.8

# Aggressive
python3 motor_test_joystick.py --linear-max 0.5 --angular-max 1.5
```

### Change Jetson address

```bash
# Static IP
python3 motor_test_joystick.py --backend websocket --host 192.168.1.100

# mDNS hostname
python3 motor_test_joystick.py --backend websocket --host saltybot.local

# Different port
python3 motor_test_joystick.py --backend websocket --host 192.168.1.100 --port 8080
```

## Troubleshooting

### "ROS2 module not found"
→ Use WebSocket backend: `--backend websocket --host <jetson-ip>`

### "Connection refused" (WebSocket mode)
→ Check Jetson IP, verify bridge listening on :9090

### Motors not responding
1. Verify e-stop status (should show "Inactive")
2. Check timeout warning (>500ms = zero velocity)
3. Monitor Jetson: `ros2 topic echo /cmd_vel`
4. Verify network connectivity

### Terminal display issues
- Try `reset` or `stty sane` in Termux
- Increase terminal size (pinch-zoom)
- Use external keyboard (more reliable)

## Safety Checklist

- [ ] Phone connected to Jetson (WiFi/tether)
- [ ] Motors disconnected or isolated (bench testing)
- [ ] E-stop accessible (spacebar)
- [ ] Terminal window visible
- [ ] Max velocities appropriate (conservative defaults)
- [ ] Kill switch ready (Ctrl+C)

## Support

- Main documentation: `MOTOR_TEST_JOYSTICK.md`
- Issue tracker: https://gitea.vayrette.com/seb/saltylab-firmware/issues/513
- Termux wiki: https://wiki.termux.com/