⚠️ v2.1.1 호환성: 2.1.1에서 토픽 이름·메시지 타입·서비스 이름이 모두 바뀌었습니다. 2.1.0 SDK 클라이언트는 2.1.1 로봇과 통신되지 않으며, 이때 에러 없이 서로를 발견하지 못합니다(0 FPS, 서비스 타임아웃). SDK 배포본을 2.1.1로 교체하고 예제와 사용자 코드를 다시 빌드하십시오.

1. Middleware

• Igris-C는 DDS를 메시지 미들웨어로 사용하며, 주요 데이터 통신 방식으로 Publish/Subscribe 모드와 Request/Response 모드 두 가지 방법을 사용합니다.

• Publish /Subscription

  • 수신자는 메시지를 구독하고, 송신자는 구독 목록에 따라 수신자에게 메시지를 전송합니다. 이 방식은 중·고주파수 또는 지속적인 데이터 교환에 주로 사용됩니다.

• Request/Response

  • 요청(Request)을 통해 데이터 조회나 동작 수행이 이루어집니다. 이 방식은 저주파수 데이터 교환이나 기능 전환(Function Switching) 시 사용됩니다.

2. Architecture Description

• DDS Middleware

  • IGRIS-C 및 관련 SDK에서는 이 DDS 미들웨어 위에서 커맨드와 상태 정보를 교환함으로써, 내부 모듈과 외부 개발 PC 간에 확장 가능하고 일관된 통신 구조를 제공합니다.

• Motion Control (로봇의 움직임을 직접 만들고 유지하는 로우레벨 제어 엔진)

  • Motion Control 모듈은 IGRIS-C의 로우레벨 운동 제어 핵심 엔진으로, 매우 빠른 내부 제어 루프를 기반으로 동작합니다.

• 주요 기능

  1. 고주기 로우레벨 제어 루프

     • 내부 컨트롤 코드에서 μs~ms 단위로 제어 루프 실행

     • 각 관절/모터에 대한 토크·속도·위치 명령을 고속으로 업데이트

  2. CAN 통신 기반 모터 제어

     • 수신한 제어 명령을 CAN 메시지로 인코딩하여 각 모터로 전달

     • 모터 상태(전류, 속도, 온도, 각도 등)를 실시간으로 수집하여 DDS로 전송

  3. 상태 정보 → DDS 미들웨어로 전달

     • IMU, 관절각, 동적 상태 등 다양한 센서 값은 DDS 토픽으로 퍼블리시되어 개발 PC에서 구독 가능

  4. DDS에서 들어오는 커맨드 처리

     • 외부 개발 PC에서 발행한 DDS 모션 커맨드를 수신

     • 제어 루프 안에서 즉시 적용하여 모터에 반영

• Image Services

  • Image Services 모듈은 IGRIS-C의 이미지 스트림 처리 및 외부 통신을 담당합니다.

  • 주요 기능

    1. 카메라 영상 처리 및 스트리밍

       • IGRIS-C에 연결된 카메라로부터 영상 프레임 수집

       • DDS 기반으로 직접 전송

       • 카메라 영상도 로봇의 전송 모드(Transport)를 따릅니다. ros 레인으로 받을 때는 수신 PC 설정이 필요합니다(3절 참고).

지원 인터페이스: SDK는 DDS(Cyclone DDS), ROS2, Python 세 가지 클라이언트
인터페이스를 제공합니다. 예제는 각각 배포본의 cyclonedds/, ros2/, python/
폴더에 있습니다. 어떤 인터페이스로 로봇에 연결할 수 있는지는 로봇의 전송 모드가 정합니다(3절 참고). (이전 문서의 "ROS2 추후 예정" 안내는 더 이상 유효하지 않습니다 — ROS2 정식 지원.)

3. 전송 모드 (Transport)

IGRIS-C는 외부 통신 레인을 하나만 서비스하며, 로봇의 igris_c.network.transport(Web Viewer의 Config 탭)가 레인과 토픽 와이어 레이아웃을 함께 결정합니다. 레인은 bridge·카메라·마스터암에 공통으로 적용됩니다. 앱이 쓰는 TCP API(기본 포트 9000)는 레인과 무관하게 항상 제공됩니다.

