ROS 2 인터페이스
PLEM 로봇은 표준 ROS 2 토픽·서비스·액션으로 제어하고 상태를 읽습니다. 이 페이지는 접속 방법, 인터페이스 목록, 클라이언트가 지킬 규칙을 다룹니다.
시작 전에
클라이언트는 로봇 기기와 같은 ROS 2 배포판을 씁니다.
| 기기 Ubuntu | ROS 2 |
|---|---|
| 22.04 (jammy) | Humble |
| 24.04 (noble) | Jazzy |
ROS_ 와 RMW 구현도 로봇과 같아야 합니다.
- 도메인 번호는
plem설정(~/.의plem/ settings. yaml ros_)에서 정합니다.domain_ id - RMW 구현은 CycloneDDS(
rmw_) 하나로 고정입니다.cyclonedds_ cpp - 이 값은
plem이 셸에 넣어 줍니다. 셸 환경 변수를 바꿔도plem설정은 바뀌지 않습니다.
로봇 기기에서 접속하기
가장 쉬운 방법은 로봇 기기에서 직접 작업하는 것입니다. 기기 콘솔이나 SSH 접속에서 새 터미널을 열면 바로 됩니다.
ros2 topic list
- 대화형 셸에는 PLEM 환경(
/opt/: rclpy,plem plem_,msgs plem_,rt_ msgs plem_)과 DDS 설정이 이미 잡혀 있습니다.drive_ msgs - 비대화형 SSH 명령이나 CI 작업에서는
bash -lc '...'로 실행하세요. 그래야 DDS 설정까지 들어옵니다. source /opt/만 하면 rclpy·메시지 패키지는 잡히지만 DDS 설정은 빠집니다. 이때도plem/ setup. bash bash -lc '...'를 쓰세요.
~/. bashrc 에 넣지 마세요ROS_, CYCLONEDDS_, RMW_ 을 셸 초기화 파일에서 export 하면 그 셸만 로봇과 어긋납니다.
도메인 번호를 바꿨다면 plem 을 다시 시작하고 새 터미널을 여세요. 이미 열린 터미널은 옛 값을 씁니다. 그 밖에 ros2 가 로봇을 못 볼 때는 문제 해결을 보세요.
다른 호스트에서 접속하기
기본 설정에서 기기는 루프백(lo)으로만 DDS 통신을 합니다. 같은 기기 안에서 카메라 영상 같은 큰 데이터를 안정적으로 주고받기 위해서입니다. 그래서 다른 컴퓨터에서 ros2 topic list 를 하면 오류 없이 빈 목록이 나옵니다. 원격 접속이 안 되면 이것부터 확인하세요.
도메인 번호를 바꿔도 이 제한은 그대로입니다. 설정 파일(/usr/)이 모든 도메인(<Domain Id="any">)에 적용되기 때문입니다.
다른 호스트와 통신하려면 로봇과 클라이언트 양쪽에서 실제 네트워크 카드를 쓰도록 설정을 바꿉니다.
- 기기에서 기본 설정 파일을 복사합니다. 기기 전체에 적용하려면
/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 - 복사한 파일의
<NetworkInterface name="lo" ...>에서lo를 실제 네트워크 카드 이름(예:eth0)으로 바꿉니다. 이 부분만 고치세요. 파일을 새로 쓰면 버퍼 크기 같은 튜닝값이 함께 사라집니다. 클라이언트도 같은 방법으로 맞춥니다. plem을 다시 실행하고 새 터미널을 엽니다. 어느 설정 파일이 쓰였는지는plem기동 로그에 한 줄로 나옵니다.- 클라이언트에서 노드 생성이 실패하면 커널 수신 버퍼가 작아서일 수 있습니다. 설정 파일은 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_, plem_, plem_ 가 있어야 합니다. 로봇 기기에는 이미 있습니다. 표준 인터페이스만으로도 관절 상태를 읽고 그리퍼를 쓸 수 있습니다. 하지만 팔을 움직이려면 먼저 모드를 바꿔야 하고(모드 먼저) 그 인터페이스가 plem_ 에 있습니다.
PLEM 패키지 저장소(Depot)는 비공개입니다. 담당자에게 받은 토큰으로 등록한 aarch64 Ubuntu 22.04(JetPack 6)·24.04(JetPack 7) 기기에서만 설치됩니다. x86 PC 등 다른 환경이 필요하면 담당자에게 문의하세요.
다른 Jetson 기기에 설치하는 순서입니다.
- 기기 배포판에 맞는 ROS 2 apt 저장소를 등록합니다(위 표). PLEM 전체 설치(
install.)를 했다면 이미 돼 있습니다.sh - PLEM 저장소를 등록합니다. 실행 중에 토큰을 묻고, 입력한 값은 화면과 셸 기록에 남지 않습니다. 토큰을 입력할 터미널이 필요하므로 원격으로는
ssh -t로 접속하세요. CI 작업처럼 터미널이 없는 곳에서는 실패합니다.curl -fsSL https://depot.wimcorp.dev/jetson/setup.sh | sudo bash - 두 패키지를 설치합니다. 이름은
plem-msgs,plem-drive입니다.ros-humble-plem-msgs형식이 아닙니다.sudo apt install plem-msgs plem-drive # /opt/plem 에 설치. source /opt/plem/setup.bash 로 씁니다
plem_·plem_ 만 필요해도 plem-drive 는 드라이브 런타임과 셸 설정까지 통째로 설치됩니다.
인터페이스 목록
인터페이스는 로봇마다 /{robot_ 아래에 있습니다. robot_ 는 plem 에서 고른 로봇 프로필 이름입니다.
- PLEM 전용 인터페이스:
/{robot_아래id}/ plem/ - ros2_control 표준 인터페이스와 F/T 센서(
ft_):sensor/* /{robot_바로 아래id}/
아래 표에서는 /{robot_ 를 생략했습니다. 인터페이스는 기동 중에 단계별로 생기고, plem/ 가 가장 늦습니다. wait_ 로 기다리세요(로봇 스택 기동).
제어
| 이름 | 타입 | 용도 |
|---|---|---|
plem/ | plem_ | 모드 전환. 모션 전에 필수 |
plem/ | plem_ | 정지·복구: reset_, protective_, release_, free_. 하위 모드와 브레이크만 바꾸고 컨트롤러는 전환하지 않음(정지·안전) |
plem/ | plem_ | 궤적 계획 |
joint_ | control_ | 궤적 실행 (표준) |
gripper_ | control_ | 그리퍼 (표준, 벤더와 무관하게 같은 이름) |
ft_ | std_ | F/T 센서 영점. 값은 센서에 저장됨(아래) |
plem/ 의 기본값(DETERMINISTIC)은 예측 가능한 산업용 모션입니다. 충돌 회피는 motion_ 로 요청합니다. ROS 2 Humble 기기에서만 되고, 무엇을 피하고 무엇을 보장하지 않는지는 로봇 스택 기동에 있습니다.
상태
| 이름 | 타입 | 주기·비고 |
|---|---|---|
joint_ | sensor_ | 100 Hz |
joint_ | sensor_ | 30 Hz. 기기에 topic_ 가 있을 때만 뜹니다. 없으면 joint_ 를 구독하세요 |
joint_ | control_ | 궤적 추종 상태(목표·실제·오차). 실행 중 모니터링용 |
status_ | plem_ | 로봇 모드, 50 Hz |
status_ | plem_ | 안전 상태, 50 Hz |
gripper_ | plem_ | 그리퍼 상태 (표 아래) |
ft_ | geometry_ | F/T 센서 힘·토크, 100 Hz |
ft_ | diagnostic_ | F/T 센서 상태, 5 Hz |
rt_ | plem_ | fault·상태 전이 같은 이산 이벤트. 정지 원인을 찾을 때 봅니다 |
rt_ | plem_ | 제어 주기 진단, 1초 단위로 집계 |
rt_ | plem_ | 매 주기 원시 데이터, 분석용 (표 아래) |
gripper_:status connected가 false 면 그리퍼가 응답하지 않는 것입니다. 케이블과 툴 전원을 확인하세요. 이때 나머지 필드는 마지막으로 읽은 값입니다.effort는 항상 0.0입니다. 드라이버가 그리퍼의 첫 응답을 받기 전에는 발행하지 않고, 그 사이에 보낸 그리퍼 명령은 실패합니다.rt_: 여러 샘플을 묶어 BestEffort QoS 설정으로 보냅니다. 샘플마다 관절 값이raw axis_개 들어 있습니다. 실시간 그래프는count rt_를 띄워 PlotJuggler 창에서 봅니다(서보 드라이브 연결하기).raw_ relay
이번 버전 이전에 녹화한 /rt_·/rt_ bag 파일은 이번 버전에서 읽을 수 없습니다. 메시지 타입의 패키지와 필드가 바뀌었기 때문입니다. 녹화한 버전에서 분석하세요.
모드 값
RobotMode: BRAKED=0 STOPPING=1 TRAJECTORY=2 FREEDRIVE=3 ERROR=-1
SafetyMode: NORMAL=0 PROTECTIVE_STOP=1
robot_ 를 구독한다면 다섯 값을 모두 처리하세요. 모드가 바뀌는 규칙은 정지·안전에 있습니다.
F/T 센서
ft_ 는 로봇 프로필에 F/T 센서를 지정한 로봇에만 있습니다. 값·영점·상태와 상태별 조치는 F/T 센서에 있습니다. 여기서는 프로그램에서 쓸 때 알아야 할 것만 다룹니다.
wrench
- 프레임은 센서의 측정 원점인
<robot_입니다. 단위는 N, N·m입니다.id>_ ft_ sensor_ frame - 마지막 영점 기준의 센서 좌표 값입니다. 중력 보상이나 좌표 변환은 하지 않습니다.
- 값을 믿을 수 없을 때는 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
level | state |
|---|---|
| OK | OK |
| WARN | STARTING, ZEROING, OVER_, OUT_ |
| ERROR | 그 밖의 값(NOT_, FROZEN, NO_) |
zero_seq
영점 명령이 센서에 전달됐을 수 있을 때마다 1씩 오르는 번호입니다. 전달을 확인하지 못한 경우도 셉니다. 스택이 기동할 때 0에서 시작합니다.
- 영점 명령이 도는 동안(보통 1초 안, 길면 몇 초) wrench 토픽에는 NaN 값이 나오고, 명령이 끝나는 순간 번호가 오릅니다.
- wrench(100 Hz)에는 번호가 없고 번호는 status(5 Hz)로 옵니다. 그래서 값이 돌아오고 최대 0.2초 뒤에 새 번호가 보입니다. 짧은 영점은
ZEROINGstatus 없이 지나갈 수도 있습니다. - NaN 값이던 wrench 토픽이 정상 값으로 돌아오고 번호가 바뀌었으면 영점이 바뀌었을 수 있습니다. 힘 기준값과 필터를 다시 잡으세요.
- 명령을 보내지 못했을 때도 잠깐
ZEROING이 보일 수 있습니다. 이때 번호는 그대로입니다. - 토크 플러그인은 값·상태·번호를 한 주기에 함께 받습니다. 번호가 같은 유효한 값은 같은 영점 기준입니다.
ft_ 는 로봇이 움직이는 중 등에는 거부됩니다. 거부되는 경우와 success: true 의 뜻은 F/T 센서에 있습니다.
ros2 topic echo /robot_1/ft_sensor/wrench
ros2 service call /robot_1/ft_sensor/zero std_srvs/srv/Trigger
null 로 옵니다JSON 형식에는 NaN 값이 없어서 null 로 바뀝니다. Number(null) 은 0이므로 그대로 쓰면 무효 값이 0 N으로 보입니다. CBOR 형식으로 구독하거나(compression: 'cbor') null 을 무효 값으로 처리하세요.
다른 프레임으로 보기
ROS 2 표준 노드 wrench_ 로 TF 기준 변환을 할 수 있습니다. 이미 설치된 force_ 패키지에 들어 있습니다. 아래 예시는 robot_1_ 기준 값을 /robot_1/ 로 냅니다.
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/ 로 하세요. plem/ 의 release_ 도 같은 모드로 바꾸지만, 궤적 컨트롤러를 켜지 않아 궤적을 실행할 준비가 되지 않습니다.
권장 순서:
plem/로 TRAJECTORY 진입set_ mode plem/로 계획plan_ trajectory - 결과의
trajectory를follow_로 실행joint_ trajectory
직접 만든 궤적은 충돌 검사를 하지 않습니다
plem/ 를 거치지 않고 직접 만들어 follow_ 로 보낸 궤적은 충돌이나 경로를 전혀 검사하지 않습니다. 검증된 동작에만 쓰세요. 실행할 때는 사람이 작업 영역 밖에 있고 비상 정지 버튼에 손이 닿아야 합니다.
실행 성공이 목표 도달은 아닙니다
FollowJointTrajectory 의 SUCCEEDED 가 뜻하는 바는 로봇 모델마다 다릅니다.
| 모델 | 도달 허용 오차 | SUCCEEDED 의 의미 |
|---|---|---|
| Neuromeka | 없음 | time_ 가 지나면 성공으로 보고합니다. 목표에 도달했다는 보장이 없습니다 |
| Huayan Elfin | 관절마다 끝점 0.02 rad, 경로 0.5 rad, goal_ 0.5 s | 허용 오차를 벗어나면 실패(abort)로 끝납니다 |
- 어느 모델이든 끝난 뒤
joint_로 최종 위치를 따로 확인하세요.states - 궤적에는 모든 관절을 이름과 함께 넣어야 합니다(
allow_, 궤적 컨트롤러 기본값).partial_ joints_ goal: false - 서보 한계를 넘는 궤적은 보내지 마세요. 예를 들어
time_가 지나치게 짧은 궤적입니다.from_ start - 마지막 점의 속도가 0이 아닌 궤적도 받아들입니다(
allow_). 안전을 위해 마지막 점의 속도는 0으로 두세요.nonzero_ velocity_ at_ trajectory_ end: true
정지와 복구
| 원하는 것 | 방법 |
|---|---|
| 제어된 정지 | 실행 중인 goal 취소(cancel) |
| 즉시 정지 | plem/ 의 protective_(브레이크 체결), 또는 plem/ |
보호 정지와 ERROR 모드는 저절로 풀리지 않습니다. safety_ 와 robot_ 를 감시하고, reset_ 로 해제한 뒤 모드에 다시 들어가세요. reset_ 는 상태와 관계없이 받아들여지고, 드라이브 fault 초기화와 보호 정지 해제를 함께 요청합니다. 절차는 정지·안전과 드라이브 fault 초기화에 있습니다.
관절 순서
joint_ 의 name 순서는 정해져 있지 않습니다(실제 예: joint0,1,2,5,3,4). 인덱스로 가정하지 말고 항상 name 으로 찾으세요. 명령을 보낼 때(joints_, JointTrajectory.)도 마찬가지입니다.
단위
각도는 라디안, 거리는 미터, 회전은 쿼터니언입니다. 필드 이름에도 단위가 붙어 있습니다(예: MotionTarget.). 도 단위 값은 rad = deg × π / 180 으로 바꿔 보내세요.
plem/ set_ mode 가 실패할 때
| 보이는 것 | 원인 |
|---|---|
goal 자체가 거부됨 (accepted == false, 결과 메시지 없음) | 이미 그 모드 · 안전 상태가 그 전환을 막음 · 다른 모드 goal 처리 중(모드 goal 요청은 하나씩 보내세요) |
받아진 뒤 실패함 (결과의 message 에 사유) | EtherCAT 링크 이상(로봇 전원·케이블) · Jog 레인이 제한 시간 안에 멈추지 않음 · 컨트롤러 전환 실패. 모두 같은 모습이라 robot_, safety_, rt_ 로 가립니다 |
메시지 구조 확인
필드 구조는 이 문서에 옮겨 적지 않습니다. 기준은 plem_·plem_·plem_ 패키지 자체이니 직접 조회하세요.
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