feat: Deep Robotics M20 autonomous navigation support

[aphexcx]

Summary

Adds full Deep Robotics M20 quadruped support to dimos, including autonomous navigation via ARISE SLAM running in a Docker container on the robot's NOS board.

What's included

• M20 Connection Module: RTSP camera, UDP velocity control, dead-reckoning + ROS2 odometry, drdds /NAV_CMD for navigation mode
• ARISE SLAM Integration: Docker-based deployment with drdds SHM bridge (lidar + IMU), patched Velodyne processing pipeline (Findings no.8, no.11 in ARISE log), lifecycle timer fixes for ARM64 (Finding no.7)
• SmartNav Blueprint: Container runs C++ nav stack (ARISE SLAM + TerrainAnalysis + LocalPlanner + PathFollower), host runs Python modules (PGO, CmdVelMux, ClickToGoal, RerunBridge)
• Rerun Visualization: 3D point cloud + 2D camera panel with color_image streaming, smart_nav visual overrides for terrain/costmap/trajectory
• Deploy Tooling: deploy.sh for remote M20 management (push/pull Docker images, bridge start/stop, service conflict resolution, NAT setup) with Tailscale support
• Native /NAV_CMD Publisher: pybind11 module using host drdds (bypasses rclpy glibc incompatibility on Ubuntu 20.04 NOS)
• drdds SHM Bridge: drdds_recv (host) + ros2_pub (container) for lidar point cloud + IMU data
• M20 Official Dev Guide: Included as reference documentation

Architecture

M20 Hardware Topology

The M20 has three compute boards connected via internal Ethernet (10.21.31.0/24). dimos runs on NOS.

graph TB
    subgraph M20["Deep Robotics M20"]
        subgraph AOS["AOS — Main Controller<br/>10.21.31.103"]
            A1[Motor control]
            A2[lio_perception]
            A3["rsdriver (lidar)"]
            A4["yesense (IMU)"]
            A5[RTSP camera]
            A6["WiFi AP (10.21.41.1)"]
        end
        subgraph GOS["GOS — Comms<br/>10.21.31.104"]
            G1[5G modem]
            G2[Tailscale VPN]
            G3[NAT gateway]
        end
        subgraph NOS["NOS — Compute<br/>10.21.31.106"]
            N1[Docker host]
            N2[dimos runtime]
            N3[drdds_recv]
            N4["Python 3.12 · 16GB RAM · 62GB eMMC"]
        end
        subgraph Sensors["Sensors"]
            S1["2x RoboSense RSAIRY 192-ch lidar<br/>front: 224.10.10.201 · back: 224.10.10.202"]
            S2["Yesense IMU (/IMU_YESENSE)"]
            S3["RTSP Camera (rtsp://AOS:8554/video1)"]
        end
        AOS --- ETH["Internal Ethernet<br/>10.21.31.0/24"]
        GOS --- ETH
        NOS --- ETH
    end

Loading

Software Stack (NOS)

C++ navigation modules run inside a Docker container (ROS2 Humble, Ubuntu 22.04), while Python modules run on the NOS host (Ubuntu 20.04, Python 3.12). This split is necessary because:

• ARISE SLAM, TerrainAnalysis, LocalPlanner, PathFollower are C++ requiring ROS2 Humble (glibc 2.32+)
• NOS runs Ubuntu 20.04 (glibc 2.31) -- can't run Humble natively
• dimos Python modules (PGO, CmdVelMux, ClickToGoal) don't need ROS2
• The container talks to dimos via RPC (DockerModuleProxy)

graph TB
    subgraph NOS["NOS (10.21.31.106)"]
        subgraph Host["Host — Ubuntu 20.04, Python 3.12 via uv"]
            subgraph Coordinator["dimos ModuleCoordinator (m20_smartnav)"]
                MC["M20Connection<br/>· RTSP camera<br/>· /NAV_CMD (drdds)"]
                PGO["PGO<br/>· loop closure<br/>· iSAM2"]
                CMX["CmdVelMux<br/>· teleop + nav<br/>· velocity mux"]
                CTG["ClickToGoal<br/>· click-to-nav"]
                RR["RerunBridgeModule<br/>gRPC :9877"]
                WS["WebsocketVisModule<br/>Command Center :7779"]
            end
        end
        subgraph Docker["Docker Container 'dimos-nav' — ROS2 Humble, Ubuntu 22.04"]
            R2P["ros2_pub<br/>(SHM → ROS2 bridge)"]
            ARISE["ARISE SLAM<br/>· feature_extraction<br/>· laser_mapping<br/>· imu_preintegration"]
            TA["Terrain<br/>Analysis"]
            LP["Local Planner +<br/>Path Follower"]
            R2P --> ARISE --> TA --> LP
        end
        subgraph Bridge["drdds_recv — host process, root"]
            DR["Subscribes /LIDAR/POINTS + /IMU via drdds<br/>Writes POSIX SHM to /dev/shm"]
        end
        Host -- "RPC (DockerModuleProxy)" --> Docker
        DR -- "/dev/shm (--ipc host)" --> R2P
    end

