WWW-POSIM시뮬레이터 문서
문서 메뉴
WWW-POSIM / 시뮬레이터 문서

Python으로 로봇 제어하기

제어 프로그램은 로봇에게 움직이는 방법을 알려 주는 작은 프로그램입니다. 이 안내에서는 일반 Python으로 시작합니다. ROS 명령이나 ROS 라이브러리가 필요하면 앱이 실행 환경을 준비합니다.

시뮬레이션을 실행할 곳 선택하기

개인 작업 공간을 사용하세요. 공개 LIVE는 함께 관람하는 시연입니다.

웹사이트는 설치형 앱보다 그래픽 품질이 낮고, 동시에 시뮬레이션을 실행할 수 있는 인원이 제한됩니다. 자리가 모두 사용 중이면 대기열에 들어가거나 내 컴퓨터에서 연습하세요.

설치형 앱: WAM-V 월드 시작하기

  1. WWW-POSIM과 VS Code를 설치하세요.
  2. WWW-POSIM을 열고 이메일 인증을 마친 계정으로 로그인한 뒤 Start simulator를 누르세요. Windows/Linux에서는 먼저 Docker를 실행하세요.
  3. 브라우저의 작업 공간 창에서 부산의 기본 좌표를 유지하고 지도를 생성하세요.
  4. WAM-V를 선택하세요. 제어 방식에서 ROS 2 직접 제어를 선택하세요.
  5. 월드 시작을 누르세요. 로봇이 보이고 월드가 실행될 때까지 기다리세요. 앱과 브라우저를 계속 열어 두세요.

앱은 시뮬레이터를 실행합니다. VS Code는 Python 프로그램을 작성하고 실행하는 편집기입니다.

설치형 앱: VS Code에서 프로젝트 열기

  1. WWW-POSIM 앱에서 Create Python project를 누르세요.
  2. 문서 폴더에 posim-controller라는 빈 폴더를 만들고 선택하세요. 앱이 예제 프로그램과 편집기 설정을 이곳에 저장합니다.
  3. VS Code를 여세요. 파일 → 폴더 열기에서 posim-controller를 선택하세요. 방금 만든 폴더의 신뢰 여부를 묻는다면 신뢰하세요.
  4. VS Code의 확장에서 Microsoft의 Python과 Python Debugger를 설치하세요.
  5. Windows/Linux: Microsoft의 Dev Containers도 설치하세요. Ctrl+Shift+P를 누르고 Dev Containers: Reopen in Container를 선택한 뒤 준비가 끝날 때까지 기다리세요. 왼쪽 아래에 컨테이너 이름이 표시됩니다.
  6. Mac: Cmd+Shift+P를 누르고 Python: Select Interpreter를 선택하세요. 프로젝트의 README에 표시된 앱 내장 Python 경로를 선택하세요. 프로젝트에 ROS 환경 설정이 포함되어 있습니다.
  7. 터미널 → 새 터미널을 선택하세요. 터미널은 명령을 글자로 입력하는 창입니다. 아래 한 줄을 붙여 넣고 Enter를 누르세요.
python controller.py

로봇의 x, y, z 좌표가 출력됩니다. 숫자가 나오면 프로그램이 시뮬레이터에서 최근 위치를 받은 것입니다.

Mac은 앱에 포함된 Python을 사용합니다. Windows/Linux에서는 준비된 컨테이너 안에서 VS Code와 Python이 실행됩니다. 앱의 Open ROS terminal을 누르고 프로젝트 폴더를 선택해 같은 명령을 실행할 수도 있습니다.

2초 동안 앞으로 움직이기

VS Code에서 controller.py를 여세요. 내용을 아래 코드로 바꾸고 파일을 저장하세요.

from www_posim_ros import Session

with Session.local(control=True) as sim:
    topic = next(name for name, kind in sim.topics.items()
                 if kind == "nav_msgs/msg/Odometry")
    print("Before:", sim.latest(topic)["pose"]["pose"]["position"])
    sim.set_velocity(forward=0.3, yaw_rate=0.0, duration=2.0)
    print("After:", sim.latest(topic)["pose"]["pose"]["position"])

VS Code 터미널에서 실행하세요.

python controller.py

브라우저에서 WAM-V를 관찰하세요. 프로그램은 초속 0.3 m의 전진을 2초 동안 요청한 뒤 추력 명령을 멈춥니다. 관성과 파도 때문에 로봇이 계속 떠밀릴 수 있습니다. 출력된 위치 차이가 정확한 이동 거리와 일치하지 않아도 됩니다.

왼쪽으로 돌려면 yaw_rate=0.0을 yaw_rate=0.1로 바꾸세요. 양수 회전 속도는 좌회전입니다. 제어를 즉시 멈추려면 브라우저의 정지 버튼을 누르세요.

웹사이트: Python과 VS Code 준비하기

