saltylab-firmware/phone/INSTALL_MOTOR_TEST.md

# 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

Option A: Via USB (adb)
```bash
# On your computer
adb push phone/motor_test_joystick.py /data/data/com.termux/files/home/

# Or just place in ~/saltylab-firmware/phone/ if building locally
```

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

### 2. Make executable

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

### 3. Verify dependencies

**For ROS2 backend** (requires ros_core on Jetson):
```bash
# Check if ROS2 is available
python3 -c "import rclpy; print('✓ ROS2 available')" 2>/dev/null || echo "✗ ROS2 not available (use --backend websocket)"
```

**For WebSocket backend** (fallback, no dependencies):
```bash
python3 -c "import json, socket; print('✓ WebSocket dependencies available')"
```

## Quick Test

### 1. Start on phone (Termux)

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

**Option B: 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

Monitor `/cmd_vel` topic:
```bash
# On Jetson
ros2 topic echo /cmd_vel
```

You should see Twist messages (linear.x, angular.z) when moving the joystick.

### 3. Safety test

1. Move joystick forward (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
6. Verify "Velocities sent to zero" message

## Setup Automation

### Auto-launch from Termux:Boot

1. Install Termux:Boot from F-Droid
2. Create startup script:
   ```bash
   mkdir -p ~/.termux/boot
   cat > ~/.termux/boot/start_motor_test.sh << 'EOF'
   #!/bin/bash
   # Start motor test joystick in background
   cd ~/saltylab-firmware/phone
   python3 motor_test_joystick.py --backend websocket --host 192.168.1.100 &
   EOF
   chmod +x ~/.termux/boot/start_motor_test.sh
   ```

3. Next boot: app will start automatically

### Manual session management

```bash
# Start in background
nohup python3 ~/saltylab-firmware/phone/motor_test_joystick.py > ~/motor_test.log 2>&1 &
echo $! > ~/motor_test.pid

# Stop later
kill $(cat ~/motor_test.pid)

# View logs
tail -f ~/motor_test.log
```

## Configuration

### Adjust velocity limits

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

Moderate:
```bash
python3 motor_test_joystick.py --linear-max 0.3 --angular-max 0.8
```

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

### Change Jetson address

For static IP:
```bash
python3 motor_test_joystick.py --backend websocket --host 192.168.1.100
```

For hostname (requires mDNS):
```bash
python3 motor_test_joystick.py --backend websocket --host saltybot.local
```

For different port:
```bash
python3 motor_test_joystick.py --backend websocket --host 192.168.1.100 --port 8080
```

## Troubleshooting

### "ModuleNotFoundError: No module named 'curses'"

Curses should be built-in with Python. If missing:
```bash
# Unlikely needed, but just in case:
python3 -m pip install windows-curses  # Windows only
# On Android/Termux, it's included
```

### "ROS2 module not found" (expected if no ros_core)

Solution: Use WebSocket backend
```bash
python3 motor_test_joystick.py --backend websocket --host <jetson-ip>
```

### Terminal display issues

- Make terminal larger (pinch-zoom)
- Reset terminal: `reset`
- Clear artifacts: `clear`
- Try external keyboard (more reliable than touch)

### No motor response

1. **Check Jetson ros_core is running:**
   ```bash
   # On Jetson
   ps aux | grep -E "ros|dcps" | grep -v grep
   ```

2. **Check motor bridge is subscribed to /cmd_vel:**
   ```bash
   # On Jetson
   ros2 topic echo /cmd_vel  # Should see messages from phone
   ```

3. **Verify phone can reach Jetson:**
   ```bash
   # In Termux
   ping <jetson-ip>
   nc -zv <jetson-ip> 9090  # For WebSocket mode
   ```

4. **Check phone ROS_DOMAIN_ID matches Jetson** (if using ROS2):
   ```bash
   # Should match: export ROS_DOMAIN_ID=0 (default)
   ```

## Uninstall

```bash
# Remove script
rm ~/saltylab-firmware/phone/motor_test_joystick.py

# Remove auto-launch
rm ~/.termux/boot/start_motor_test.sh

# Stop running process (if active)
pkill -f motor_test_joystick
```

## Support

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