seb/saltylab-firmware
1
0
Fork 0
Code Issues Pull Requests 5 Actions Packages Projects Releases Wiki Activity
saltylab-firmware/jetson/ros2_ws/src/saltybot_obstacle_memory/README.md
sl-webui fb93acee0a feat: Add Issue #453 - Obstacle memory map with persistent hazard zones 
- 2D occupancy grid (100x100 cells @ 10cm resolution, configurable)
- LIDAR integration: subscribes to /scan and /odom for real-time obstacle detection
- Ray-casting: marks hit points as obstacles, intermediate points as free space
- Cell states: unknown/free/obstacle/hazard with confidence tracking (0.0–1.0)
- Hazard classification: 3+ detections = permanent hazard (stays in memory)
- Temporal decay: 95%/day for hazards (30-day half-life), 85%/day for obstacles (~21-day)
- Decay interval: applied hourly, cells revert to free when confidence < 20%
- Persistence: auto-saves to /home/seb/saltybot-data/obstacle_map.yaml every 5 minutes
- YAML format: grid metadata + cell array with state/confidence/detection_count/timestamp
- OccupancyGrid publisher: /saltybot/obstacle_map for Nav2 integration at 5 Hz
- Thread-safe: all grid operations protected with locks for concurrent callbacks
- Statistics: hazard/obstacle/free cell counts and coverage percentage
- Dashboard overlay ready: color-coded cells (red=hazard, orange=obstacle, gray=free)
- Configurable via obstacle_memory.yaml: grid size/resolution, range limits, decay rates

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-03-05 09:21:30 -05:00

3.2 KiB
Raw Blame History

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)