ROS 2를 설치할 수 없거나 쓰지 않는 환경이라면 cyclonedds_native 레인과 C++/Python SDK(cyclonedds/, python/)를 사용하십시오. Cyclone DDS가 SDK에 번들되어 있어 ROS 2 의존성이 없으며, 토픽·서비스 기능은 ros 레인과 같습니다.

• 공통 발행 토픽: lowstate, handstate, pdustate, robotstate, odom, torso_twist_odom. 공통 구독 토픽: lowcmd, handcmd, cmd_vel(geometry_msgs/TwistStamped). ros 레인은 추가로 imu_state, motor_state, joint_state 토픽을 제공합니다.

• 클라이언트의 레이아웃 지정: C++ ChannelFactory::Instance()->Init(domain_id, ns, "", TopicNaming::RosCompatible), Python channel.Init(domain_id, ns, "", igc_sdk.parse_topic_naming("ros_compatible")). 예제는 --dds-topic-naming 플래그를 받습니다(client.ipynb 제외).

• 2.1.0의 설정값 cyclonedds·both는 더 이상 쓰지 않으며, 남아 있으면 경고 후 cyclonedds_native로 처리됩니다. 2.1.0처럼 DDS와 ROS 2를 동시에 제공하지 않습니다.

• 멀티캐스트가 막힌 망(Wi-Fi 로봇 + 유선 PC): cyclonedds 레인은 cyclonedds/cyclonedds_peers.xml, ros 레인은 ros2/fastdds_peers.xml을 사용합니다(파일의 <address>에 로봇 IP를 넣고 FASTRTPS_DEFAULT_PROFILES_FILE 지정 후 ros2 daemon stop). ROS_STATIC_PEERS는 participant 범위를 넓히지 못해 대체가 되지 않습니다.

• 카메라 영상을 ros 레인으로 받을 때는 수신 PC에서 ros2/setup_client_network.sh를 한 번 실행합니다(수신 버퍼·IP 재조립 풀 sysctl 설정).

cyclonedds_native(출하 기본) · cyclonedds_ros_compatible

# 배포본의 cyclonedds/ 폴더에서 (domain id·namespace는 로봇 설정과 같게)
export CYCLONEDDS_URI=file://$PWD/cyclonedds_spdp.xml
./build/cyclonedds_gui_client 0 igris_c_IG01               # 상태 모니터 GUI (domain 0, 호기 IG01)
./build/cyclonedds_service 0 igris_c_IG01                  # 서비스 콘솔 (PDU/토크/핸드/제어 모드)
python3 ../python/sdk_gui_client.py --domain-id 0 --namespace igris_c_IG01   # Python 예제

# 멀티캐스트가 로봇에 닿지 않을 때 — cyclonedds_peers.xml의 <Peer address>를 먼저 로봇 IP로 수정
export CYCLONEDDS_URI=file://$PWD/cyclonedds_peers.xml

# 로봇이 cyclonedds_ros_compatible 일 때는 각 예제에 --dds-topic-naming ros_compatible 을 붙입니다.

ros

# 배포본의 ros2/ 패키지를 빌드한 워크스페이스에서 (ROS_DOMAIN_ID·namespace는 로봇 설정과 같게)
ROS_DOMAIN_ID=0 ros2 run igris_c_sdk ros_lowstate_listener --ros-args -p robot_namespace:=igris_c_IG01

# 멀티캐스트가 로봇에 닿지 않을 때 — fastdds_peers.xml의 <address>를 먼저 로봇 IP로 수정
export FASTRTPS_DEFAULT_PROFILES_FILE=$PWD/fastdds_peers.xml
ros2 daemon stop

⚠️ 로봇과 클라이언트의 레인·토픽 레이아웃·namespace·domain_id 네 가지가 모두 일치해야 합니다. 하나라도 다르면 에러 없이 서로를 발견하지 못합니다(0 FPS, 서비스 타임아웃). 로봇의 domain_id는 igris_c.network.cyclonedds.domain_id(기본 0)입니다.

4. Robot Namespace (토픽 prefix)

모든 DDS 토픽은 로봇 호기(unit)별 namespace 아래로 해석됩니다. 호기마다 namespace가 다르며,

igris_c_접두사에 로봇별 suffix(호기마다 다름)가 붙는 형태입니다. 예: igris_c_IG01.

연결할 로봇의 namespace는 Web Viewer 또는 로봇 OLED 화면에서 확인합니다.

