본문으로 건너뛰기

ROS 2 인터페이스

PLEM 로봇은 표준 ROS 2 토픽·서비스·액션으로 제어하고 상태를 읽습니다. 이 페이지는 접속 방법, 인터페이스 목록, 클라이언트가 지킬 규칙을 다룹니다.

시작 전에​

클라이언트는 로봇 기기와 같은 ROS 2 배포판을 씁니다.

기기 UbuntuROS 2
22.04 (jammy)Humble
24.04 (noble)Jazzy

ROS_DOMAIN_ID 와 RMW 구현도 로봇과 같아야 합니다.

  • 도메인 번호는 plem 설정(~/.plem/settings.yaml 의 ros_domain_id)에서 정합니다.
  • RMW 구현은 CycloneDDS(rmw_cyclonedds_cpp) 하나로 고정입니다.
  • 이 값은 plem 이 셸에 넣어 줍니다. 셸 환경 변수를 바꿔도 plem 설정은 바뀌지 않습니다.

로봇 기기에서 접속하기​

가장 쉬운 방법은 로봇 기기에서 직접 작업하는 것입니다. 기기 콘솔이나 SSH 접속에서 새 터미널을 열면 바로 됩니다.

ros2 topic list
  • 대화형 셸에는 PLEM 환경(/opt/plem: rclpy, plem_msgs, plem_rt_msgs, plem_drive_msgs)과 DDS 설정이 이미 잡혀 있습니다.
  • 비대화형 SSH 명령이나 CI 작업에서는 bash -lc '...' 로 실행하세요. 그래야 DDS 설정까지 들어옵니다.
  • source /opt/plem/setup.bash 만 하면 rclpy·메시지 패키지는 잡히지만 DDS 설정은 빠집니다. 이때도 bash -lc '...' 를 쓰세요.
주의
DDS 값을 ~/.bashrc 에 넣지 마세요

ROS_DOMAIN_ID, CYCLONEDDS_URI, RMW_IMPLEMENTATION 을 셸 초기화 파일에서 export 하면 그 셸만 로봇과 어긋납니다.

도메인 번호를 바꿨다면 plem 을 다시 시작하고 새 터미널을 여세요. 이미 열린 터미널은 옛 값을 씁니다. 그 밖에 ros2 가 로봇을 못 볼 때는 문제 해결을 보세요.

다른 호스트에서 접속하기​

기본 설정에서 기기는 루프백(lo)으로만 DDS 통신을 합니다. 같은 기기 안에서 카메라 영상 같은 큰 데이터를 안정적으로 주고받기 위해서입니다. 그래서 다른 컴퓨터에서 ros2 topic list 를 하면 오류 없이 빈 목록이 나옵니다. 원격 접속이 안 되면 이것부터 확인하세요.

도메인 번호를 바꿔도 이 제한은 그대로입니다. 설정 파일(/usr/share/plem/cyclonedds-localhost.xml)이 모든 도메인(<Domain Id="any">)에 적용되기 때문입니다.

다른 호스트와 통신하려면 로봇과 클라이언트 양쪽에서 실제 네트워크 카드를 쓰도록 설정을 바꿉니다.

  1. 기기에서 기본 설정 파일을 복사합니다. 기기 전체에 적용하려면 /etc/plem/cyclonedds.xml, 내 계정에만 적용하려면 ~/.ros/cyclonedds.xml 로 복사합니다. 둘 다 있으면 ~/.ros/ 쪽이 먼저입니다.
    sudo install -d -m 0755 /etc/plem && sudo install -m 0644 /usr/share/plem/cyclonedds-localhost.xml /etc/plem/cyclonedds.xml
  2. 복사한 파일의 <NetworkInterface name="lo" ...> 에서 lo 를 실제 네트워크 카드 이름(예: eth0)으로 바꿉니다. 이 부분만 고치세요. 파일을 새로 쓰면 버퍼 크기 같은 튜닝값이 함께 사라집니다. 클라이언트도 같은 방법으로 맞춥니다.
  3. plem 을 다시 실행하고 새 터미널을 엽니다. 어느 설정 파일이 쓰였는지는 plem 기동 로그에 한 줄로 나옵니다.
  4. 클라이언트에서 노드 생성이 실패하면 커널 수신 버퍼가 작아서일 수 있습니다. 설정 파일은 10 MB 이상을 요구합니다(<SocketReceiveBufferSize min="10MB"/>). sysctl -w net.core.rmem_max=10485760 으로 늘리고, 재부팅 뒤에도 유지하려면 /etc/sysctl.d/ 에 넣으세요.