서버에서 시뮬레이션을 실행하려면 이 순서를 사용하세요.

  1. www-posim.vercel.app에 로그인하고 ROS 2 직접 제어 방식의 WAM-V 개인 월드를 만드세요. 월드 실행이 끝날 때까지 기다리세요.
  2. VS Code와 Microsoft의 Python 확장을 설치하세요.
  3. 아래에서 내 컴퓨터에 맞는 블록 하나만 따라 하세요. 터미널에 블록을 복사해 붙여 넣고 Enter를 누르세요. .venv 폴더는 이 프로젝트의 Python 패키지를 보관합니다.

Windows — PowerShell

Python 설치 관리자를 설치하세요. 시작 메뉴에서 새 PowerShell 창을 연 뒤 붙여 넣으세요.

py install 3.14
mkdir "$HOME\posim-controller"
cd "$HOME\posim-controller"
py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install https://github.com/IOES-Lab/homebrew-www-posim/releases/download/v0.5.4/www_posim_ros-0.4.0-py3-none-any.whl

Mac — 터미널

Python.org의 macOS 설치 프로그램으로 Python 3.14를 설치하세요. 응용 프로그램 → 유틸리티 → 터미널을 열고 붙여 넣으세요.

mkdir -p ~/posim-controller
cd ~/posim-controller
python3.14 -m venv .venv
.venv/bin/python -m pip install https://github.com/IOES-Lab/homebrew-www-posim/releases/download/v0.5.4/www_posim_ros-0.4.0-py3-none-any.whl

Ubuntu — 터미널

Ctrl+Alt+T를 눌러 터미널을 열고 붙여 넣으세요.

sudo apt update
sudo apt install -y python3-venv python3-pip
mkdir -p ~/posim-controller
cd ~/posim-controller
python3 -m venv .venv
.venv/bin/python -m pip install https://github.com/IOES-Lab/homebrew-www-posim/releases/download/v0.5.4/www_posim_ros-0.4.0-py3-none-any.whl

sudo가 컴퓨터 비밀번호를 물을 수 있습니다. 입력하는 동안 글자가 보이지 않는 것이 정상입니다. 비밀번호를 입력한 뒤 Enter를 누르세요.

웹사이트: VS Code에서 프로그램 실행하기

  1. VS Code에서 파일 → 폴더 열기를 선택하고 홈 폴더의 posim-controller를 여세요.
  2. 아직 설치하지 않았다면 Microsoft의 Python 확장을 설치하세요.
  3. Windows/Linux에서는 Ctrl+Shift+P, Mac에서는 Cmd+Shift+P로 명령 팔레트를 여세요. Python: Select Interpreter에서 프로젝트의 .venv를 선택하세요.
  4. controller.py 파일을 만들고 아래 코드를 붙여 넣으세요. YOU@example.com을 계정 이메일로 바꾸고 저장하세요.
from www_posim_ros import Session

with Session.remote(email="YOU@example.com", control=True) as sim:
    topic = next(name for name, kind in sim.topics.items()
                 if kind == "nav_msgs/msg/Odometry")
    print(sim.latest(topic)["pose"]["pose"]["position"])
    sim.set_velocity(forward=0.3, yaw_rate=0.0, duration=2.0)
  1. 터미널 → 새 터미널을 선택하세요. 내 컴퓨터에 맞는 명령을 실행하세요.

Windows:

.\.venv\Scripts\python.exe controller.py

Mac/Ubuntu:

.venv/bin/python controller.py
  1. Password:가 나오면 WWW-POSIM 비밀번호를 입력하고 Enter를 누르세요. 입력하는 동안 글자가 보이지 않습니다. 웹사이트에서 WAM-V가 움직이는지 확인하세요.

프로그램은 내 컴퓨터에서 실행되며 내 서버 작업 공간에 명령을 보냅니다. 패키지를 가져오기만 해서는 로그인하거나 연결하지 않습니다. with 블록에 들어갈 때 연결합니다.

잘 되지 않을 때

고급: 전체 ROS 환경, 센서와 제어 세부 사항

ROS 명령 사용하기

설치형 앱에서 Open ROS terminal을 누르고 프로젝트 폴더를 선택하세요. 터미널에 ROS connected. Telemetry and topic echo are ready.가 표시됩니다. 준비된 터미널은 센서 데이터를 ROS 프로그램에 전달하는 로컬 중계기를 공유합니다.

ros2 topic list
ros2 topic echo /model/wamv/odometry --once --field pose.pose.position
ros2 topic echo /model/wamv/imu --once

전체 ROS 프로그램은 생성된 ros_controller.py를 사용하세요. ROS의 Python 인터페이스인 rclpy를 가져와 위치·운동 정보를 구독합니다. ROS에서는 이 메시지를 odometry라고 부릅니다.

python ros_controller.py

Ctrl+C로 프로그램을 멈추세요. 추가 라이브러리는 준비된 제어 환경에 설치하세요. RViz는 선택적으로 사용하는 ROS 시각화 도구입니다. 사용하려면 같은 환경에 설치해야 합니다.

앱의 명령줄 도구 사용하기

Ubuntu에서는 www-posim 명령을 사용합니다. Mac에서는 그 자리에 /Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM을 사용하세요. Windows PowerShell에서는 설치된 WWW-POSIM.exe의 전체 경로 앞에 &를 붙여 실행하세요.