• SDK에서는 ChannelFactory::Init(domain_id, namespace) 로 namespace를 지정합니다.

• 코드에서는 접두어 없는 토픽 이름(lowstate)만 작성하고, 실제 토픽 이름(와이어 이름)은 SDK가 만들어 줍니다. rt/ 구간은 ROS 2 rmw가 붙이는 것이라 네이티브 레이아웃에는 없습니다.

  • TopicNaming::Native(기본, 로봇 cyclonedds_native): namespace igris_c_IG01 + lowstate → igris_c_IG01/lowstate

  • TopicNaming::RosCompatible(로봇 cyclonedds_ros_compatible): → rt/igris_c_IG01/lowstate. ROS 2 rmw가 /igris_c_IG01/lowstate를 맹글링한 결과와 같으므로, rclcpp 노드가 rmw를 바꾸지 않고도 구독할 수 있습니다.

• 레이아웃은 ChannelFactory::Init()의 4번째 인자 TopicNaming으로 지정합니다(생략 시 Native). 예제에서는 --dds-topic-naming native|ros_compatible 플래그로 지정합니다.

// C++
ChannelFactory::Instance()->Init(0, "igris_c_IG01");                  // domain 0, 호기 IG01
Subscriber<igris_c_sdk::msg::dds_::LowState_> sub("lowstate", QosProfile::SensorData());   // → igris_c_IG01/lowstate

// 로봇이 cyclonedds_ros_compatible 일 때
ChannelFactory::Instance()->Init(0, "igris_c_IG01", "", TopicNaming::RosCompatible);      // → rt/igris_c_IG01/lowstate

# Python
channel = igc_sdk.ChannelFactory.Instance()
channel.Init(0, "igris_c_IG01")

# 로봇이 cyclonedds_ros_compatible 일 때
channel.Init(0, "igris_c_IG01", "", igc_sdk.parse_topic_naming("ros_compatible"))

⚠️ 개발 PC(SDK 클라이언트)와 로봇이 동일한 namespace + domain_id 를 사용해야 통신됩니다. 연결할 호기의 namespace를 확인해 지정하세요. cyclonedds 레인에서는 토픽 레이아웃(TopicNaming)까지 로봇과 같아야 합니다.

예제 실행 전 — CYCLONEDDS_URI 환경 변수

DDS 통신은 네트워크 인터페이스 설정이 담긴 CycloneDDS XML 을 사용합니다. 외부 개발 PC에서
SDK 예제를 실행할 때는 이 XML을 CYCLONEDDS_URI 로 지정해야 로봇의 DDS 네트워크에 연결됩니다.
배포본의 cyclonedds/ 폴더에 예제용 XML 두 개가 동봉되어 있습니다(python/에도 같은 파일이 있습니다). 이 절은 cyclonedds 레인에 해당하며, ros 레인은 3절의 fastdds_peers.xml 안내를 따릅니다.

1. <NetworkInterface name="..."> 를 이 PC에서 로봇과 통신하는 네트워크
   인터페이스 이름으로 수정합니다. (인터페이스 목록 확인: ip link / 또는 autodetermine="true" 로 자동 선택) cyclonedds_peers.xml 은 <Peer address="..."> 에 로봇 IP도 함께 넣어야 합니다.

2. 예제 실행 전 CYCLONEDDS_URI 를 이 파일로 export 합니다.

# 배포본의 cyclonedds/ 폴더에서
export CYCLONEDDS_URI=file://$(pwd)/cyclonedds_spdp.xml
# 이후 예제 실행
./build/cyclonedds_hand_example 0 igris_c_IG01
# 로봇이 cyclonedds_ros_compatible 일 때
./build/cyclonedds_hand_example 0 igris_c_IG01 --dds-topic-naming ros_compatible

⚠️ 예제가 실행은 되는데 데이터가 하나도 들어오지 않는다면 — 모든 스트림이 0 FPS, 서비스는 타임아웃, 에러는 아무것도 뜨지 않는다면 — discovery가 완료되지 않은 것입니다. 멀티캐스트 차단이 가장 흔한 원인이며 cyclonedds_peers.xml 로 바꾸면 됩니다. 전송 모드·토픽 레이아웃·namespace·domain_id 불일치도 같은 증상을 보입니다. 아무도 발행하지 않는 토픽은 에러가 아니므로 어디에도 에러로 보고되지 않습니다.

