---
name: harunkurtdev/nav2-server-nodes
source: https://app.decimal.ai/s/harunkurtdev-nav2-server-nodes@1/SKILL.md
source_sha256: 9aa3e342dcb9
---

# Nav2 Server Nodes

Source: `~/nav2_ws/src/navigation2/`

## Lifecycle Manager

**Package:** `nav2_lifecycle_manager`
**Purpose:** Orchestrate lifecycle transitions of all Nav2 nodes

### Architecture
Manages state machine: `UNCONFIGURED → INACTIVE → ACTIVE → FINALIZED`
Uses bond connections for health monitoring. Auto-reconnects on failure.

### Key Parameters
```yaml
lifecycle_manager:
  ros__parameters:
    autostart: true
    bond_timeout: 4.0
    bond_heartbeat_period: 0.5
    service_timeout: 5.0
    attempt_respawn_reconnection: true
    node_names:
      - "map_server"
      - "amcl"
      - "controller_server"
      - "planner_server"
      - "smoother_server"
      - "behavior_server"
      - "bt_navigator"
      - "waypoint_follower"
      - "velocity_smoother"
      - "collision_monitor"
```

### Service
- `manage_nodes` (nav2_msgs/ManageLifecycleNodes)
  - Commands: STARTUP(0), PAUSE(1), RESUME(2), RESET(3), SHUTDOWN(4), CONFIGURE(5), CLEANUP(6)

---

## Velocity Smoother

**Package:** `nav2_velocity_smoother`
**Purpose:** Apply acceleration/deceleration limits to velocity commands

### Architecture
- Subscribes to raw `cmd_vel` (from controller)
- Publishes smoothed `cmd_vel_smoothed`
- Enforces kinematic limits on linear and angular velocities

### Key Parameters
```yaml
velocity_smoother:
  ros__parameters:
    smoothing_frequency: 20.0
    scale_velocities: false
    feedback: "OPEN_LOOP"           # or "CLOSED_LOOP" (uses odom)
    max_velocity: [0.26, 0.0, 1.0]   # [vx, vy, wz]
    min_velocity: [-0.26, 0.0, -1.0]
    max_accel: [2.5, 0.0, 3.2]
    max_decel: [-2.5, 0.0, -3.2]
    deadband_velocity: [0.0, 0.0, 0.0]
    velocity_timeout: 1.0
    odom_topic: "odom"
    odom_duration: 0.1
```

---

## Collision Monitor

**Package:** `nav2_collision_monitor`
**Purpose:** Real-time collision avoidance between controller and hardware

### Architecture
Intercepts `cmd_vel` → applies safety actions → outputs safe `cmd_vel`.
Monitors configurable polygons/circles around robot.

**Action Types:**
| Type | Behavior |
|------|----------|
| `stop` | Zero velocity on detection |
| `slowdown` | Reduce velocity by factor |
| `limit` | Cap max velocity |
| `approach` | Slow proportionally to distance |

**Polygon Sources:**
- `Polygon` - Static polygon shape
- `Circle` - Circular zone
- `VelocityPolygon` - Dynamic polygon based on current velocity

**Data Sources:**
- `Scan` - LaserScan
- `PointCloud` - PointCloud2
- `Range` - Single range sensor
- `Costmap` - Costmap data

### Key Parameters
```yaml
collision_monitor:
  ros__parameters:
    cmd_vel_in_topic: "cmd_vel_smoothed"
    cmd_vel_out_topic: "cmd_vel"
    transform_tolerance: 0.5
    source_timeout: 5.0
    stop_pub_timeout: 2.0
    polygons: ["FootprintApproach"]
    FootprintApproach:
      type: "polygon"
      action_type: "approach"
      footprint_topic: "/local_costmap/published_footprint"
      time_before_collision: 2.0
      simulation_time_step: 0.02
      max_points: 5
      enabled: true
    observation_sources: ["scan"]
    scan:
      type: "scan"
      topic: "/scan"
```

### Collision Detector
Separate node (`CollisionDetector`) that only detects, doesn't modify commands. Publishes `CollisionDetectorState`.

---

## Smoother Server

**Package:** `nav2_smoother`
**Action:** `SmoothPath`
**Purpose:** Host path smoother plugins

### Smoother Plugins
| Plugin | Package | Algorithm |
|--------|---------|-----------|
| `SimpleSmoother` | `nav2_smoother` | Basic iterative smoothing |
| `SavitzkyGolaySmoother` | `nav2_smoother` | Savitzky-Golay filter |
| `ConstrainedSmoother` | `nav2_constrained_smoother` | Convex optimization with constraints |

```yaml
smoother_server:
  ros__parameters:
    smoother_plugins: ["simple_smoother"]
    simple_smoother:
      plugin: "nav2_smoother::SimpleSmoother"
      tolerance: 1.0e-10
      max_its: 1000
      do_refinement: true
```

### Constrained Smoother
```yaml
    constrained_smoother:
      plugin: "nav2_constrained_smoother::ConstrainedSmoother"
      tolerance: 1.0e-10
      max_its: 1000
      enforce_path_inversion: true  # For lattice planner
      do_refinement: true
      w_smooth: 0.3
      w_data: 0.2
```

