CLAR — Capstone LiDAR Autonomous Robot

CLAR는 Jetson Orin Nano 로컬 Ubuntu + ROS2 Humble 기반의 건설 현장 자동화 먹매김 로봇 프로젝트다. MD200T 듀얼 BLDC, SLAMTEC A2M12 LiDAR, ESP32 micro-ROS 마킹 장치, 외부 노트북 AprilTag 브리지, FastAPI WebUI를 하나의 워크스페이스에서 통합 운용한다.

운용 시퀀스 / 라벨 / 합격 기준 / 충돌 매트릭스의 정본은 PROJECT_STATE.md, clar_install.md, plan_validation.md에 있다. 하드웨어 검증 미완료 항목은 [검증 대기]로 분류된다 (CLAUDE.md §4.3).

캡스톤 범위 (2026-05-14 결정): Phase 1 (layout_executor_fallback 모드, 외부 카메라 1대 + AprilTag 측위) + Phase 2 (nav2_default 모드, LiDAR + AMCL, 가벽 인테리어 환경) 까지 진행한다. 시연 환경은 MDF 가벽이 세워진 인테리어 먹매김 현장이다. Phase 3 (벽 없는 건설 현장, 외부 카메라 N대 fan-in) 은 캡스톤 범위 밖의 future work 로 분리된다. 상세 결정 근거는 docs/algorithm/robot_path_algorithm_report.md §7 참조.

---

빠른 진입점

처음 보는 사람은 docs/ALGORITHM_OVERVIEW.md 1페이지부터 (1분 안에 CLAR 가 뭘 하는지 + 8 단계 데이터 흐름 + 10 컴포넌트 책임).

목적	문서
1분 진입 (알고리즘 큰 그림)	docs/ALGORITHM_OVERVIEW.md
ROS 토픽 추적 (전체 인벤토리)	docs/ROS_TOPICS.md
처음 환경 설치	docs/INSTALLATION.md → docs/SETTING.md → clar_install.md
일상 운용 (DXF 업로드 → 시작/정지)	docs/USER_GUIDE.md
깊은 알고리즘 (L4 actuator, dual-loop)	docs/ARCHITECTURE.md → docs/onboarding/02_algorithm_report.md
검증 / 합격 기준	docs/TEST_GUIDE.md → plan_validation.md
하드웨어 / 펌웨어 / udev	docs/HARDWARE.md
컴포넌트 상태 (검증 완료 / 검증 대기 / 미구현)	PROJECT_STATE.md
신규 인수인계 onboarding	docs/onboarding/ (01 → 02 → 03 → 04)
전체 문서 지도	docs/DOC_INDEX.md

---

핵심 컴포넌트 (1줄 요약)

컴포넌트	역할
md_controller	/cmd_vel → 좌/우 RPM RS-485 변환, /odom 발행
sllidar_ros2	A2M12 /scan 발행
robot_localization	wheel odom + 외부 pose EKF 융합 (ekf*.yaml)
clar_layout / blueprint_parser	DXF MARK/WALL 분리, /layout_waypoints, /clar/safe_region, /clar/wall_markers
clar_layout / layout_executor	4중 가드 + waypoint 추종 (20 Hz)
clar_layout / web_server (Phase C)	FastAPI + WebSocket + Basic Auth
clar_layout / clar_orchestrator (Phase C)	/clar/job_command 구독 → subprocess 라이프사이클, /clar/job_status 2 Hz
clar_apriltag_test / apriltag_to_external_pose (외부 노트북)	/external_pose (frame=map, 5 Hz)
md_teleop, esp32_firmware	키보드 제어 / GPIO 제어
clar_runtime	4 mode runtime supervisor (nav2_default 등) [검증 대기]

---

빠른 실행 (요약 — 정본은 clar_install.md §3)

Canonical 시퀀스: T2 → T3 → T4 → N1 → T6.

# 단일 통합 실행 (Phase A/B/C + Nav2)
ros2 launch clar_runtime clar_full_system.launch.py mode:=nav2_default

# 또는 노트북(N1) 측 AprilTag 브리지
ros2 launch clar_apriltag_test final_tag_tracking.launch.py
ros2 run clar_apriltag_test apriltag_to_external_pose

# WebUI: http://<jetson-ip>:8080/  (Basic Auth)

T1(md_controller.launch.py)은 정상 운용 시퀀스에서 직접 기동하지 않는다 (CLAUDE.md §4.1). 충돌 매트릭스 / 단독 디버깅 모드는 clar_install.md §9, docs/tests/Layout_test.md 참조.

시뮬 (선택)

시뮬 (선택, Jetson + Gazebo Classic 11 필요): ros2 launch clar_simulation clar_sim_layout.launch.py world:=empty_room. 실차 launch 와 동시 실행 절대 금지 (clar_install.md §9.2 row 14, clar_install.md §S 참조).

---

환경 요약 (정본은 docs/SETTING.md)

항목	값
보드	Jetson Orin Nano
ROS	ROS2 Humble
워크스페이스	~/clar/md_controller_ws
ROS_DOMAIN_ID	67 (ESP32 펌웨어와 일치 필수)
ROS_LOCALHOST_ONLY	1 기본, 외부 카메라 PC 연동 시에만 0
RMW	rmw_fastrtps_cpp

---

라이선스 / 기여

본 저장소는 Capstone 프로젝트 산출물이다. 운영 정책은 CLAUDE.md, 문서 정책은 docs/DOC_POLICY.md를 따른다.