설정하지 않거나 인터페이스가 맞지 않으면 participant 디스커버리가 실패해 토픽이 보이지 않습니다.
namespace · domain_id는 XML이 아니라 예제 인자(또는 ChannelFactory::Init)로 지정합니다.

5. Get SDK

• SDK 소개

  • igris_c_sdk 는 ROBROS에서 개발한 차세대 로봇용 SDK입니다. 이 SDK는 기본 모터 제어 및 고급 동작 제어와 같은 인터페이스를 캡슐화하고, 관련 기능 인터페이스를 제공합니다.

  • 제공되는 SDK와 예제를 참고하시면 로봇 제어를 학습하고 IGRIS-C의 2차 개발(Secondary Development)을 완성할 수 있습니다.

• SDK download

  • SDK: igris_c_sdk_public v2.1.1

  • Description: igris_c_description_public v2.1.1

  • 마스터암: igris_c_masterarm_public v2.0.6

  • 로봇 소프트웨어 2.1.1에는 위 버전을 사용하십시오. 각 저장소의 main 브랜치는 이후 릴리즈로 바뀔 수 있습니다.

• 배포본 구성 — 최상위 폴더는 서로 독립적이므로 사용하는 런타임에 맞는 것을 고릅니다.

  • dist/ — Python wheel (igris_c_sdk-*.whl)

  • cyclonedds/ — 네이티브 C++ SDK(헤더, 정적 라이브러리, 번들 Cyclone DDS), 예제 소스, cyclonedds_spdp.xml / cyclonedds_peers.xml

  • python/ — Python 예제와 재현 가능한 pixi 환경(pixi.toml, pixi.lock)

  • ros2/ — ROS 2 ament 패키지 igris_c_sdk(메시지·서비스 정의 + 예제 노드), fastdds_peers.xml, setup_client_network.sh. 패키지 폴더 ros2/src/igris_c_sdk_public/를 colcon 워크스페이스의 src/에 복사해 빌드합니다(배포본 루트를 넣으면 아무것도 빌드되지 않습니다).

• 빌드 환경과 의존성

  • Ubuntu 24.04 (x86_64), CMake 3.14 이상, C++17 (GCC 11+ / Clang 14+), Python 3.12. ROS 2 Jazzy는 ros2/ 패키지를 쓸 때만 필요합니다. cyclonedds/·python/은 Cyclone DDS가 번들되어 있어 ROS 2 없이 빌드·실행됩니다.

  • libssl-dev는 필수이고, GUI 예제는 libglfw3-dev · libgl1-mesa-dev, 센서 뷰어는 libopencv-dev가 필요합니다.

  • OpenCV는 센서 뷰어(cyclonedds_sensor_viewer, ros_sensor_viewer, sensor_viewer.py)만 사용합니다. OpenCV가 없으면 configure가 실패하므로, 뷰어 없이 빌드하려면 -DIGRIS_C_BUILD_VIEWERS=OFF를 지정합니다.

sudo apt install libssl-dev                            # 필수
sudo apt install libglfw3-dev libgl1-mesa-dev          # GUI 예제
sudo apt install libopencv-dev                         # 센서 뷰어

# OpenCV 없이 빌드할 때
cmake -B build -S . -DIGRIS_C_BUILD_VIEWERS=OFF        # cyclonedds/
colcon build --cmake-args -DIGRIS_C_BUILD_VIEWERS=OFF  # ros2/

• 예제 목록 — C++·ROS 2 예제는 domain id와 namespace를 인자로, Python 예제는 --domain-id / --namespace로 받습니다.

ros_gui_client로 실기 로봇에 접속한 화면입니다(domain 27, igris_c_IG27, ros 전송 모드). 관절 슬라이더, 연결 상태·IMU, 서비스 버튼이 한 창에 모여 있으며 cyclonedds_gui_client도 같은 구성입니다.

python/common.py는 Python 예제가 함께 쓰는 공용 모듈입니다. 2.1.0의 cyclonedds_sensor_config 예제와 MetaQuest 예제는 해당 기능이 삭제되어 배포본에서 빠졌습니다.

• URDF

  • IGRIS-C의 모든 버전용 URDF는 위 Description 저장소에서 다운로드할 수 있습니다.