Autonomous quadruped robot built from a cheap toy dog. ESP32-S3 handles real-time motor control and sensor fusion; a companion computer (RPi5/Jetson) runs ROS2, SLAM, and OpenClaw gait generation.

<<<<<<< HEAD Transform a standard toy robot dog into an intelligent, autonomous quadruped by:

• Intercepting control signals from the existing board
• Adding ESP32-S3 + ROS2 for smart decision-making
• Integrating LiDAR for autonomous navigation
• Connecting to OpenClaw for high-level AI tasks =======

Avoid strapping pins: GPIO 0, 3, 46, 26-32 (reserved for Octal PSRAM).

Full pinout: docs/hardware/pinout.md
Hardware overview: docs/hardware/overview.md

b0c9f4c (Save local changes to README)

AI / UI (Telegram, WhatsApp, CLI)
         |
    RosClaw (agent bridge)
         |
    OpenClaw (gaits) + Nav2 (planning) + SLAM Toolbox (mapping)
         |
    ros2_control (hardware interface)
         | UDP 50Hz
    +---------------------------+
    |   ESP32-S3 Firmware       |
    |  PID 200Hz | ADC | UART   |
    |  PWM → SA8301 → Motors    |
    +---------------------------+

• Framework: Arduino (PlatformIO) or ESP-IDF
• Core 0: WiFi + UDP communication (50Hz)
• Core 1: Real-time control (PID @ 200Hz, ADC, PWM)
• UDP Protocol:
  • TX → PC: [joint0, joint1, joint2, joint3, roll, pitch, yaw] (7 floats)
  • RX ← PC: [target0, target1, target2, target3] (4 floats)
• Watchdog: No heartbeat >100ms → emergency stop (PWM=0, sit pose)

• Distribution: ROS2 Humble (Ubuntu 22.04) or Jazzy (Ubuntu 24.04)
• ros2_control: Custom hardware interface over UDP
• OpenClaw: Quadruped gait generation (trot, walk, stand)
• Nav2: Global/local planning, obstacle avoidance
• SLAM Toolbox: 2D occupancy grid mapping
• WitMotion driver: Publishes sensor_msgs/LaserScan

Full plan with 25 tasks, dependencies, and checkpoints: docs/PLAN.md

• PlatformIO (firmware)
• ROS2 Humble or Jazzy (companion PC)
• colcon (ROS2 build)
• WiFi network shared between ESP32 and companion PC

cd firmware
pio run
pio run --target upload

cd ros2_ws
colcon build --packages-select clawdog_*
source install/setup.bash

# Terminal 1: Start robot hardware + teleop
ros2 launch clawdog_bringup robot.launch.py

# Terminal 2: Gamepad teleop (optional)
ros2 launch clawdog_bringup teleop.launch.py

# Terminal 3: SLAM
ros2 launch clawdog_bringup slam.launch.py

# Terminal 4: Navigation
ros2 launch clawdog_bringup navigation.launch.py

Always test with robot suspended (no ground contact) until PID and gait are verified.

Full safety docs: CLAUDE.md

ClawDog/
├── firmware/              # ESP32-S3 firmware (PlatformIO)
│   ├── src/
│   ├── include/
│   ├── lib/
│   ├── test/
│   └── platformio.ini
├── ros2_ws/               # ROS2 workspace
│   └── src/
│       ├── clawdog_control/     # Hardware interface, gaits, teleop
│       ├── clawdog_description/ # URDF, meshes
│       ├── clawdog_bringup/     # Launch files, configs
│       └── witmotion_driver/    # LiDAR driver
├── openclaw/              # OpenClaw integration
├── docs/                  # Documentation
│   ├── decisions/         # ADRs
│   └── hardware/          # Pinout, overview
├── scripts/               # Utility scripts
├── tests/                 # Integration tests
├── DESC.md
├── README.md
└── LICENSE

Apache License 2.0

This project is in early development. No code yet — documentation and planning phase. See docs/PLAN.md for the implementation roadmap.