saltylab-firmware/jetson/ros2_ws/src/saltybot_obstacle_memory

SaltyBot Obstacle Memory Map (Issue #453)

Persistent spatial memory system for tracking obstacles and hazards detected by LIDAR. Maintains a 2D occupancy grid that accumulates detections over time with temporal decay.

Features

1. Occupancy Grid Map

• Resolution: 10cm per cell (configurable)
• Grid Size: 100×100 cells by default (~10×10 meters centered on robot)
• Cell States:
  • Unknown: Never observed (-1 in OccupancyGrid)
  • Free: Definitely free space (0% occupancy)
  • Obstacle: Detected obstacle (0–100% based on confidence)
  • Hazard: Persistent hazard with 3+ detections (high confidence)

2. Hazard Classification

• Detection-based: 3+ observations of same location = hazard
• Permanent: Hazards persist even with temporal decay
• Confidence Tracking: 0.0–1.0 based on detection history
• Quality Metric: Increases confidence with repeated detections

3. Temporal Decay

• Hazard Decay: 95% per day (30-day half-life)
  • Decays slowly due to persistence
  • Never drops below 30% confidence
• Obstacle Decay: 85% per day (~21-day half-life)
  • Faster decay than hazards
  • Reverts to free space when confidence < 20%
• Decay Interval: Applied every hour

4. LIDAR Integration

• Input: LaserScan on /scan (or /saltybot/scan)
• Odometry: Robot position from /odom
• Ray Casting: Marks hit points as obstacles, intermediate points as free
• Range Filtering: Configurable min/max range (default 0.1–10.0m)

5. ROS2 Navigation Integration

• Output: /saltybot/obstacle_map (nav_msgs/OccupancyGrid)
• Format: Standard OccupancyGrid for Nav2 costmap
• Frequency: Published at 5 Hz
• Frame: Map frame compatible with move_base

6. Persistence

• Storage: YAML file at /home/seb/saltybot-data/obstacle_map.yaml
• Format: Grid metadata + cell states with timestamps
• Auto-Save: Every 5 minutes (configurable)
• Load on Startup: Restores previous session's map

Configuration

Edit config/obstacle_memory.yaml:

grid_width: 100
grid_height: 100
grid_resolution: 0.1
map_file: "/home/seb/saltybot-data/obstacle_map.yaml"
auto_save_interval: 300.0
scan_max_range: 10.0
scan_min_range: 0.1
publish_rate_hz: 5.0
decay_interval_seconds: 3600.0

Running

Launch the obstacle memory node

ros2 launch saltybot_obstacle_memory obstacle_memory.launch.py

Direct execution

ros2 run saltybot_obstacle_memory obstacle_memory

Integration Points

1. Navigation Stack (Nav2)

   • Consumes /saltybot/obstacle_map in costmap_2d_ros
   • Influences pathfinding and local costmap

2. LIDAR Driver (e.g., saltybot_sensors)

   • Publishes /scan or /saltybot/scan
   • Ray angles, distances, and timestamp

3. Odometry Provider (e.g., wheel encoders + IMU)

   • Publishes /odom
   • Robot pose (x, y, theta)

4. Dashboard/WebUI

   • Subscribes to /saltybot/obstacle_map
   • Displays as overlay on navigation view
   • Hazard visualization

Performance

• Memory: ~100KB per 100×100 grid
• Computation: O(n) per LIDAR scan (n = number of rays)
• Persistence: O(width×height) per save (~1ms for 100×100)
• Decay: O(width×height) per hour (~5ms for 100×100)