import { ImgTag } from '@/components/MDXRenderer'; import DriveAssetGrid from '@/components/DriveAssetGrid'; {/* more */} [mumallaeng/Shoepernoma](https://github.com/mumallaeng/Shoepernoma) \ [addinedu-ros-8th/ros-repo-3](https://github.com/addinedu-ros-8th/ros-repo-3) > *(KDT) ROS2와 인공지능을 활용한 자율주행 로봇 개발자 양성과정 8기* 교육과정 내에서 진행된 파이널 과제입니다. 3팀 **Secondary Wave**는 본 프로젝트로 최종 발표회에서 최우수상(1위)을 수상하였습니다. ## 담당 작업 - 팀장으로 MainService 구조를 잡고 ROS2 Action·Topic·Service 기반 작업 처리 흐름을 정리했습니다. - 피킹 요청을 로봇 작업으로 변환하는 Task 처리 로직과 rack·cart controller, 로봇 암 제어 흐름을 구현했습니다. - Manager GUI와 Main Server 사이의 통신 구조를 정리하고, 로봇 상태·작업 상태·재고 상태가 함께 보이도록 연결했습니다. - AI 모듈과 DB 연동 결과를 시스템 흐름에 붙이고, 디렉토리·네이밍·문서 구조를 정리하며 리팩토링했습니다. - 주행·인식·GUI를 모두 직접 구현했다는 의미가 아니라, 각 모듈이 하나의 시연 흐름으로 이어지도록 통합하는 쪽을 맡았습니다. 매장 연동형 자율주행 로봇을 활용해 신발 상자를 자동으로 피킹(Picking)하고 전달하는 스마트 물류 솔루션입니다. - 오프라인 매장 내 물류 처리 자동화 및 효율화 - ROS2 기반 자율주행 로봇 개발 및 AI 영상 처리 기술 적용 - GUI 연동으로 실시간 재고 관리 및 피킹 요청 처리 LiDAR+IMU 기반 2D SLAM(Cartographer)으로 지도를 작성하고 자율주행에는 Nav2이 사용되었습니다. \ OpenCV ArUco Marker를 활용해 주행 초기 위치 보정과 근접 정렬·도킹 기능을 구현했습니다. \ YOLOv8n 모델로 신발 상자 객체 인식을 수행하고, Python 기반 GUI로 로봇 상태 및 재고 현황을 실시간으로 모니터링할 수 있습니다. ## 프로젝트 개요 | | | |-----|-----| | 기간 | 2025.04.09 ~ 2025.05.27 (7주) | | 팀명 | Secondary Wave | | 로봇이름 | ROScar | | 로봇그룹 | ROScars(로스카츠 🐷) |

| 역할 | 이름 | 주요 업무 요약 | |------|--------|----------------------------------------------------------| | 팀장 | 김연우 | - MainService 구조화 및 ROS2 통신 처리
- Task 처리 로직 및 ROS Action 연동
- 로봇 암 제어 및 rack·cart controller 개발
- Manager GUI 통신 구조 개선
- AI 모듈·DB 통합 및 시스템 리팩토링 | | 팀원 | 나덕윤 | - YOLO 기반 AI 모델 학습 및 라벨링
- 객체 인식 결과 MainServer 연동
- Manager GUI 상 로봇 상태 표시 구현
- 로그인 및 UI 흐름 설계 | | 팀원 | 남상기 | - 자율주행 기능 (TEB, 경로 계획, Waypoint)
- IMU, LiDAR, 초음파 센서 통신 처리
- ArUco 기반 절대 위치 추정
- Domain Bridge 및 통신 구조 설계 | | 팀원 | 심채훈 | - SLAM 및 Navigation 환경 설정
- ArUco 기반 위치 보정
- Battery·SSID 센서 퍼블리싱 및 DB 연동
- UDP 기반 영상 송신
- GUI 기본 기능 구현 | ### 주요 주행 기술 | 기능 | 기술 | | --- | --- | | 지도·SLAM | LiDAR+IMU 2D SLAM (Cartographer) | | 초기 위치 보정 | ArUco 마커 기반 `/initialpose` 보정 (OpenCV ArUco + Cartographer trajectory restart) | | 자율 주행·경로 계획 | Nav2 (NavFn 전역 플래너 + DWB 로컬 플래너 + 코스트맵) | | 웨이포인트 주행 | Nav2 FollowWaypoints 액션 | | 근접 정렬·도킹 | ArUco 기반 PID 정렬 | | 시각화 | RViz (SLAM·주행 뷰 분리) | | IMU 노이즈 보정 | 칼만 필터 기반 안정화 | ### 전체 기술 스택 | 분류 | 기술 요소 | |------------------|------------------------------------------------------------------| | 로봇 미들웨어 | ROS2, Nav2, TF2 | | 언어 | Python, C++ | | SLAM & 위치추정 | Cartographer SLAM, ArUco, Lifecycle Node | | 센서 융합 | LiDAR, IMU, Ultrasonic, Camera, Micro-ROS | | 객체 인식 | OpenCV, YOLOv8n | | GUI | PyQt6 | | 통신 | TCP, UDP(영상 전송), ROS2(Action·Service·Topic) | | 데이터베이스 | MySQL, ORM | | 협업 도구 | Git, Slack, Jira, Confluence | ### 주요 담당 업무 **Main Service 아키텍처 설계** - ROS2 Action·Service·Topic 기반 모듈 설계 및 task 처리 로직 개발 - GUI와 연동되는 토픽·서비스 흐름 구성 및 이벤트 통신 처리 **Controller 및 ROS2 패키지 개발** - 랙·카트 제어용 cart_controller, rack_controller 모듈 리팩토링 - 서보 모터 제어 로직 내장한 roscar_arm_controller 개발 **DB 연동 및 ORM 기반 구조 설계** - 시퀀스 다이어그램 기반 쿼리·테이블 구조 정의 및 SSL 설정 적용 - 로그 저장 및 인터페이스 기록을 위한 다중 DB ORM 구성 **시스템 통합 및 최적화** - TCP·UDP 기반 AI 모듈 연동 및 파일시스템 이벤트 처리 - Monorepo 기반 패키지 구조 재편 및 실행 스크립트 자동화 - 코드 네이밍·디렉토리 통일, 문서화 및 유지보수성 향상 # 프로젝트 결과 및 자료 ## 구현 하드웨어와 함께 제공된 ROS2 워크스페이스 [pinky_violet](https://github.com/pinklab-art/pinky_violet)에서 필요한 패키지를 Shopernoma에 맞게 수정하여 사용했습니다. \ 주요 패키지로는 `pinky_cartographer`, `pinky_navigation`, `pinky_bringup`가 있습니다. | 패키지명 | 패키지 기능 | 변경·적용 내용 | | --- | --- | --- | | `pinky_cartographer` | SLAM(Cartographer)으로 지도 작성 | 그대로 사용(기능·설정 변경 없음) | | `pinky_navigation` | Nav2 주행 스택(플래너·컨트롤러·코스트맵) | 맵 파일 교체, `nav2_params.yaml` 튜닝(footprint·robot_radius 등) | | `pinky_bringup` | 모터·배터리·센서 초기화 런치 | 모터·배터리 노드는 그대로 사용.
센서 및 카메라는 별도로 구현 | ## 주행 기술

**주행 시행착오(발전 과정)**

### 1. 센서 입력 수집

- GUI에 사용되는 센서 및 상태 퍼블리셔는 C++로 구현하여 지연·부하를 줄이고 안정적인 타이밍을 확보하도록 함 {/* - 주행쪽에서도 C++로 구현한 데이터를 사용하고싶었으나, `pinky_bringup`에서 Cartographer와 Nav2 등과 같이 주행 부분에 연결된 데이터가 너무 많아 그대로 사용할 수밖에 없었음 (시간문제) */} - 주행 관련 구현에는 Python으로 기존에 제공된 `pinky_bringup` 패키지의 노드를 그대로 사용 - 제조사 SDK로 센서 값을 직접 읽기 위해 `mobile_controller`에 센서 퍼블리셔 노드 별도 구현 (기본 설정은 표준 ROS 드라이버) - IMU: ICM20948 {/* (`/dev/i2c-1`, `0x68`) → `/roscar/sensor/imu` */} - LiDAR: SLLidar SDK {/* (`/dev/ttyAMA0`, 460800) → `/roscar/sensor/lidar` */} - 초음파: GPIO {/* TRIG=23, ECHO=24 (`gpiod`) → `/roscar/sensor/ultra` */} - 배터리: ADS1115 {/* (`0x48`) 샘플링 → `/roscar/status/battery` */} - 카메라 {/* - ROS 이미지 토픽 대신에 UDP 스트리밍 사용한 이유: 학습목적도 있었기에 ROS끼리 통신과 ROS와 ROS아닌 통신 간의 차이를 경험해보고자 함. */} - 메인 스레드에서 Picamera2로 직접 캡처 - 프레임을 UDP로 스트리밍 전송하면서, 같은 프레임으로 [ArUco 정렬(PID)](##### 6. [ArUco PID] 근접 정렬·도킹)을 수행 - 정렬 결과 /cmd_vel 퍼블리시는 메인 루프에서 ArucoAlign.process_frame()이 직접 수행 - ROS 콜백 처리 루프인 `rclpy.spin(align_node)`는 별도의 스레드로 분리해 메인 루프가 블로킹되지 않게 유지

### 2. SLAM 및 지도 작성 - Cartographer(2D SLAM)으로 갈 수 있는 공간(흰색)과 갈 수 없는 공간(검정색)을 구분하여 `roscars_map.pgm`(흑백 이미지 파일) 지도를 작성 - LiDAR(`/scan`) + IMU(`/imu`) 융합으로 센서가 인식될 때마다 Cartographer가 `/map`, `/tf`를 사용해 자동으로 맵 업데이트 - 이때, 업데이트되면서 기존에 흑색인 부분이 희색으로 바뀌는 현상 발생 → 그림판으로 갈 수 없는 공간(검정색) 복원하여 최종 지도 작성 {/* - PGM은 흑·백 점유 지도이므로, 필요 시 수동 편집으로 장애물(검정) 영역 복구 가능 */}

### 3. [Nav2] 자율주행 - 전역 플래너: NavFn (Dijkstra) - 로컬 플래너: DWB - `pinky_navigation`에서 Nav2 주행 스택 기능 사용하여 SLAM으로 작성한 지도를 적용하고 플래너, 컨트롤러, 코스트맵 등의 설정 조정 - 맵 파일 교체와 `nav2_params.yaml` 튜닝(footprint·robot_radius 등)을 적용 - costmap 구성 및 velocity_smoother 사용으로 주행 안정화 - 전역 경로는 임의로 선정한 웨이포인트를 순서대로 NavFn이 계산 위와 같이 Dijkstra와 DWB 조합으로 최종 구현됐으며, 아래는 초기 목표였던 A*과 TEB 적용 시도 내용입니다. - 초기 목표인 A*과 TEB는 아래와 같은 문제로 적용하지 못함 - TEB는 당시에 Jazzy 버전의 사용 가능한 오픈소스가 없어 직접 구현했으나, 좌우로 움직이며 둠칫둠칫하는 등의 불안정한 주행 현상 발생 - A*은 구현하여 nodes까지 구성·연결했으나, edges가 구성·연결이 완료되지 않아 실제 구현에는 적용되지 못함 {/* - 맵 로드: `roscars/pinky_navigation/map/roscars_map.yaml` - 설정: `roscars/pinky_navigation/params/nav2_params.yaml` footprint는 로봇의 바닥면 윤곽을 2D 다각형(좌표 리스트)으로 정의한 것으로, 회피/경로 계획 시 로봇이 실제로 차지하는 영역을 반영함. 로봇이 주행 중에 벽에 너무 가까이 붙거나 급격히 방향을 바꾸는 현상이 발생하여 로봇의 크기를 높게 설정해 보완함. robot_radius는 로봇을 원형으로 단순화했을 때의 반지름 값으로, footprint 대신 단순 모델로 충돌 여유를 계산할 때 사용됨. velocity_smoother는 가속도 제한 노드로, 로봇이 급격히 속도를 변경하지 않도록 줌. \ 이를 통해 로봇의 움직임이 보다 부드럽고 안정적으로 변하며, 주행 중 흔들림이나 충격을 줄여줌. costmap은 로봇 주변 공간을 비용 지도로 나타내는 2D 그리드 맵으로 각 셀에 로봇의 이동 여부를 나타내 장애물, 자유 공간, 위험 구역 등을 표시함. \ 장애물과 가까울수록 비용을 높게 매겨서, 경로 계획기가 안전한 공간을 우선으로 선택하도록 만든다. - 장애물 = 높은 비용 - 통과 가능한 공간 = 낮은 비용 - **장애물 주변에 완충 영역(Inflation)**을 만들어 충돌여유를 확보 Nav2는 이 costmap을 사용하여 경로 계획과 장애물 회피를 수행함. - global costmap: 전체 경로 계획용 - local costmap: 주변 회피/미세 제어용 */}

### 4. [FollowWaypoints] 웨이포인트 주행

- 개발용으로 갈림길의 좌표 6개를 웨이포인트로 사전에 정의하여 주행 테스트 - 좌표는 RViz에서 `2D Nav Goal`로 위치를 지정한 후에 `Publish Point`로 좌표 기록 - `FollowWaypoints` action으로 웨이포인트 순차 주행 {/* - Nav2 `FollowWaypoints` 액션으로 웨이포인트 순차 주행 - Nav2 waypoint_follower 서버 + C++ 클라이언트 구성 - `roscars/mobile_controller/nav_drive/waypoint_follower.cpp`에서 액션 클라이언트 구현 - A* 적용 - `roscars/mobile_controller/nav_drive/astar.cpp`에 A* 구현 - `waypoint_follower.cpp`에서 `astar.search(0, 5)`로 경로를 계산 후 웨이포인트 전송 - `edges`가 비어 있어 그래프가 구성되지 않음 - A* 호출은 실행되지만 유효한 최단 경로를 만들지 못할 수 있음 */}

### 5. [ArUco `/initialpose`] 초기 위치 보정

- ArUco 마커 ID를 map 좌표에 매핑해 사용 {/* `roscars/aruco_mapper/aruco_marker_positions.json` */} - 좌표 산정 흐름: - RViz Nav Goal·Publish Point로 좌표를 확인 - ArUco 역인식으로 마커 좌표 추정 시도했으나 오차가 커서 중단(키보드 방향키 teleop로 이동하며 카메라로 마커 인식 → CSV 저장) - 카메라와 마커간의 거리를 줄자로 실제 길이를 측정하고 map 좌표계(m 단위)로 변환 좌표값을 보정 - 최종 좌표값을 JSON에 key-value로 저장 - Picamera2 프레임에서 ArUco 검출 → `/initialpose` 퍼블리시 - 마커 방향 그룹(E·W·N·S)별 오프셋 보정 로직 포함 - Cartographer trajectory 재시작으로 초기 위치 반영 {/* 로컬라이저: 마커를 보고 현재 위치나 자세를 추정하는 노드 - ArUco 로컬라이저는 마커 위치를 시각화용으로만 퍼블리시하며, 네비게이션에 직접 관여하지 않음. - 즉, 위치를 계산하긴 하되 이동 계획이나 위치 추정 흐름에 직접 반영하지 않음 */} {/* - yaw 각도: - 기체나 물체가 수직축을 중심으로 좌우로 회전한 각도 - 어느 방향을 바라보는지 나타내는 각도 (0°=동, 90°=북, 180°=서, 270°=남) */} {/* - 마커 방향 그룹(E·W·N·S): - ArUco 마커가 카메라 프레임 기준으로 어느 방향을 바라보는지에 따라 묶은 분류 - 카메라 프레임 기준으로 마커 자세를 추정하면 마커가 바라보는 방향에 따라 위치 오차 패턴이 다르게 나타남 - yaw 각도를 기준으로 동·서·남·북 네 그룹으로 나누고, 미리 측정한 오프셋을 더하거나 빼서 initialpose에 올리는 위치·각도 계산 - 방향별로 오차 패턴이 달라서 각 그룹마다 보정값을 적용해야함 - 결과적으로 같은 마커라도 방향에 맞는 보정을 거쳐 위치·각도 정확도가 높아짐 */} {/* - Cartographer의 trajectory: - 로봇의 위치·자세가 시간에 따라 이어진 경로(즉, 지금까지 어디를 어떻게 움직였는지 기록한 것) - 센서 데이터를 적분해서 추정 - Cartographer는 보통 로컬 trajectory로 단기 추정을 만들고, 백엔드 최적화로 전역 trajectory를 보정하면서 지도를 갱신함 */} ### 6. [ArUco PID] 근접 정렬·도킹 - 정밀 정차·도킹을 위해 ArUco 마커 오차를 PID 제어로 보정 - 카메라 프레임에서 ArUco 마커를 검출해 좌우·거리 오차를 계산 - 오차를 PID로 제어해 속도 명령(`/cmd_vel`) 생성 → 목표 거리·각도 도달 시 정지 {/* - 역할 분리를 위해 로컬 제어로 동작시켜 Nav2 경로 제어와 분리시킴 */}

### 7. [Kalman Filter] IMU 노이즈 보정 - IMU 노이즈 보정을 위한 칼만 필터 데이터는 수집 완료 - 적용 목적은 IMU 흔들림 기반 충돌 로그 기록이었으나 시간 문제로 필터링 파이프라인 및 기능은 적용하지 못함

### 8. [Micro-ROS + Platform.io + Docker] MCU 센서 통신 Rack과 Cart에서 집품을 확인하는 기능에 ESP32 MCU 펌웨어가 사용되었습니다. \ 보드의 설정은 Platform.io로 관리되며, 시리얼 통신으로 센서 데이터를 얻습니다. \ Micro-ROS agent로 ROS2 네트워크와 통신합니다. 이는 Docker로 배포하여 환경 설정을 간소화했습니다. {/* PlatformIO: 임베디드 보드(ESP32 등)용 펌웨어를 빌드/업로드/모니터링까지 통합 관리해주는 개발 환경(IDE/CLI) */} {/* Micro-ROS: ROS 2를 MCU(마이크로컨트롤러)에서도 쓰기 위한 경량 통신/실행 스택으로, 에이전트를 통해 ROS 2 네트워크와 브릿지됨 */} {/* Docker: 개발/배포 환경을 컨테이너 이미지로 패키징해 동일한 실행 환경을 재현하는 가상화 도구 */} {/* PlatformIO vs Docker: PlatformIO는 MCU 펌웨어의 개발·배포(보드 업로드), Docker는 애플리케이션 런타임 환경을 컨테이너로 재현·배포하는 도구로 목적과 레벨이 다름 */} **Micro-ROS agent 실행 절차(컨테이너)** PlatformIO 타깃 보드: `esp32dev`(cart), `esp32-s3-devkitc-1`(rack) 1. [ROScar Docker 이미지](https://hub.docker.com/r/yonmilk/roscars) 내려받기
``` docker pull yonmilk/roscars:rack-esp32-s3-wroom-1-0.1.0 ``` 2. MCU 연결 및 디바이스 확인(호스트)
USB 연결 후 `/dev/ttyACM*` 또는 `/dev/ttyUSB*` 확인 3. 컨테이너 실행 + 시리얼 디바이스 매핑
``` docker run --rm -it --device /dev/ttyACM0 --group-add dialout yonmilk/roscars:rack-esp32-s3-wroom-1-0.1.0 ``` 4. 컨테이너 내부에서 Micro-ROS agent 실행
``` ros2 run micro_ros_agent serial --dev /dev/ttyACM0 -b 115200 -v4 ``` 5. 연결 확인
Agent 로그에 XRCE-DDS 세션/클라이언트 연결 로그가 출력되는지 확인

## GUI

## 설계 - [User Requirements Specification (URS)](shoepernoma/user-requirements.md) - [System Requirements Specification (SRS)](shoepernoma/system-requirements.md) - [Interface Specification](shoepernoma/interface-specification.md) - [Scenario](shoepernoma/scenario.md) - [GUI Specification](shoepernoma/gui-specification.md) ## 시스템 구조 ## 지도 ## 주요 ROS 통신 인터페이스 ## 시퀀스 다이어그램 ## 전체 주행 상태

## 데이터 구조 ## Hardware 구성