www-posim ros init ./posim-controller
www-posim ros shell --workspace ./posim-controller
www-posim ros run ./posim-controller/controller.py
www-posim ros stop

run은 ROS와 공유 중계기를 준비한 뒤 프로그램을 실행합니다. stop은 앱이 관리하는 제어 환경을 종료합니다. 설치형 시뮬레이터를 닫아도 앱이 준비한 제어 환경은 멈춥니다. 실습을 마치면 편집기의 컨테이너도 닫으세요.

BlueROV 추력 제어하기

네이티브 관절 순서에 맞춰 6개 추력을 뉴턴 단위로 지정합니다. WAM-V는 왼쪽·오른쪽 순서의 2개 값을 사용합니다. 먼저 중립 명령으로 시작하세요.

from www_posim_ros import Session

with Session.local(control=True) as sim:
    sim.set_thrusters([0.0] * 6, duration=1.0)

도우미는 초당 약 10회 명령을 보내고 지정 시간이 끝나면 제어 권한을 반납합니다. 다른 스레드에서 sim.stop()을 호출하면 실행 중인 도우미 명령을 중단합니다. 연결이 끊기면 제어가 끝나며, 통신 오류 뒤에 명령을 자동으로 재개하지 않습니다. 중립 입력을 보내도 관성과 파도는 남습니다.

기존 ROS 환경으로 웹 작업 공간에 연결하기

표준 메시지 패키지가 있는 호환 ROS 2 Lyrical 환경을 사용하세요. Ubuntu 26.04는 공식 ROS 설치 안내를 따르세요. Windows에서는 Ubuntu 26.04 WSL2에 ROS를 설치할 수 있습니다. Microsoft WSL 안내를 참고하세요.

ROS를 불러온 터미널에서 실행하세요.

python3 -m venv --system-site-packages .venv-ros
source .venv-ros/bin/activate
python -m pip install https://github.com/IOES-Lab/homebrew-www-posim/releases/download/v0.5.4/www_posim_ros-0.4.0-py3-none-any.whl
export ROS_DOMAIN_ID=76
export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST
www-posim-connect --server https://www-posim.vercel.app/api --email YOU@example.com --control

Python 설치 방식에서 요구한다면 호환되는 가상 환경을 사용하세요. 중계기를 계속 실행하고, 같은 환경과 ROS 도메인을 불러온 다른 터미널에서 제어 프로그램을 실행하세요. Mac은 앱의 환경을 불러올 수 있습니다.

eval "$(/Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM --ros-env)"

메시지와 연결 인터페이스

Session.latest()는 ROS 메시지 필드를 Python 딕셔너리로 반환합니다. 중계기가 이미지·점군의 바이너리를 base64 문자열로 보낸 경우 이 형태를 유지합니다. 최근 센서 값을 기다리며, timeout과 max_age로 대기 시간과 허용 경과 시간을 지정할 수 있습니다.

전체 중계기는 센서 필드를 표준 ROS 메시지로 변환하고 수신한 위치 정보를 이용해 로봇 추적용 로컬 좌표 변환을 만듭니다. 사용자 로봇에는 별도 메시지 정의, URDF나 TF 트리가 필요할 수 있습니다. 임의 서비스 호출이나 위치 직접 변경은 이 제어 인터페이스의 범위에 포함되지 않습니다.

토픽은 보이는데 echo가 비어 있을 때

앱의 ROS 터미널을 열고 아래 명령으로 확인하세요. 중계기, 제어 프로그램, ROS 명령 터미널은 같은 ROS 버전, ROS_DOMAIN_ID, 미들웨어(RMW_IMPLEMENTATION)를 사용해야 합니다. 미들웨어를 바꾸면 ROS 데몬을 멈추고 중계기와 제어 프로그램을 다시 실행하세요.

ros2 daemon stop
python3 -c "from rclpy.utilities import get_rmw_implementation_identifier; print(get_rmw_implementation_identifier())"
ros2 topic info /model/wamv/odometry --verbose
ros2 topic echo /model/wamv/odometry --once --qos-reliability best_effort

Reliable 발행자는 Best Effort 구독자에게도 메시지를 보낼 수 있습니다. Best Effort 발행자는 Reliable 전달을 요구하는 구독자에게 메시지를 보낼 수 없습니다. 설정을 바꾸기 전에 발행자와 구독자의 QoS를 확인하세요.

기존 Ubuntu/WSL ROS 환경에서는 CycloneDDS를 시험할 수 있습니다. 중계기 터미널과 제어 프로그램 터미널에서 각각 아래 명령을 실행한 뒤 프로그램을 시작하세요.

sudo apt install ros-lyrical-rmw-cyclonedds-cpp
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
ros2 daemon stop

Mac 네이티브 앱은 CycloneDDS를 사용합니다. 패키지의 Docker 환경은 Fast DDS를 사용합니다. 웹사이트 연결은 WebSocket으로 메시지를 전달하며, 서버와 로컬 중계기는 별도 DDS 도메인을 사용합니다. 고급 설정은 ROS 미들웨어 안내를 참고하세요.