# URDF 검증 및 디버깅 기법 #### URDF 파일 구조 점검 URDF(Unified Robot Description Format)는 XML 기반의 로봇 모델 기술 방식이며, 복잡한 로봇 구조를 표현하기 위해 링크(link), 조인트(joint), 센서(sensor) 등을 계층적으로 기술한다. URDF가 의도대로 동작하지 않을 경우 가장 먼저 해야 할 일은 XML 구조가 유효한지 점검하는 것이다. * **XML 문법 오류**: 여는 태그와 닫는 태그의 위치가 일치하는지 확인한다. * **속성값 형식 오류**: 예를 들어, 관성 요소(`inertial`)나 충돌 요소(`collision`)에서 float 형식의 숫자를 적어야 하는데 문자열을 잘못 적은 경우 등을 확인한다. * **중복 선언 및 중복 ID**: 링크나 조인트 이름이 중복으로 선언되면 로봇 모델 파싱 과정에서 충돌이 일어난다. URDF 파일을 검증하기 위해서는 ROS에서 제공하는 `check_urdf`와 같은 유틸리티를 활용할 수 있다. ```bash # ROS 환경이 세팅된 터미널에서 check_urdf my_robot.urdf ``` 이 명령을 실행하면, URDF 파일이 파싱되는 과정에서 발생하는 문법 오류나 구조적 문제에 대한 정보를 즉시 확인할 수 있다. #### 로봇 링크 및 조인트 선언 검증 URDF에서 링크와 조인트 선언이 정확히 매칭되지 않으면 RViz나 Gazebo에서 로봇이 기대와 다른 형태로 그려지거나, 일부 링크가 보이지 않는 문제가 생길 수 있다. * **링크가 존재하지 않는데 조인트에서 참조하는 경우**: 특정 조인트에서 `$parent` 또는 `$child`로 명시된 링크 이름이 존재하지 않으면, ROS에서 URDF 파싱 시 에러가 발생한다. * **지나치게 복잡한 링크 구조**: 하나의 링크에 너무 많은 시각적 요소(visual)나 물리적 요소(collision)가 오버레이되어 있는지 확인한다. 또한, RViz나 Gazebo에서 모델이 로드되었을 때 링크들이 예상한 좌표계 위치에 배치되는지, 혹은 전혀 다른 위치에 표시되는지 확인한다. #### 시각적 디버깅(Vizual Debugging) RViz에서 URDF를 시각적으로 확인하면서 디버깅하는 방법은 직관적이다. URDF를 로드한 뒤, 문제점이 발생하는 링크나 조인트를 하나씩 감춰가며, 어떤 부분에서 위치나 형태가 이상하게 표현되는지 확인한다. * **Visual 요소의 색상, 투명도 설정 오류**: 시각적으로 링크가 사라진 것처럼 보이면, 실제로 색상 혹은 `rgba`(red-green-blue-alpha) 설정이 적절치 못해 투명도가 1보다 작은지(즉, 투명도가 높게 설정되어 보이지 않는 경우) 점검한다. * **부품 간 간격이 지나치게 큼**: 예컨대 로봇 팔 링크가 분리되어 보인다면, 조인트 연결 관계의 위치나 회전 중심이 제대로 정의되지 않았을 가능성이 있다. #### Gazebo 시뮬레이션 상에서의 디버깅 URDF가 Gazebo 플러그인과 함께 동작하려면, URDF 내부에 `` 태그들이 올바르게 설정되어야 한다. 가령 물리 엔진 파라미터, 센서 플러그인 등이 올바르게 참조되지 않으면, 시뮬레이션을 시작했을 때 물리적으로 정상 동작하지 않을 수 있다. **관성 파라미터 오류**: URDF의 `` 요소 정의가 부정확하면, Gazebo에서 물리 시뮬레이션이 어색해진다. 관성 행렬(inertia tensor) $\mathbf{I}$은 다음과 같은 형태로 표현된다. $$ \mathbf{I} = \begin{bmatrix} I\_{xx} & I\_{xy} & I\_{xz} \ I\_{xy} & I\_{yy} & I\_{yz} \ I\_{xz} & I\_{yz} & I\_{zz} \end{bmatrix} $$ 대부분의 경우 대칭 행렬이므로 $I\_{xy} = I\_{yx}$, $I\_{xz} = I\_{zx}$, $I\_{yz} = I\_{zy}$처럼 정의된다. 인쇄 후 값이 어긋난 부분이 있으면 URDF에서 잘못 표기된 부분이 있는지 확인해야 한다. **조인트 물리 파라미터 오류**: 조인트의 마찰 계수나 감속 계수(damping)가 터무니없이 큰 값 또는 0으로 설정되어 있을 수 있다. 이 경우 시뮬레이션 상에서 조인트가 전혀 움직이지 않거나, 혹은 폭주하게 된다. #### 관성 및 질량 검증 URDF 상에서 관성 및 질량 설정은 시뮬레이션의 물리적 안정성에 매우 큰 영향을 준다. 특이하게도 질량 $m$이나 관성 텐서가 지나치게 작게 설정되어 있으면, 로봇이 물리적으로 불안정해진다. **질량 검증**: 로봇 전체 질량에 비해 특정 링크가 지나치게 무겁거나, 혹은 지나치게 가벼운 값을 가지지는 않는지 확인한다. **관성 검증**: * 주축(Principal axis)에 대해 관성값이 일관성이 있는지 * 관성 텐서 대각 항($I\_{xx}, I\_{yy}, I\_{zz}$)이 음수가 아닌지 * 실제 하드웨어 구조에 비추어 말이 되는 값인지 **관성 텐서 시각화** 관성이 적절하게 정의되었는지 확인하기 위해서는 다음과 같은 다이어그램을 참고할 수 있다: {% @mermaid/diagram content="flowchart TB A\[Actual 3D Model] --> B{Parameter\nExtraction} B --> C\[Compute Inertia Tensor] C --> D\[Compare with URDF Inertia]" %} 이 과정을 통해 실제 CAD 등에서 추출한 관성 텐서와 URDF에 기재한 값이 어느 정도 오차 범위 내에 있는지 확인할 수 있다. #### Visual 및 Collision 지오메트리 정합(Alignment) 문제 디버깅 URDF에서 한 링크에 대해 \*\*시각적 지오메트리(visual)\*\*와 \*\*충돌 지오메트리(collision)\*\*를 따로 정의할 수 있다. 시각적 지오메트리는 말 그대로 사람에게 보이는 모델을, 충돌 지오메트리는 물리 시뮬레이션 엔진에서 충돌 계산에 사용되는 모델을 의미한다. 따라서 두 지오메트리가 동일한 좌표계 및 축(scale)을 적절히 가지는지 확인해야 한다. **머티리얼(Material)만 정의된 시각적 요소**: 단순한 메쉬 파일(Collada, STL 등)을 불러오지 않고, URDF에서 `` 태그 내에 ``, ``, ``와 같은 기본 형상만을 정의하는 경우가 있다. 이때 시각적으로는 단순한 색상 재질만 확인할 수 있으므로, 실제 모델 크기가 제대로 반영되었는지, RViz의 그리드와 비교해 눈으로 점검한다. Collision 지오메트리가 너무 단순하거나 복잡: * 충돌 지오메트리가 지나치게 단순하면(예: 로봇 팔에 구체 하나만 부착), 실제 환경과 충돌 감지가 제대로 되지 않는다. * 충돌 지오메트리가 너무 복잡하면(예: 고해상도 메쉬 파일), 시뮬레이터 성능에 영향을 줄 수 있다. 보통은 시각적 지오메트리보다 더 단순화된 메쉬 또는 프리미티브(primitive) 기하학을 사용하되, 지나치게 단순하지 않도록 균형을 맞춘다. RViz에서 확인할 때는 시각적 지오메트리와 충돌 지오메트리를 각각 켜고 꺼볼 수 있으므로, 두 지오메트리가 서로 맞물려 있는지, 혹은 공간적으로 어긋나 있는지를 쉽게 파악할 수 있다. #### Xacro 매크로 디버깅 URDF를 직접 작성하는 대신, Xacro(XML Macros)를 사용해 반복되는 요소를 쉽게 관리할 수 있다. 하지만 매크로를 잘못 적용하거나, 매크로 내부의 파라미터를 잘못 전달하면 결과적으로 생성된 URDF가 의도와 달라지는 경우가 많다. * **Xacro 파라미터 확인** Xacro 파일 상단에 `$xacro:property`로 정의한 변수들이 제대로 사용되는지 확인한다. * **중첩 매크로** 매크로를 여러 번 중첩해 사용하면 구조가 복잡해지므로, 디버깅에 어려움을 겪을 수 있다. 이런 경우 `$xacro --inorder` 옵션 등으로 최종 생성된 URDF 파일을 확인하며 문제를 찾는다. ```bash # Xacro 파일로부터 실제 URDF 생성 xacro my_robot.xacro > my_robot.urdf # 생성된 URDF 문법 확인 check_urdf my_robot.urdf ``` 위와 같은 과정을 거치면서 단계별로 결과물을 확인하는 것이 중요하다. #### TF(Transform) 트리 확인 ROS에서 로봇 모델을 운용할 때, **Robot State Publisher**를 통해 URDF 기반 TF 트리를 방송한다. 특정 링크가 엉뚱한 위치나 회전 상태로 보인다면, TF 프레임 구조에 문제가 있을 수 있다. 1. Robot State Publisher 노드 실행 * URDF(또는 Xacro가 변환된 URDF)를 로드하여 각 링크 간 좌표계 관계를 방송한다. 2. `ros2 run tf2_tools view_frames` 등의 도구 활용 * TF 트리가 어떻게 구성되어 있는지를 `.pdf` 등의 형태로 시각화해 볼 수 있다. 3. TF 변환의 누락 * 특정 링크를 정의했는데, 그 링크에 대한 좌표 변환이 제대로 설정되지 않아 TF 트리에 해당 링크가 포함되지 않는지 확인한다. #### URDF 플러그인(Plugin)에서 발생하는 이슈 로봇 모델에 센서나 액추에이터 동작을 정의하기 위해 URDF(또는 SDF) 안에 Gazebo용 플러그인을 삽입하는 경우가 많다. 이때 다음과 같은 문제들이 발생할 수 있다. * 플러그인 로드 에러: * 플러그인 이름(예: `libgazebo_ros_diff_drive.so`)을 잘못 입력했을 때 * ROS 패키지 경로가 설정되지 않아 Gazebo가 해당 플러그인을 찾지 못할 때 * **파라미터 불일치**: 각 플러그인이 요구하는 파라미터가 있는데, URDF 내에 `` 태그에서 이 파라미터를 올바르게 입력하지 않으면 시뮬레이션이 정상적으로 동작하지 않는다. 예시로, 차동 드라이브 로봇(diff-drive robot) 플러그인의 경우 바퀴 링크 이름(`left_wheel`, `right_wheel`), 축간 거리(wheel separation), 휠 지름(wheel radius) 등을 정확히 입력해야 한다. #### URDF-SRDF 연동 디버깅 MoveIt이나 기타 고급 로봇 제어 패키지에서는 URDF와 더불어 SRDF(Semantic Robot Description Format)를 사용한다. SRDF는 로봇의 운동학 그룹(kinematic group), 제한사항, 플래너 설정 등을 정의하기 때문에 URDF와의 정합이 매우 중요하다. * **링크/조인트 명 불일치** SRDF에서 특정 조인트(joint)이름을 참조하는데, URDF에서 해당 이름이 존재하지 않을 경우 MoveIt 환경 구성 시 에러가 발생한다. * **플래닝 그룹 누락** 팔이나 그리퍼, 또는 모바일 베이스 등에 대한 플래닝 그룹을 SRDF에 정의하지 않으면, MoveIt에서 해당 로봇 요소를 인식하지 못한다. * **로봇 상태 초기화 문제** MoveIt Setup Assistant 등에서 생성된 SRDF 파일 내 ‘기본 자세(default posture)’가 URDF에서 불가능한 조인트 각도를 참고하는지 확인한다. 일반적으로 MoveIt Setup Assistant를 통해 SRDF를 자동 생성한 뒤, 수동으로 수정하는 과정에서 오탈자가 발생하기 쉬우므로, 각 단계에서 URDF와 SRDF의 링크·조인트 이름이 정확히 일치하는지 꼼꼼히 확인해야 한다. #### Orientation 설정 디버깅 (Roll, Pitch, Yaw vs. Quaternion) URDF에서 링크 및 조인트의 위치는 3차원 좌표계 상의 위치 $x, y, z$와 회전(orientation)으로 정의되는데, 회전은 `rpy`(roll, pitch, yaw) 혹은 `xyz`(회전축-회전각) 형식으로 많이 지정한다. * **Roll, Pitch, Yaw 순서** ROS URDF에서 기본적으로 `rpy`는 $\text{roll} \rightarrow \text{pitch} \rightarrow \text{yaw}$ 순서로 축을 적용한다. 이를 잘못 해석하여 $\text{yaw} \rightarrow \text{pitch} \rightarrow \text{roll}$ 순으로 이해하면, 실제 표현되는 방향이 전혀 다르게 될 수 있다. * **Quaternion 변환** ROS 내부적으로 `rpy`는 쿼터니언 $\bigl(w, x, y, z\bigr)$으로 변환되어 사용된다. 쿼터니언 $q = (w, x, y, z)$의 정상화(normalization)가 제대로 되어 있는지, 혹은 $w$가 음수가 되어 로봇 조인트 방향이 반대로 보이는지는 아닌지 살펴볼 필요가 있다. * **중첩 회전** 조인트가 여러 축에 걸쳐 연달아 회전하는 메커니즘일 경우, 순서나 축 정의가 잘못되어 모델이 뒤틀릴 수 있다. 실제 로봇 매뉴얼에 표시된 조인트 순서를 토대로, URDF 상 `rpy`를 지정하는 순서가 일치하는지 확인한다. #### ros2\_control 설정 디버깅 ROS2 Humble 환경에서 로봇의 하드웨어 인터페이스를 구성하기 위해서는 `ros2_control` 프레임워크가 점차 표준으로 자리 잡고 있다. 이를 위해 URDF 내부(또는 별도의 xacro)에서 `` 태그를 정의해야 하는데, 다음과 같은 실수들이 잦다. * 하드웨어 인터페이스 타입 미스매치 * 예: Effort Interface 필요하지만 Position Interface로 선언 * 예: 실제 서보모터는 단순 위치제어만 가능한데, URDF에서는 속도제어, 토크제어까지 정의 * 컨트롤러 파라미터 누락 * `` 내에 각 조인트 컨트롤러의 PID 또는 gains 설정이 누락되면, 시뮬레이션에서 원하는 대로 제어가 이루어지지 않는다. * 조인트 리밋(joint limit) 설정 오류 * URDF의 `` 태그에서 `upper`, `lower`, `velocity` 등을 적절히 설정해야 한다. `velocity` 제한을 지나치게 작게 잡으면, 컨트롤러가 올바른 동작을 못 하거나 에러가 발생할 수 있다. #### URDF to SDF 변환 문제 Gazebo(특히 Ignition Gazebo)에서 URDF를 직접 사용하기도 하지만, 내부적으로 SDF(Simulation Description Format)로 변환해 사용한다. 변환 과정에서 일부 정보가 손실되거나, 제대로 매핑되지 않는 문제가 발생할 수 있다. * **Plugs or Additional Tags** Gazebo에서만 사용하는 추가 태그(예: `` 태그 내부 설정)가 SDF 변환 과정에서 누락되지 않는지 확인한다. * **Mesh File 경로** URDF에서 `package://` 형태로 메쉬 파일을 참조하는 경우, SDF 변환 시 실제 풀 경로가 올바르게 변환되는지 확인한다. * **조인트 제한 및 물리 파라미터** URDF와 SDF에서 조인트 제한 설정 방식이 조금 다를 수 있으므로, Gazebo 로드 시 경고 메시지가 뜬다면 조인트 제한 값이 제대로 들어갔는지 살펴봐야 한다. #### urdf\_to\_graphviz 활용 URDF 구조를 시각적으로 파악하기 위해 `urdf_to_graphviz` 유틸리티를 사용하는 것도 유용하다. 이 툴을 통해 URDF의 링크와 조인트 관계를 Graphviz 형태로 표현해 주므로, 복잡한 로봇 모델 구조를 트리(또는 그래프) 형태로 확인할 수 있다. ```bash # urdf_to_graphviz 설치 및 실행 예시 sudo apt-get install ros--urdf-tutorial urdf_to_graphviz my_robot.urdf ``` * 그래프 시각화 결과 분석 * 링크와 조인트가 어떻게 연결되어 있는지 한눈에 확인 * 조인트가 여러 갈래로 분기되어 있거나, 역으로 불필요한 고리가 생기지는 않았는지 점검 이와 같은 그래프 기반 디버깅은 특히 링크가 많은 복잡한 매니퓰레이터나 서비스 로봇에서 구조적인 문제를 빠르게 파악하는 데 도움이 된다. #### 고급 URDF 디버깅 전략 URDF 작성이 단순히 로봇의 운동학 구조만을 기술하는 것이 아니라, 실제 시뮬레이션 및 센서·액추에이터 플러그인과도 밀접히 연계된다는 점을 감안하면, 아래와 같은 고급 디버깅 전략이 필요하다. * **단계별 최소 로봇 모델 구성** 로봇이 복잡할수록 한꺼번에 URDF를 작성하면 문제가 발생했을 때 원인을 찾기가 어렵다. 1. 링크 두 개와 단순 조인트 하나만 정의한 최소 로봇 모델을 만든다. 2. 이 모델이 정상적으로 동작함을 확인한 뒤, 점진적으로 링크와 조인트를 추가한다. 3. 문제 발생 시, 어느 지점에서부터 동작이 이상해지는지 추적이 가능하다. * **CAD → URDF 연동 시 검증** 복잡한 로봇 구조의 경우, CAD 소프트웨어(예: SolidWorks, Fusion 360)에서 직접 관성 텐서와 질량, 치수를 추출하여 URDF에 반영한다. 이때 단계별로 결과를 검증하는 것이 좋다. * CAD에서 도출한 질량 총합과 URDF 최종 질량 총합 비교 * CAD에서 도출한 관성 텐서와 URDF 관성 텐서가 동일한지(또는 지정된 공차 이내인지) * **Gazebo 물리 파라미터 튜닝** Gazebo에서 URDF로부터 변환된 모델이 물리적으로 불안정하게 행동한다면, 다음을 확인한다. * 각 조인트의 `cfm` (Constraint Force Mixing)이나 `erp` (Error Reduction Parameter) 값 * 바닥 마찰 계수와 로봇 휠(또는 발)에 설정된 마찰 계수 * `max_step_size`, `real_time_update_rate` 등의 시뮬레이션 파라미터 * **디버그 로깅(Debug Logging) 활용** ROS나 Gazebo에서 로그 레벨(예: DEBUG, INFO, WARN, ERROR)을 조정하면 보다 자세한 URDF 파싱 과정 및 물리 엔진 출력을 확인할 수 있다. ```bash # 예: Gazebo에서 로그 레벨을 DEBUG로 gazebo --verbose --log-level=debug ``` 이를 통해 URDF 또는 플러그인 로딩 단계에서 어떤 오류나 경고가 발생하는지 상세히 모니터링할 수 있다. * **동적(動的) 테스트** 로봇 조인트를 실제로 구동(시뮬레이터 상에서)해 보며, 특정 구간에서 갑자기 조인트가 튕겨나가거나, 링크가 조인트 제한을 초과해 움직이는 문제가 없는지 살핀다. 만약 보이지 않는 곳에서 링크가 겹치고 있다면, 충돌 반발력 때문에 폭주가 발생할 수도 있다. * **공유 메모리 및 네임스페이스 확인** 복수의 URDF(Xacro)가 서로 상호 참조되거나, 하나의 패키지 안에서 이름 충돌이 발생할 수도 있다. 같은 링크 이름이 두 번 정의되지 않았는지, 여러 개의 URDF 파일이 같은 하드웨어 리소스를 공유해 혼동이 생기지 않았는지 확인한다. #### URDF 모델 버전 관리 버전 관리를 제대로 하지 않으면, 디버깅 자체가 어려워진다. Git 등 VCS(Version Control System)를 사용해 URDF 파일 변경 이력을 추적함으로써, 어느 시점에서 문제가 발생했는지 빠르게 파악할 수 있다. * **커밋 단위를 작게 유지** URDF를 대규모로 수정하면, 디버깅 시점이 모호해진다. 가능한 작은 단위로 변경하고 커밋 메시지에 “조인트 A의 관성 수정” 등 구체적인 설명을 남긴다. * **태그(Release Tag) 혹은 브랜치** “시뮬레이션 안정 동작” 등 로봇이 정상 구동하는 특정 커밋에 태그를 달아두면, 미래에 문제가 발생했을 때 태그가 달린 버전과 비교하며 빠르게 문제점을 찾을 수 있다. #### CI/CD 파이프라인에 URDF 테스트 통합 소프트웨어 개발 환경에서 URDF 품질을 유지하기 위해 CI/CD(Continuous Integration / Continuous Deployment) 파이프라인에 URDF 검증 스크립트를 넣는 것이 좋다. * **문법 검사** `check_urdf`를 자동화 파이프라인에서 실행하여 URDF 문법 오류가 있으면 빌드가 실패하도록 설정한다. * **기본적인 시뮬레이션 구동 테스트** Docker 컨테이너나 가상 환경에서 Headless 모드로 Gazebo를 실행하여, URDF 로딩 시 에러 혹은 충돌이 발생하면 빌드를 중단한다. * **MoveIt/ros2\_control 테스트** MoveIt이나 ros2\_control에서 필요한 중요한 ROS 토픽이 잘 생성되는지를 확인하거나, 특정 동작 시퀀스를 간단히 실행해본 뒤 문제 여부를 체크한다. 이처럼 자동화된 테스트를 도입하면, URDF 관련된 누적 변경으로부터 발생하는 런타임 문제를 사전에 방지할 수 있다.