# SaltyBot Patrol Mode (Issue #446)

Autonomous waypoint circuit with idle behaviors, person detection, and social integration.

## Features

- **Autonomous Navigation**: Uses Nav2 `/navigate_to_pose` to visit waypoints in order
- **Idle Behaviors**: Pan-tilt sweeps and random greetings at each waypoint (10-30s)
- **Person Detection Pause**: Detects people → pauses patrol → enters social mode → resumes when they leave
- **Battery Management**: Automatically returns to dock at <25% battery
- **Teleop Override**: Can be interrupted by teleop joystick control
- **Voice Commands**: Start/stop patrol via voice ("patrol start", "patrol stop")
- **Randomized Patrol**: Waypoints visited in random order each patrol cycle
- **State Publishing**: Publishes `/saltybot/patrol_state` for monitoring

## Architecture

```
Patrol State Machine:
  IDLE → NAVIGATE → IDLE_BEHAVIOR → (next waypoint)
                ↓
         [Person Detected]
                ↓
         PAUSE_PERSON → SOCIAL_MODE → back to NAVIGATE

  Battery < 25% → RETURN_TO_DOCK
  Voice/Teleop → IDLE
```

## Usage

### Start Patrol

```bash
ros2 launch saltybot_patrol patrol.launch.py
```

Or via voice:
```
"Hey SaltyBot, start patrol"
```

### Stop Patrol

```bash
ros2 service call /patrol_control ... stop
```

Or via voice:
```
"Hey SaltyBot, stop patrol"
```

## Configuration

Edit `config/patrol_params.yaml`:

```yaml
patrol_waypoints:
  - name: "waypoint_1"
    x: 5.0
    y: 0.0
    yaw: 0.0  # radians
  - name: "waypoint_2"
    x: 3.0
    y: 5.0
    yaw: 1.57
```

Parameters:
- `min_idle_time`: Minimum pause at each waypoint (default: 10s)
- `max_idle_time`: Maximum pause at each waypoint (default: 30s)
- `battery_dock_threshold`: Battery level to trigger dock return (default: 25%)
- `person_pause_timeout`: How long to wait for person to leave (default: 30s)

## Topics

| Topic | Type | Description |
|-------|------|-------------|
| `/saltybot/patrol_state` | String | Current patrol state + battery + waypoint |
| `/saltybot/speech_text` | String | Greetings spoken at waypoints |
| `/saltybot/pan_tilt_cmd` | String | Pan-tilt sweep commands |
| `/saltybot/person_detections` | Detection2DArray | Person detection input |
| `/saltybot/teleop_cmd` | String | Teleop override signals |
| `/saltybot/voice_cmd` | String | Voice command input |

## Monitoring

Check patrol state:
```bash
ros2 topic echo /saltybot/patrol_state
```

Expected output:
```
state:NAVIGATE,battery:85.5%,waypoint:2/5
state:IDLE_BEHAVIOR,battery:85.3%,waypoint:2/5
state:NAVIGATE,battery:84.8%,waypoint:3/5
```

## Behaviors at Each Waypoint

1. **Arrival**: Stop at waypoint
2. **Pan-Tilt Sweep**: Look around the environment
3. **Greeting**: Speak random greeting
4. **Pause**: Wait 10-30 seconds
5. **Move to Next**: Navigate to next waypoint

## Person Detection Integration

When a person is detected:
1. Patrol pauses
2. Robot faces the person (pan-tilt)
3. Enters social mode (greetings, conversation)
4. Waits for person to leave
5. Resumes patrol at current waypoint

## Battery Management

- Continuous monitoring of battery level
- When battery < 25%: Immediately return to dock (0, 0)
- Pause patrol during charging
- Resume when battery > 80%

## Teleop Override

- User can take control at any time
- Teleop takes priority over patrol
- Patrol pauses and enters idle
- Automatically resumes when control is released (if not manually stopped)

## Limitations & Future

- Waypoint collision detection not implemented (uses Nav2 safety)
- No docking automation (manual charging)
- Pan-tilt and speech topics assumed to exist
- Person tracking limited to detection (no following)

## Issue #446 Completion

✅ Autonomous waypoint circuit
✅ Idle behaviors (pan-tilt, greetings)
✅ Person detection pauses
✅ Battery monitoring & dock return
✅ Teleop override
✅ Voice commands
✅ Randomized waypoint order
✅ State publishing