Loading

Sensor Data Flow

End-to-end path from hardware sensors through ARISE SLAM to motor commands:

flowchart TB
    subgraph AOS["AOS"]
        RS["rsdriver<br/>/LIDAR/POINTS"]
        YS["yesense<br/>/IMU_YESENSE"]
    end

    subgraph NOS_Host["NOS Host"]
        RECV["drdds_recv<br/>(POSIX SHM)"]
    end

    subgraph Container["Docker Container"]
        PUB["ros2_pub"]
        FE["feature_extraction"]
        LM["laser_mapping"]
        IP["imu_preintegration"]
        TA2["TerrainAnalysis"]
        LP2["LocalPlanner"]
        PF["PathFollower"]
        RNAV["ROSNav Module<br/>(ROS2 → LCM bridge)"]
    end

    subgraph NOS_Modules["NOS Host Modules"]
        PGO2["PGO<br/>loop closure + global map"]
        CMX2["CmdVelMux<br/>teleop + nav merge"]
        M20C["M20Connection"]
        NCP["nav_cmd_pub<br/>(pybind11)"]
    end

    RS -- "drdds SHM" --> RECV
    YS -- "drdds SHM" --> RECV
    RECV -- "/dev/shm" --> PUB
    PUB -- "/bridge/LIDAR_POINTS" --> FE
    PUB -- "/bridge/IMU" --> IP
    FE --> LM
    IP --> LM
    LM -- "/state_estimation" --> RNAV
    LM -- "/registered_scan" --> RNAV
    LM --> TA2 --> LP2 --> PF
    PF -- "cmd_vel" --> RNAV
    RNAV -- "LCM /odometry" --> PGO2
    RNAV -- "LCM /registered_scan" --> PGO2
    RNAV -- "LCM /nav_cmd_vel" --> CMX2
    CMX2 -- "LCM /cmd_vel" --> M20C
    M20C --> NCP
    NCP -- "drdds /NAV_CMD" --> AOS_Motor["AOS<br/>Motor Controller"]

Loading

Startup Ordering (Critical)

drdds uses FastDDS Shared Memory transport for zero-copy IPC. The SHM discovery mechanism requires subscribers to start before publishers, otherwise the subscriber never discovers the publisher's SHM segments.

flowchart LR
    subgraph Order["Startup Sequence"]
        direction TB
        S1["1. drdds_recv starts<br/>Creates SHM segments"]
        S2["2. rsdriver restarts<br/>Discovers SHM, publishes lidar"]
        S3["3. yesense restarts<br/>Discovers SHM, publishes IMU"]
        S4["4. Docker container starts<br/>ros2_pub reads /dev/shm"]
        S5["5. ARISE SLAM activates<br/>Lifecycle: 5/10/15s timers"]
        S6["6. IMU init completes<br/>~200 samples for gravity cal"]
        S7["7. SLAM producing<br/>/state_estimation + /registered_scan"]
        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7
    end

Loading

If this ordering is violated (e.g., rsdriver starts before drdds_recv), the SHM bridge silently fails -- lidar data never reaches ARISE SLAM. The deploy.sh bridge-start command enforces this ordering.

Remote Access (Tailscale)

flowchart LR
    subgraph Mac["Developer Mac"]
        DV["dimos-viewer"]
        T1["localhost:9877"]
        T2["localhost:7779"]
        T3["localhost:3030"]
    end
    subgraph GOS_VPN["GOS (Tailscale)<br/>100.89.134.73"]
        TS["5G + VPN<br/>NAT gateway"]
    end
    subgraph NOS_Ports["NOS"]
        P1[":9877 Rerun gRPC"]
        P2[":7779 Command Center"]
        P3[":3030 RerunWebSocket"]
    end
    T1 -- "SSH tunnel" --> TS
    T2 -- "SSH tunnel" --> TS
    T3 -- "SSH tunnel" --> TS
    TS -- NAT --> P1
    TS -- NAT --> P2
    TS -- NAT --> P3
    DV -- "--connect" --> T1
    DV -- "--ws-url" --> T3