네트워크에 노출됩니다

루프백 제한을 풀면 같은 기기 안 대용량 전송의 안정성을 내주고 로봇을 네트워크에 노출하게 됩니다. 필요한 기간에, 믿을 수 있는 네트워크에서만 푸세요.

plem_msgs·plem_rt_msgs·plem_drive_msgs 설치​

PLEM 전용 인터페이스를 쓰려면 클라이언트에 plem_msgs, plem_rt_msgs, plem_drive_msgs 가 있어야 합니다. 로봇 기기에는 이미 있습니다. 표준 인터페이스만으로도 관절 상태를 읽고 그리퍼를 쓸 수 있습니다. 하지만 팔을 움직이려면 먼저 모드를 바꿔야 하고(모드 먼저) 그 인터페이스가 plem_msgs 에 있습니다.

등록한 Jetson 기기에서만 받을 수 있습니다

PLEM 패키지 저장소(Depot)는 비공개입니다. 담당자에게 받은 토큰으로 등록한 aarch64 Ubuntu 22.04(JetPack 6)·24.04(JetPack 7) 기기에서만 설치됩니다. x86 PC 등 다른 환경이 필요하면 담당자에게 문의하세요.

다른 Jetson 기기에 설치하는 순서입니다.

  1. 기기 배포판에 맞는 ROS 2 apt 저장소를 등록합니다(위 표). PLEM 전체 설치(install.sh)를 했다면 이미 돼 있습니다.
  2. PLEM 저장소를 등록합니다. 실행 중에 토큰을 묻고, 입력한 값은 화면과 셸 기록에 남지 않습니다. 토큰을 입력할 터미널이 필요하므로 원격으로는 ssh -t 로 접속하세요. CI 작업처럼 터미널이 없는 곳에서는 실패합니다.
    curl -fsSL https://depot.wimcorp.dev/jetson/setup.sh | sudo bash
  3. 두 패키지를 설치합니다. 이름은 plem-msgs, plem-drive 입니다. ros-humble-plem-msgs 형식이 아닙니다.
    sudo apt install plem-msgs plem-drive # /opt/plem 에 설치. source /opt/plem/setup.bash 로 씁니다

plem_rt_msgs·plem_drive_msgs 만 필요해도 plem-drive 는 드라이브 런타임과 셸 설정까지 통째로 설치됩니다.

인터페이스 목록​

