설치형 작업공간에서 제어
VS Code에서 준비된 ROS 2 예제를 열고, 설치형 시뮬레이션에 짧은 이동 명령을 보내 봅니다.
제어할 월드 시작하기
- 설치하기를 따라 앱을 설치하고 VS Code도 설치하세요.
- WWW-POSIM을 열고 이메일 인증을 마친 계정으로 로그인한 뒤 시뮬레이터 시작을 선택하세요. Windows와 Ubuntu에서는 Docker를 먼저 실행하세요.
- 작업 공간에서 준비된 지형과 WAM-V를 고르고 ROS 2 직접 제어를 선택하세요.
- 월드를 시작하고 차량과 최신 위치 데이터가 나타날 때까지 기다리세요. 앱과 브라우저를 열어 두세요.
앱은 시뮬레이터를 실행하고, VS Code는 제어 프로그램을 작성하고 실행하는 데 사용합니다.
VS Code에서 준비된 예제 열기
앱의 VS Code에서 열기를 선택하면 작업 폴더와 ros_vehicle_command.py가 함께 열립니다. 초기 폴더는 Documents/WWW-POSIM입니다. Python 프로젝트 만들기는 기존 파일을 유지하면서 예제와 편집기 설정을 추가합니다. VS Code를 열 때 차량 예제가 없으면 이 파일도 추가합니다. 다른 폴더는 로컬 설정 → 작업 폴더에서 선택하세요. 작업 폴더 열기는 같은 폴더를 파일 관리자에서 엽니다.
VS Code에서 묻는다면 본인이 만든 프로젝트를 신뢰하고 WWW-POSIM: ROS terminal 자동 작업을 허용하세요. 허용하지 않은 경우 터미널 → 작업 실행 → WWW-POSIM: ROS terminal로 실행할 수 있습니다. 새 통합 터미널은 WWW-POSIM ROS 프로필을 사용합니다. ROS connected가 나타난 뒤 명령을 입력하세요. 예제 파일을 열기만 해서는 차량이 움직이지 않습니다.
macOS에서는 터미널과 Python 디버거가 앱에 포함된 Python 및 준비된 ROS 환경을 사용합니다. 이 프로젝트를 위해 별도 Python 가상환경을 만들 필요는 없습니다. Windows와 Ubuntu에서는 준비된 제어 컨테이너에서 명령을 실행하고 VS Code가 공유 폴더의 파일을 편집합니다.
편집과 디버깅에는 Microsoft의 Python, Python Debugger 확장을 설치하세요. Windows와 Ubuntu에서는 Dev Containers도 설치하고 Dev Containers: Reopen in Container로 컨테이너 디버깅을 사용합니다. ROS 터미널 열기는 같은 작업 폴더에서 외부 ROS 터미널을 엽니다.
ROS 2 차량 예제 실행하기
실행 중인 월드의 제어 패널에서 ROS 허용를 선택하세요. 준비된 VS Code 터미널에서 도움말을 확인하고 WAM-V에 짧은 이동 명령을 보내세요.
python ros_vehicle_command.py --help
python ros_vehicle_command.py --vehicle wamv --forward 0.3 --seconds 2
예제는 ROS 2 명령을 주기적으로 발행하고, 실행이 끝나거나 Ctrl+C를 누르면 중립 명령을 보냅니다. 이동 명령을 보내기 전에 구독자가 연결될 때까지 기다립니다. 예제의 실행 시간은 최대 30초, WAM-V 명령은 1 m/s와 0.5 rad/s, BlueROV2 추력은 모터당 5 N으로 제한됩니다.
BlueROV2는 추력 여섯 개를 모두 0으로 두고 시작하세요.
python ros_vehicle_command.py --vehicle bluerov2 --thrusters 0 0 0 0 0 0 --seconds 2
선택한 차량과 움직임을 확인한 뒤 입력을 늘리세요. 중립 명령을 보내도 관성과 파도에 의한 움직임은 남을 수 있습니다.
Python 세션 인터페이스 사용하기
같은 패키지의 Python 세션 인터페이스도 사용할 수 있습니다. 다음을 controller.py로 저장하고 준비된 터미널에서 python 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"])
프로그램은 최신 위치를 읽고 2초 동안 전진 0.3 m/s를 요청한 뒤 제어를 해제합니다. 출력된 두 위치의 차이가 정확히 일정한 거리일 필요는 없습니다. 왼쪽으로 돌려면 yaw_rate=0.1로 바꾸세요. 즉시 제어를 멈추려면 브라우저의 정지 기능을 사용하세요.
BlueROV 추력 제어하기
세션 인터페이스는 기본 조인트 순서에 따른 BlueROV2 추력 여섯 개를 N 단위로 받습니다. WAM-V는 왼쪽과 오른쪽 두 개를 사용합니다. 먼저 중립 입력을 보내세요.
from www_posim_ros import Session
with Session.local(control=True) as sim:
sim.set_thrusters([0.0] * 6, duration=1.0)
| 인터페이스 한도 | 값 |
|---|---|
| WAM-V 속도 | 전진 ±1.5 m/s, 요 ±0.5 rad/s |
| WAM-V 추력 | 모터당 ±200 N |
| BlueROV2 추력 | 모터당 ±50 N |
| 도우미 함수 실행 시간 | 0초 초과, 최대 300초 |
| 명령 감시 시간 | 유효한 갱신 없이 0.75초 경과 |
이 한도는 ros_vehicle_command.py에 설정한 더 작은 예제 한도와 다릅니다. 도우미 함수는 약 10 Hz로 명령을 반복하고 실행 후 제어를 해제합니다. 다른 스레드에서 sim.stop()을 호출하면 실행 중인 도우미를 중단할 수 있습니다. 연결이 끊어지면 제어가 끝나며, 네트워크 오류 후 명령을 자동으로 다시 시작하지 않습니다.
서버가 제어 권한 반납 확인을 지원하면, 도우미는 중립 출력과 권한 반납 확인을 받은 뒤 반환합니다. controller_busy는 다른 제어기가 권한을 사용 중이라는 뜻입니다. 해당 제어기를 중지한 뒤 새 제어기를 시작하세요.
정상적인 평가 완료나 워크스페이스의 중지 버튼은 control_lease_ended를 발생시킬 수 있습니다. 명령 감시 시간 초과나 시뮬레이터·센서 사용 불가 상태는 각각 watchdog_timeout 또는 simulation_or_sensor_unavailable 오류로 실행을 실패 처리합니다. 시뮬레이터 상태와 명령 전송 간격을 확인한 뒤 새 실행을 직접 시작하세요.
도전과제 평가 중 control_service_stalled는 서버의 네이티브 제어 콜백이 0.75초 넘게 멈췄다는 뜻입니다. 추진기를 안전 정지하고 해당 코스에는 유효한 점수를 부여하지 않습니다. 웹사이트 제출은 완료한 코스 기록을 보관하고 중단된 코스를 자동 재시도합니다. 로컬 연습에서는 시뮬레이터 상태를 확인한 뒤 실행을 다시 시작하세요.
설치형 앱 확장 불러오기
설치형 앱의 로컬 작업공간은 소유자가 승인한 world/model ZIP 확장을 불러올 수 있습니다. 호스팅 작업공간과 평가 세션에서는 확장 코드를 실행하지 않습니다.
- 작업공간의 마지막 검토 단계에서 사용자 world/model 확장 → 확장 ZIP 가져오기를 선택하세요. ZIP에는
extension.json, 진입점 SDF와 해시가 선언된 파일이 들어 있습니다. 가져오기는 코드를 실행하지 않고 파일을 검사해 보관합니다. - 선언된 파일과 SDK에서 코드, 대상 플랫폼, ZIP SHA-256과 SDK SHA-256을 확인하세요. 대상과 SDK는 실행 중인 엔진과 일치해야 합니다. 코드는 로컬 런타임의 권한으로 파일과 네트워크에 접근합니다.
- 신뢰하는 코드에만 코드 승인 후 선택을 누르고 확인한 뒤 월드를 시작하세요. 승인은 소유자와 정확한 ZIP·SDK 조합에 연결되고 선택은 새 세션에 적용됩니다. 확장 선택 해제를 눌러도 보관된 ZIP은 남습니다.
SDK를 확인할 수 없거나 대상·해시가 다르면 선택할 수 없습니다. 선택한 엔진에 맞게 빌드한 확장을 사용하고 해당 ZIP을 승인하세요. 등록된 항법 provider 진입점이 없는 일반 스크립트는 실행할 수 없습니다. 앱이 세션의 provider 프로세스를 관리하고 세션 종료 시 함께 중지합니다.
WAM-V와 BlueROV2는 활성 ROS 항법 provider 하나를 공통으로 사용합니다. 사용자 provider를 선택하면 기본 provider의 출력을 대체하며 원시 GNSS 수신기는 유지합니다. 공통 출력은 /vehicle/navigation/estimate의 nav_msgs/Odometry와 /vehicle/navigation/status의 std_msgs/String JSON입니다. 위치·자세는 navigation_map ENU, 속도는 base_link 기체 FLU 좌표를 사용합니다. 일치하는 시뮬레이션 시각, 유한한 공분산, 세션 식별자와 WGS 84 전역 원점이 필요합니다.
Autopilot 모드에서는 공통 게이트웨이가 출력을 검사한 뒤 FCU에 외부 항법으로 전달합니다. GPS 고정 상태는 원시 GNSS만 결정합니다. 보정, 전역 정합 또는 유효한 센서 데이터가 없으면 provider의 준비 상태를 false로 유지해야 합니다. 가져오기나 프로세스 실행만으로 항법이 준비되지는 않습니다. 입력 선택과 신호 손실 동작은 GNSS와 항법을 참고하세요.
SDK 업데이트
Python SDK는 업데이트를 자동으로 설치하지 않습니다. SDK 0.4.2부터는 시뮬레이션에 연결할 때 공개 안정 버전을 백그라운드에서 확인합니다. 새 SDK가 있으면 터미널에 현재 버전, 권장 버전과 업데이트 방법을 표시합니다. 확인에 실패해도 컨트롤러는 계속 실행됩니다. 성공한 확인 결과는 1시간 동안 재사용하며, 확인 요청에 WWW-POSIM 로그인 정보는 보내지 않습니다. 공식 채점 실행에서는 이 업데이트 요청을 하지 않습니다.
- 앱에서 준비한 ROS 터미널: WWW-POSIM 런처의 업데이트 확인(Check for updates)으로 앱을 업데이트하세요. 업데이트한 시뮬레이터를 시작한 뒤 해당 런처의 ROS 터미널 열기(Open ROS terminal) 또는 VS Code에서 열기(Open in VS Code)를 사용하세요. 이미 열린 터미널은 기존 환경을 유지합니다.
- 기존 Windows/Linux VS Code Dev Container: 앱을 업데이트한 뒤
.devcontainer/devcontainer.json의image를 SDK 알림에 표시된 엔진 이미지로 바꾸세요. 나머지 프로젝트 설정은 유지하세요. Dev Containers: Rebuild and Reopen in Container를 실행하세요. 이미 컨테이너에 연결했다면 Dev Containers: Rebuild Container를 사용하세요. 창을 다시 여는 것만으로는 컨테이너가 바뀌지 않습니다. 이전 SDK에 알림 기능이 없다면 업데이트한 런처에서 새 빈 폴더에 Python 프로젝트 만들기(Create Python project)를 실행하고, 생성된 컨테이너 설정의image값을 복사하세요. 자세한 방법은 VS Code 재빌드 안내를 참고하세요. - 별도로 설치한 Python 환경: 컨트롤러를 멈춘 뒤 알림에 표시된 명령을 실행하세요. 해당 환경의 Python 실행 파일과 권장 SDK의 공식 wheel을 사용하도록 안내합니다. 업데이트 후 Python을 다시 실행하세요. 앱을 업데이트해도 별도로 설치한 가상환경은 갱신되지 않습니다.
로그인하거나 월드를 실행하지 않고도 직접 확인할 수 있습니다. 앱에서 연 ROS 터미널에서는 다음 명령을 실행하세요.
python -m www_posim_ros.updates
웹사이트: Python과 VS Code 준비하기에서 만든 가상환경을 사용한다면 프로젝트 폴더에서 운영체제에 맞는 명령을 실행하세요.
Windows PowerShell
.\.venv\Scripts\python.exe -m www_posim_ros.updates
Mac / Linux
.venv/bin/python -m www_posim_ros.updates
SDK 0.4.1 이하에는 알림 기능과 위 확인 명령이 없습니다. 처음 한 번은 웹사이트: Python과 VS Code 준비하기의 SDK wheel 설치 명령에서 pip install 다음에 --upgrade를 추가하여 업데이트하세요. 알림은 업데이트가 있다는 안내이며, 설치가 완료되었다는 뜻은 아닙니다.
실행 문제 확인하기
No module named www_posim_ros: 프로젝트의 준비된 Python 인터프리터를 사용하세요.- 최신 텔레메트리가 없음: 월드가 실행 중이고 차량이 나타났는지 확인하세요. 토픽 이름이 보이는 것만으로 수신을 확인할 수는 없습니다.
- 직접 제어 모드가 필요함: ROS 2 직접 제어를 선택해 월드를 시작하세요.
controller_busy: 다른 제어 프로그램을 종료한 뒤 다시 실행하세요.- 월드나 차량을 변경함: 프로그램을 다시 시작해 현재 연결 정보를 받으세요.
- ROS 도구 실행 실패: 준비된 환경의
~/.www-posim-ros/domain-76/client.log를 확인하고, 필요하면 도구를 닫았다가 다시 여세요.
ROS 터미널과 연결, 웹 작업공간에서 제어, RViz와 Foxglove 뷰어, ROS 문제 해결도 참고하세요.