Loading

Included documentation

This PR includes extensive investigation logs and planning documents that serve as critical context for understanding the M20 platform and the architectural decisions made.

Investigation logs

Document	Description
INVESTIGATION_LOG.md	52 sections covering the initial M20 integration -- LiDAR data flow, mac_bridge TCP transport, drdds/DDS topic discovery, CycloneDDS vs FastDDS interop, NOS Docker setup, RTSP camera, dead-reckoning odometry, and getting dimos running on Mac receiving all M20 topics. The foundational investigation that preceded the ROSNav migration.
plans/m20-rosnav-migration/ROSNAV_MIGRATION_LOG.md	30 findings documenting the full migration from the M20's proprietary drdds nav stack to dimos ROSNav. Covers DDS discovery (Finding no.1), NOS resource constraints (Finding no.5), Docker networking (Finding no.9), FastDDS SHM cross-version compatibility (Finding no.16), lidar multicast topology (Finding no.22), drdds SHM bridge design (Finding no.25), and more. Essential reading for anyone working on M20 or similar embedded ARM64 robots with proprietary middleware.
plans/m20-rosnav-migration/ARISE_SLAM_LOG.md	17 findings on integrating ARISE SLAM's Velodyne mode with the M20's dual RoboSense RSAIRY 192-channel lidars. Key discoveries: ARISE's Velodyne processing pipeline was never functional upstream -- undistortionAndscanregistration() is commented out in all forks (Finding no.8). Documents the IMU-triggered processing fix from SuperOdom (Finding no.11), 192-to-64 channel ring remapping (Finding no.2), QoS mismatch (Finding no.3), float32 time truncation (Finding no.4), and lifecycle activation race conditions on ARM64 (Finding no.7).

Planning documents (plans/m20-rosnav-migration/)

Directory	Contents
00-discovery/	Initial DDS topic discovery and QoS analysis from live M20 hardware
01-scope/	Requirements gathering -- multi-LLM question generation (Opus, GPT, Gemini), question triage, and system context analysis
02-spec/	Technical specification with key decisions table, phased delivery plan, and spec review assessment
03-plan/	Implementation plan with task breakdown, dependency graph, and plan review
04-beads/	Issue tracking drafts (beads format) with review passes
05-drdds-bridge/	Detailed plan for the drdds SHM bridge (lidar + IMU data path)

Reference documentation

Document	Description
dimos/robot/deeprobotics/m20/docs/m20-official-software-development-guide.md	Official Deep Robotics M20 software development guide -- covers the 3-board architecture (AOS/GOS/NOS), drdds middleware, UDP protocol, DDS topics, network topology, and sensor specifications.

Hardware details

• M20 3-board architecture: AOS (10.21.31.103, main controller), GOS (10.21.31.104, 5G comms), NOS (10.21.31.106, Docker host + compute)
• Sensors: 2x RoboSense RSAIRY 192-channel lidars (merged via drdds), Yesense IMU, RTSP camera
• Verified on: M20-770 ("gogo") via Tailscale

Key files

Path	Purpose
dimos/robot/deeprobotics/m20/connection.py	Main M20 connection module
dimos/robot/deeprobotics/m20/blueprints/rosnav/m20_smartnav.py	SmartNav blueprint
dimos/robot/deeprobotics/m20/rosnav_docker.py	Docker container management
dimos/robot/deeprobotics/m20/velocity_controller_dds.py	Native drdds velocity control
dimos/robot/deeprobotics/m20/docker/deploy.sh	Deployment tooling
dimos/robot/deeprobotics/protocol.py	Deep Robotics UDP protocol
dimos/robot/deeprobotics/m20/docker/drdds_bridge/	SHM bridge source (drdds_recv + ros2_pub)

Test plan

• ARISE SLAM producing /state_estimation and /registered_scan on M20 hardware
• Costmap visible in command center (port 7779)
• Color image streaming in rerun viewer (~7fps)
• nav_cmd_pub publishing /NAV_CMD via native drdds
• CmdVelMux routing teleop + nav cmd_vel
• End-to-end WASD teleop via dimos-viewer
• Click-to-goal autonomous navigation
• Multi-floor mapping with PGO loop closure

🤖 Generated with Claude Code