---

## Waypoint Follower

**Package:** `nav2_waypoint_follower`
**Actions:** `FollowWaypoints`, `FollowGPSWaypoints`
**Purpose:** Sequential navigation through ordered waypoints

### Architecture
Uses `NavigateToPose` action internally for each waypoint. Supports plugin-based task execution at each waypoint.

### Key Parameters
```yaml
waypoint_follower:
  ros__parameters:
    loop_rate: 20
    stop_on_failure: true
    waypoint_task_executor_plugin: "wait_at_waypoint"
    wait_at_waypoint:
      plugin: "nav2_waypoint_follower::WaitAtWaypoint"
      enabled: true
      waypoint_pause_duration: 200  # ms
```

---

## Docking Server

**Package:** `nav2_docking`
**Actions:** `DockRobot`, `UndockRobot`
**Purpose:** Autonomous charging dock approach/departure

### Architecture
- Navigates to staging pose → detects dock → controlled approach → verify charging
- Plugin-based dock types (SimpleChargingDock, SimpleNonChargingDock)
- Internal controller for precise dock approach
- Pose filtering for dock detection smoothing

### Key Parameters
```yaml
docking_server:
  ros__parameters:
    dock_plugins: ["simple_charging_dock"]
    simple_charging_dock:
      plugin: "opennav_docking::SimpleChargingDock"
      docking_threshold: 0.05
      staging_x_offset: -0.7
      use_external_detection_pose: true
    docks: ["home_dock"]
    home_dock:
      type: "simple_charging_dock"
      frame: "map"
      dock_pose: [0.0, 0.0, 0.0]
    controller:
      use_collision_detection: true
      k_phi: 3.0
      k_delta: 2.0
      v_linear_min: 0.15
      v_linear_max: 0.25
    filter_coef: 0.1
    detection_timeout: 10.0
    max_retries: 3
```

---

## Following Server

**Package:** `nav2_following`
**Action:** `FollowObject`
**Purpose:** Track and follow dynamic targets

### Architecture
Similar to docking but for moving targets. Subscribes to target pose topic, applies filtering, controls approach.

```yaml
following_server:
  ros__parameters:
    fixed_frame: "odom"
    base_frame: "base_link"
    filter_coef: 0.1
    detection_timeout: 5.0
    odom_topic: "/odom"
    controller:
      use_collision_detection: false
      k_phi: 3.0
      k_delta: 2.0
```

---

## Simple Commander (Python API)

**Package:** `nav2_simple_commander`
**Class:** `BasicNavigator`
**Purpose:** High-level Python API for Nav2

### Key Methods
```python
from nav2_simple_commander.robot_navigator import BasicNavigator

navigator = BasicNavigator()

# Initialization
navigator.setInitialPose(initial_pose)
navigator.waitUntilNav2Active()

# Navigation
navigator.goToPose(goal_pose)
navigator.goThroughPoses(poses)
navigator.followWaypoints(waypoints)
navigator.followPath(path)

# Recovery
navigator.spin(spin_dist=1.57)
navigator.backup(backup_dist=0.15, backup_speed=0.025)

# Docking
navigator.dockRobot(dock_id="home_dock")
navigator.undockRobot(dock_type="simple_charging_dock")

# Planning only
path = navigator.getPath(start, goal, planner_id="GridBased")
smoothed = navigator.smoothPath(path, smoother_id="simple_smoother")

# Status
navigator.isTaskComplete()      # Returns True when done
result = navigator.getResult()  # TaskResult enum
feedback = navigator.getFeedback()

# Costmap
navigator.clearAllCostmaps()
navigator.clearLocalCostmap()
navigator.clearGlobalCostmap()

# Lifecycle
navigator.lifecycleStartup()
navigator.lifecycleShutdown()
```

### TaskResult Enum
```python
class TaskResult(Enum):
    UNKNOWN = 0
    SUCCEEDED = 1
    CANCELED = 2
    FAILED = 3
```

---

## Loopback Simulator

**Package:** `nav2_loopback_sim`
**Purpose:** Lightweight sim without physics (for testing Nav2)

Accepts `cmd_vel`, publishes:
- Odometry on `/odom`
- TF: `odom` → `base_link`
- LaserScan from occupancy grid (optional)

```yaml
loopback_simulator:
  ros__parameters:
    update_duration: 0.02
    base_frame_id: "base_link"
    odom_frame_id: "odom"
    map_frame_id: "map"
    scan_frame_id: "base_scan"
    publish_map_odom_tf: true
    publish_clock: true
```

---

## Data Flow Summary

```
cmd_vel flow:
  Controller Server → Velocity Smoother → Collision Monitor → Hardware

Localization flow:
  /scan + /map → AMCL → map→odom TF

Planning flow:
  Goal → BT Navigator → Planner Server → Smoother Server → Controller Server

Costmap flow:
  /scan + /map → Costmap Layers → Combined Costmap → Planner/Controller
```