인터페이스는 로봇마다 /{robot_id}/ 아래에 있습니다. robot_id 는 plem 에서 고른 로봇 프로필 이름입니다.

  • PLEM 전용 인터페이스: /{robot_id}/plem/ 아래
  • ros2_control 표준 인터페이스와 F/T 센서(ft_sensor/*): /{robot_id}/ 바로 아래

아래 표에서는 /{robot_id}/ 를 생략했습니다. 인터페이스는 기동 중에 단계별로 생기고, plem/plan_trajectory 가 가장 늦습니다. wait_for_server 로 기다리세요(로봇 스택 기동).

제어​

이름타입용도
plem/set_modeplem_msgs/action/SetMode모드 전환. 모션 전에 필수
plem/control_commandplem_rt_msgs/srv/SetControlCommand정지·복구: reset_error, protective_stop, release_brake, free_drive. 하위 모드와 브레이크만 바꾸고 컨트롤러는 전환하지 않음(정지·안전)
plem/plan_trajectoryplem_msgs/action/PlanTrajectory궤적 계획
joint_trajectory_controller/follow_joint_trajectorycontrol_msgs/action/FollowJointTrajectory궤적 실행 (표준)
gripper_action_server/gripper_commandcontrol_msgs/action/GripperCommand그리퍼 (표준, 벤더와 무관하게 같은 이름)
ft_sensor/zerostd_srvs/srv/TriggerF/T 센서 영점. 값은 센서에 저장됨(아래)

plem/plan_trajectory 의 기본값(DETERMINISTIC)은 예측 가능한 산업용 모션입니다. 충돌 회피는 motion_intent=COLLISION_AWARE 로 요청합니다. ROS 2 Humble 기기에서만 되고, 무엇을 피하고 무엇을 보장하지 않는지는 로봇 스택 기동에 있습니다.

상태​

이름타입주기·비고
joint_statessensor_msgs/msg/JointState100 Hz
joint_states_throttledsensor_msgs/msg/JointState30 Hz. 기기에 topic_tools 가 있을 때만 뜹니다. 없으면 joint_states 를 구독하세요
joint_trajectory_controller/statecontrol_msgs/msg/JointTrajectoryControllerState궤적 추종 상태(목표·실제·오차). 실행 중 모니터링용
status_broadcaster/robot_modeplem_msgs/msg/RobotMode로봇 모드, 50 Hz
status_broadcaster/safety_modeplem_msgs/msg/SafetyMode안전 상태, 50 Hz
gripper_statusplem_msgs/msg/GripperStatus그리퍼 상태 (표 아래)
ft_sensor/wrenchgeometry_msgs/msg/WrenchStampedF/T 센서 힘·토크, 100 Hz
ft_sensor/statusdiagnostic_msgs/msg/DiagnosticStatusF/T 센서 상태, 5 Hz
rt_eventsplem_rt_msgs/msg/RtEventfault·상태 전이 같은 이산 이벤트. 정지 원인을 찾을 때 봅니다
rt_diagnosticsplem_msgs/msg/RtDiagnostics제어 주기 진단, 1초 단위로 집계
rt_rawplem_rt_msgs/msg/RtRawBatch매 주기 원시 데이터, 분석용 (표 아래)
  • gripper_status: connected 가 false 면 그리퍼가 응답하지 않는 것입니다. 케이블과 툴 전원을 확인하세요. 이때 나머지 필드는 마지막으로 읽은 값입니다. effort 는 항상 0.0입니다. 드라이버가 그리퍼의 첫 응답을 받기 전에는 발행하지 않고, 그 사이에 보낸 그리퍼 명령은 실패합니다.
  • rt_raw: 여러 샘플을 묶어 BestEffort QoS 설정으로 보냅니다. 샘플마다 관절 값이 axis_count 개 들어 있습니다. 실시간 그래프는 rt_raw_relay 를 띄워 PlotJuggler 창에서 봅니다(서보 드라이브 연결하기).
예전 버전에서 녹화한 bag

이번 버전 이전에 녹화한 /rt_raw·/rt_events bag 파일은 이번 버전에서 읽을 수 없습니다. 메시지 타입의 패키지와 필드가 바뀌었기 때문입니다. 녹화한 버전에서 분석하세요.

모드 값​

RobotMode: BRAKED=0 STOPPING=1 TRAJECTORY=2 FREEDRIVE=3 ERROR=-1
SafetyMode: NORMAL=0 PROTECTIVE_STOP=1

robot_mode 를 구독한다면 다섯 값을 모두 처리하세요. 모드가 바뀌는 규칙은 정지·안전에 있습니다.

F/T 센서​

ft_sensor/* 는 로봇 프로필에 F/T 센서를 지정한 로봇에만 있습니다. 값·영점·상태와 상태별 조치는 F/T 센서에 있습니다. 여기서는 프로그램에서 쓸 때 알아야 할 것만 다룹니다.

wrench​

  • 프레임은 센서의 측정 원점인 <robot_id>_ft_sensor_frame 입니다. 단위는 N, N·m입니다.
  • 마지막 영점 기준의 센서 좌표 값입니다. 중력 보상이나 좌표 변환은 하지 않습니다.
  • 값을 믿을 수 없을 때는 6축 모두 NaN 값이 나갑니다. 직전 값이나 추정값으로 채우지 않습니다. 어떤 경우인지는 OK 가 아닌 상태들입니다.

status​

  • 어댑터가 뜨면 바로 5 Hz로 발행합니다. status 메시지가 오지 않으면 어댑터가 없거나 연결이 끊긴 것입니다.
  • message 는 운영자에게 그대로 보여 줄 문장입니다. 프로그램에서는 values 의 state 로 분기하세요. OK 가 아닌 동안 wrench 토픽에는 NaN 값이 나옵니다.
  • values 의 다른 키: utilization(정격 대비 부하, 1.0 = 정격), error_flag, overload_byte, wrapped_axes, sent_cycles, zero_seq. 값은 모두 문자열입니다. 순서에 기대지 말고 키 이름으로 찾으세요.
levelstate
OKOK
WARNSTARTING, ZEROING, OVER_RATED, OUT_OF_RANGE
ERROR그 밖의 값(NOT_RESPONDING, FROZEN, NO_RELAY)

zero_seq​

영점 명령이 센서에 전달됐을 수 있을 때마다 1씩 오르는 번호입니다. 전달을 확인하지 못한 경우도 셉니다. 스택이 기동할 때 0에서 시작합니다.

  • 영점 명령이 도는 동안(보통 1초 안, 길면 몇 초) wrench 토픽에는 NaN 값이 나오고, 명령이 끝나는 순간 번호가 오릅니다.
  • wrench(100 Hz)에는 번호가 없고 번호는 status(5 Hz)로 옵니다. 그래서 값이 돌아오고 최대 0.2초 뒤에 새 번호가 보입니다. 짧은 영점은 ZEROING status 없이 지나갈 수도 있습니다.
  • NaN 값이던 wrench 토픽이 정상 값으로 돌아오고 번호가 바뀌었으면 영점이 바뀌었을 수 있습니다. 힘 기준값과 필터를 다시 잡으세요.
  • 명령을 보내지 못했을 때도 잠깐 ZEROING 이 보일 수 있습니다. 이때 번호는 그대로입니다.
  • 토크 플러그인은 값·상태·번호를 한 주기에 함께 받습니다. 번호가 같은 유효한 값은 같은 영점 기준입니다.

ft_sensor/zero 는 로봇이 움직이는 중 등에는 거부됩니다. 거부되는 경우와 success: true 의 뜻은 F/T 센서에 있습니다.

ros2 topic echo /robot_1/ft_sensor/wrench
ros2 service call /robot_1/ft_sensor/zero std_srvs/srv/Trigger
경고
웹 클라이언트(rosbridge)에는 NaN 값이 null 로 옵니다

JSON 형식에는 NaN 값이 없어서 null 로 바뀝니다. Number(null) 은 0이므로 그대로 쓰면 무효 값이 0 N으로 보입니다. CBOR 형식으로 구독하거나(compression: 'cbor') null 을 무효 값으로 처리하세요.

다른 프레임으로 보기​

ROS 2 표준 노드 wrench_transformer_node 로 TF 기준 변환을 할 수 있습니다. 이미 설치된 force_torque_sensor_broadcaster 패키지에 들어 있습니다. 아래 예시는 robot_1_tcp 기준 값을 /robot_1/ft_sensor/robot_1_tcp/wrench 로 냅니다.

ros2 run force_torque_sensor_broadcaster wrench_transformer_node --ros-args \
-r __ns:=/robot_1/ft_sensor \
-r /robot_1/ft_sensor/fts_wrench_transformer/wrench:=/robot_1/ft_sensor/wrench \
-p target_frames:="['robot_1_tcp']"
  • 입력 토픽은 절대 이름으로 remap 합니다.
  • 축 방향과 토크 기준점(r × F)까지 옮겨 주지만 중력 보상은 하지 않습니다.
  • TF 트리가 필요하므로 로봇 스택이 떠 있을 때 실행하세요.

클라이언트 규칙​

모드 먼저​

궤적은 로봇이 TRAJECTORY 모드일 때만 받습니다. 다른 모드에서는 FollowJointTrajectory goal 요청이 거부됩니다(accepted == False).

ros2 action list 에 궤적 실행 액션이 보인다고 goal 요청이 받아지는 것은 아닙니다. 궤적 컨트롤러는 꺼진 채로 올라와 있다가 모드에 들어갈 때 켜집니다.

TRAJECTORY 진입은 반드시 plem/set_mode(TRAJECTORY) 로 하세요. plem/control_command 의 release_brake 도 같은 모드로 바꾸지만, 궤적 컨트롤러를 켜지 않아 궤적을 실행할 준비가 되지 않습니다.

권장 순서:

  1. plem/set_mode 로 TRAJECTORY 진입
  2. plem/plan_trajectory 로 계획
  3. 결과의 trajectory 를 follow_joint_trajectory 로 실행

직접 만든 궤적은 충돌 검사를 하지 않습니다​

검증된 궤적만 보내세요

plem/plan_trajectory 를 거치지 않고 직접 만들어 follow_joint_trajectory 로 보낸 궤적은 충돌이나 경로를 전혀 검사하지 않습니다. 검증된 동작에만 쓰세요. 실행할 때는 사람이 작업 영역 밖에 있고 비상 정지 버튼에 손이 닿아야 합니다.

실행 성공이 목표 도달은 아닙니다​

FollowJointTrajectory 의 SUCCEEDED 가 뜻하는 바는 로봇 모델마다 다릅니다.

모델도달 허용 오차SUCCEEDED 의 의미
Neuromeka없음time_from_start 가 지나면 성공으로 보고합니다. 목표에 도달했다는 보장이 없습니다
Huayan Elfin관절마다 끝점 0.02 rad, 경로 0.5 rad, goal_time 0.5 s허용 오차를 벗어나면 실패(abort)로 끝납니다
  • 어느 모델이든 끝난 뒤 joint_states 로 최종 위치를 따로 확인하세요.
  • 궤적에는 모든 관절을 이름과 함께 넣어야 합니다(allow_partial_joints_goal: false, 궤적 컨트롤러 기본값).
  • 서보 한계를 넘는 궤적은 보내지 마세요. 예를 들어 time_from_start 가 지나치게 짧은 궤적입니다.
  • 마지막 점의 속도가 0이 아닌 궤적도 받아들입니다(allow_nonzero_velocity_at_trajectory_end: true). 안전을 위해 마지막 점의 속도는 0으로 두세요.

정지와 복구​

원하는 것방법
제어된 정지실행 중인 goal 취소(cancel)
즉시 정지plem/control_command 의 protective_stop(브레이크 체결), 또는 plem/set_mode(BRAKED)

보호 정지와 ERROR 모드는 저절로 풀리지 않습니다. safety_mode 와 robot_mode 를 감시하고, reset_error 로 해제한 뒤 모드에 다시 들어가세요. reset_error 는 상태와 관계없이 받아들여지고, 드라이브 fault 초기화와 보호 정지 해제를 함께 요청합니다. 절차는 정지·안전과 드라이브 fault 초기화에 있습니다.

관절 순서​

joint_states 의 name 순서는 정해져 있지 않습니다(실제 예: joint0,1,2,5,3,4). 인덱스로 가정하지 말고 항상 name 으로 찾으세요. 명령을 보낼 때(joints_rad, JointTrajectory.joint_names)도 마찬가지입니다.

단위​

각도는 라디안, 거리는 미터, 회전은 쿼터니언입니다. 필드 이름에도 단위가 붙어 있습니다(예: MotionTarget.joints_rad). 도 단위 값은 rad = deg × π / 180 으로 바꿔 보내세요.

plem/set_mode 가 실패할 때​

보이는 것원인
goal 자체가 거부됨 (accepted == false, 결과 메시지 없음)이미 그 모드 · 안전 상태가 그 전환을 막음 · 다른 모드 goal 처리 중(모드 goal 요청은 하나씩 보내세요)
받아진 뒤 실패함 (결과의 message 에 사유)EtherCAT 링크 이상(로봇 전원·케이블) · Jog 레인이 제한 시간 안에 멈추지 않음 · 컨트롤러 전환 실패. 모두 같은 모습이라 robot_mode, safety_mode, rt_events 로 가립니다

메시지 구조 확인​

필드 구조는 이 문서에 옮겨 적지 않습니다. 기준은 plem_msgs·plem_rt_msgs·plem_drive_msgs 패키지 자체이니 직접 조회하세요.

ros2 interface show plem_msgs/action/SetMode
ros2 interface show plem_msgs/action/PlanTrajectory # Goal = MotionTarget target (+ 선택 start_joints_rad)
ros2 interface show plem_msgs/msg/MotionTarget # move_type, speed_scale 등 모션 목표 필드
ros2 interface show plem_rt_msgs/srv/SetControlCommand