전체 과정 P2 Python 으로 움직이고 읽기 · 약 200분 · 중급

CH04pymycobot MyAGVPlus 로 이동 제어

pymycobot 의 MyAGVPlus 클래스로 전원 · 이동 · 정지를 다루고, 시간 기반 이동 프로그램과 안전한 정지 구조를 시뮬레이터에서 먼저 검증합니다.

선수 챕터: CH01 CH02 CH03
Python Playground

학습 목표#

  • MyAGVPlus 객체가 두 개의 직렬 링크(모터 컨트롤러 921600 baud · ESP32 115200 baud)를 연다는 것을 설명하고, 버전 확인 → power_on() 순서로 연결을 점검할 수 있습니다.
  • move_forward · move_backward · move_left_lateral · move_right_lateral · turn_left · turn_right · stop 의 속도 범위(0.01~1.60 m/s, 0.01~7.27 rad/s) 와 반환값(1 / −1) 을 알고, 반환값을 확인하는 코드를 쓸 수 있습니다.
  • move → sleep(t) → stop 패턴으로 거리를 만들고, 가속 · 감속 · 미끄럼 때문에 오차가 쌓이는 과정을 시뮬레이터 궤적으로 설명할 수 있습니다.
  • try / finally 와 속도 제한 래퍼로 예외 · 중단 시에도 반드시 멈추는 제어 구조를 만들고, 시뮬에서 검증한 코드를 실물 절차에 맞게 옮길 수 있습니다.
이 차시를 공부하는 방법

이 페이지에는 브라우저에서 바로 동작하는 시뮬레이터 4개가 있습니다. 버튼을 누르기 전에 결과를 먼저 예측해 적고, 조작해서 확인하세요. Playground 실습 코드는 pymycobot 대신 **같은 메서드 이름 · 같은 반환값을 흉내 내는 교육용 클래스 SimAGVPlus** 를 코드 맨 위에 넣어 실행합니다. 실물로 옮길 때는 import 줄과 sleep 출처만 바꿉니다.

이 차시의 물리값은 교육용 가정입니다

메서드 이름 · 속도 범위 · 반환값 · power_on() 약 6초는 공식 문서(myagvPlus_docs 6.1.2 API) 기준입니다. 반면 시뮬레이터의 가속 한계 1.0 m/s² · 감속 한계 2.0 m/s² · 측면 전달률 0.93 · 회전 전달률 0.96 · 측면 이동 시 1 m 당 0.05 rad 회전은 원리를 보여 주기 위한 교육용 값입니다. 실물의 가감속 · 미끄럼 크기는 확인 필요이며, 바닥 · 적재 · 배터리 상태에 따라 달라집니다.

1교시 · 개발 환경과 연결: MyAGVPlus 객체 만들기#

설치와 import#

myAGV Plus 는 Ubuntu 22.04 와 Python 이 설치된 상태로 출고됩니다. 로봇 안의 터미널에서 pymycobot 을 최신으로 맞춥니다.

bash
pip install --upgrade pymycobot
python -c "from pymycobot import MyAGVPlus; print('import OK')"

공식 문서에는 두 가지 import 형태가 모두 나옵니다. 둘 다 같은 클래스를 가리킵니다.

python실물 전용
from pymycobot import MyAGVPlus            # API 문서의 형태
# from pymycobot.myagvplus import MyAGVPlus  # 이동 · LED 예제 문서의 형태

agv = MyAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                esp32_port="/dev/myagvplus_esp32", esp32_baud=115200, debug=True)

생성자 인수는 공식 예제를 그대로 따랐습니다. 첫 인수는 모터 컨트롤러 포트이고, 포트 경로는 장치 설정에 따라 다를 수 있습니다(LED 예제 문서는 ESP32 를 /dev/ttyACM0 으로 씁니다). 생성자의 기본값 · 생략 가능 여부는 문서에 적혀 있지 않으므로 네 값을 모두 적는 습관을 들입니다.

두 개의 직렬 링크#

링크포트 (공식 예제)속도하는 일
모터 컨트롤러/dev/myagvplus_controller921600 baud전원 릴레이 · 모터 활성 · 속도 명령과 응답
ESP32 보조 보드/dev/myagvplus_esp32115200 baud50 ms 마다 상태 자동 보고 (배터리 · 자이로 등), LED · IO (ch05)
  • baud 는 "1초에 보내는 신호 수" 입니다. 921600 baud 는 115200 baud 의 8배라 짧은 제어 명령을 지연 없이 주고받기에 알맞습니다.
  • ESP32 는 묻지 않아도 50 ms(1초에 20번) 마다 상태를 보내옵니다. 프로그램은 가장 최근 값을 읽기만 하면 됩니다.
  • 두 값 중 하나라도 틀리면 증상이 다르게 나타납니다. 시뮬레이터 1 에서 직접 틀려 봅니다.

펌웨어 확인과 power_on()#

연결 직후 가장 먼저 할 일은 로봇이 대답하는지 확인하는 것입니다.

메서드반환의미
get_system_version()float펌웨어 버전
get_modify_version()float펌웨어 수정 버전
power_on()1 성공 / 0 실패릴레이 켜기 → 모든 모터 활성 → 속도 제어 모드 초기화, 약 6초의 안전 대기 포함
power_off()1 / 0모터 비활성 → 릴레이 끄기
is_power_on()1 켜짐 / 0 꺼짐전원 상태 확인

power_on() 은 안에서 약 6초를 기다린 뒤에 돌아옵니다. 그동안 다음 줄은 실행되지 않습니다. 이것이 1교시 시뮬레이터의 핵심 관찰 거리입니다.

Playground 시뮬 shim#

같은 제어 코드, 다른 대상: 시뮬 shim 의 구조 제어 코드 (같음) agv.move_forward(0.3) sleep(2) ; agv.stop() 시뮬 shim 같은 메서드 이름 · 반환값 pymycobot 직렬 포트로 바이트 전송 브라우저 시뮬레이터 가상 시계 · 가상 로봇 myAGV Plus 실물 바퀴가 실제로 돎 바뀌는 것은 import 줄(과 sleep 출처)뿐입니다. 그래서 시뮬에서 검증한 순서 · 반환값 처리 · 정지 구조가 그대로 실물로 옮겨집니다.
제어 코드는 그대로 두고, 그 아래에서 명령을 받는 대상만 바꿉니다.

shim 은 진짜 라이브러리와 메서드 이름 · 인수 · 반환값이 같은 "대역" 입니다. shim 이 Playground 에 설치되어 있으면 from pymycobot import MyAGVPlus 한 줄이 브라우저에서는 시뮬레이터 로봇에, 로봇 컴퓨터에서는 실물에 연결됩니다.

이 강좌의 Playground 상태

이 강좌의 Playground 에는 아직 pymycobot shim 이 설치되어 있지 않습니다(import pymycobot 은 ModuleNotFoundError). 그래서 이 차시의 실습 코드는 같은 구조의 **SimAGVPlus 클래스를 코드 맨 위에 직접 넣어** 실행합니다. 차이는 두 가지뿐입니다.

  • agv = SimAGVPlus(...) ↔ agv = MyAGVPlus(...)
  • sleep = agv.sleep (시뮬 시간을 진행, 실제로 기다리지 않음) ↔ from time import sleep

시뮬레이터 1 · 연결 · 전원 콘솔#

버튼 하나가 Python 한 줄입니다. 왼쪽 프로그램과 오른쪽 보드 사이로 파란 점(명령 · 응답) 과 주황 점(ESP32 상태 보고) 이 오갑니다. 아래 띠는 1차원 트랙 위의 로봇입니다.

연결 · 전원 콘솔 · 한 줄씩 실행해 보기
해 볼 것 (먼저 예측을 적고 확인하세요)
  1. 객체를 만들기 전에 power_on() 을 누릅니다. 어떤 오류가 나오나요? 이어서 객체를 만들고 주황 점이 1초에 몇 번 오는지 "상태 보고 n 개" 숫자로 세어 봅니다.
  2. 스크립트를 실행합니다. 예측: move_forward(0.3) 은 t = 몇 초에 실행될까요? 로그의 t 값으로 확인합니다.
  3. power_on 을 기다리지 않음을 켜고 스크립트를 다시 실행합니다. 같은 코드인데 로봇이 왜 움직이지 않나요? move_forward 의 반환값을 봅니다.
  4. 모터 baud 를 115200 으로 바꾸고 처음부터 해 봅니다. 객체는 만들어지나요? 버전과 power_on() 은 무엇을 돌려주나요?
  5. ESP32 포트를 없는 포트로 바꾸고 객체를 만듭니다. 4번과 실패하는 시점이 어떻게 다른가요?
관찰 포인트
  • power_on() 은 블로킹(blocking) 입니다. 약 6초 동안 프로그램이 그 줄에 머물러 있으므로, 바로 다음 줄의 move_forward 는 t ≈ 6 s 에 실행되고 정상적으로 움직입니다. "power_on 직후 move" 가 위험한 경우는 기다리지 않도록 바꾼 코드(스레드 · 비동기 호출)뿐입니다.
  • 모터가 활성화되기 전에 보낸 명령은 이 시뮬에서 −1 로 거부됩니다(교육용 가정 — 실물의 정확한 처리는 확인 필요). 반환값을 출력해 보지 않았다면 "코드는 돌았는데 로봇이 안 움직인다" 로만 보입니다.
  • 없는 포트는 객체를 만드는 순간 예외가 납니다. 반면 baud 불일치는 포트는 열리므로 객체가 만들어지고, 첫 통신에서야 None · 0 같은 이상한 값으로 드러납니다. 그래서 연결 직후 버전부터 확인합니다.
  • ESP32 상태 보고는 50 ms 주기라 1초에 약 20개가 쌓입니다. 배터리가 19.0 V 미만이면 백그라운드 감시가 동작을 잠가 이동 명령이 −1 이 됩니다(자세한 상태 진단은 ch05).

실습 과제 1#

실습 과제 1-1 · 객체 생성 → 버전 → power_on → 첫 이동

SimAGVPlus 로 공식 연결 순서를 재현합니다. TODO 를 채워 버전 두 개를 출력하고, power_on() 의 반환값과 그 순간의 시뮬 시간 agv.t 를 출력한 뒤, 0.3 m/s 로 2초 전진합니다. 예측 먼저: 마지막 줄에 출력될 시뮬 시간과 x 위치는 얼마일까요?

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

# ---------------- 여기부터 제어 코드 (실물에서도 같음) ----------------
agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                 esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
sleep = agv.sleep          # 실물: from time import sleep

# TODO 1: get_system_version() 과 get_modify_version() 을 출력
print("system version:", None)
print("modify version:", None)

# TODO 2: power_on() 을 호출하고 반환값과 agv.t 를 출력
ret = 0
print("power_on ->", ret, " t = %.2f s" % agv.t)

# TODO 3: move_forward(0.3) 의 반환값을 출력하고 2초 기다린 뒤 stop(), 1초 더 기다림
print("t = %.2f s, pose =" % agv.t, agv.pose())
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

# ---------------- 여기부터 제어 코드 (실물에서도 같음) ----------------
agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                 esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
sleep = agv.sleep          # 실물: from time import sleep

print("system version:", agv.get_system_version())
print("modify version:", agv.get_modify_version())

ret = agv.power_on()
print("power_on ->", ret, " t = %.2f s" % agv.t)

print("move_forward ->", agv.move_forward(0.3))
sleep(2)
agv.stop()
sleep(1)
print("t = %.2f s, pose =" % agv.t, agv.pose())

실행 결과: power_on -> 1 t = 6.00 s, 마지막 줄은 t = 9.00 s, pose = (0.578, 0.0, 0.0) 입니다. 2초 × 0.3 m/s = 0.6 m 를 기대했지만 0.578 m 입니다. 모자란 2.2 cm 는 3교시에서 계산합니다. baudrate=115200 으로 바꿔 실행하면 버전이 None, power_on -> 0 이 되고 move_forward 는 −1 로 거부됩니다.

실습 과제 1-2 · 연결 점검 함수 만들기

연결 직후 "대답하는가 → 전원이 켜지는가" 를 한 번에 확인하는 check_connection(agv) 를 만듭니다. 문제가 있으면 어느 단계에서 실패했는지 문자열로 돌려줍니다. 두 객체(정상 baud · 잘못된 baud)로 시험합니다.

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim (연결 점검용 축약판): 버전 · 전원만 흉내 냄"""
    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200):
        self.ok = (baudrate == 921600)
        self.t, self.powered = 0.0, False
    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None
    def power_on(self):
        if not self.ok: return 0
        self.t += 6.0
        self.powered = True
        return 1

def check_connection(agv):
    # TODO 1: get_system_version() 이 None 이면 "버전 응답 없음 - baud 확인" 을 돌려줌
    # TODO 2: power_on() 이 1 이 아니면 "power_on 실패" 를 돌려줌
    # TODO 3: 모두 통과하면 "OK (펌웨어 x.x / x.x)" 형식으로 돌려줌
    return "아직 구현하지 않음"

good = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                  esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
bad = SimAGVPlus("/dev/myagvplus_controller", baudrate=115200,
                 esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
print("정상 baud :", check_connection(good))
print("잘못된 baud:", check_connection(bad))
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim (연결 점검용 축약판): 버전 · 전원만 흉내 냄"""
    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200):
        self.ok = (baudrate == 921600)
        self.t, self.powered = 0.0, False
    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None
    def power_on(self):
        if not self.ok: return 0
        self.t += 6.0
        self.powered = True
        return 1

def check_connection(agv):
    sv = agv.get_system_version()
    if sv is None:
        return "버전 응답 없음 - baud 확인"
    mv = agv.get_modify_version()
    if agv.power_on() != 1:
        return "power_on 실패"
    return "OK (펌웨어 %s / %s)" % (sv, mv)

good = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                  esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
bad = SimAGVPlus("/dev/myagvplus_controller", baudrate=115200,
                 esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
print("정상 baud :", check_connection(good))
print("잘못된 baud:", check_connection(bad))

실행 결과: 정상 baud : OK (펌웨어 1.0 / 2.0), 잘못된 baud: 버전 응답 없음 - baud 확인. 버전 확인을 power_on 보다 먼저 두면 6초를 기다리기 전에 배선 · 설정 문제를 걸러낼 수 있습니다. 실물에서 받는 버전 숫자는 펌웨어마다 다릅니다.

확인 문제 1-1

다음 코드를 실물에서 실행했습니다. move_forward(0.5) 가 로봇에 전달되는 시점은?

python
agv = MyAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                esp32_port="/dev/myagvplus_esp32", esp32_baud=115200)
agv.power_on()
agv.move_forward(0.5)
  1. 객체를 만든 직후 (power_on 과 거의 동시)
  2. power_on() 이 돌아온 뒤, 즉 약 6초 뒤
  3. ESP32 가 다음 상태 보고를 보낸 50 ms 뒤
  4. move_forward 는 power_on 이 있으면 무시된다
정답 보기② — power_on() 은 릴레이 · 모터 활성 · 속도 모드 설정과 약 6초의 안전 대기를 마친 뒤에 돌아오는 블로킹 호출입니다. 시뮬레이터 1 스크립트에서 move_forward 가 t ≈ 6 s 에 찍히는 것으로 확인했습니다. ① 은 power_on 을 스레드로 호출해 기다리지 않게 바꾼 경우입니다.
확인 문제 1-2

시뮬레이터 1 에서 모터 baud 만 115200 으로 잘못 적었습니다. 관찰한 증상은?

  1. 객체를 만드는 줄에서 SerialException 이 난다
  2. 객체는 만들어지지만 버전이 None, power_on() 이 0 을 돌려준다
  3. 모든 것이 정상이고 속도만 8배 느려진다
  4. ESP32 상태 보고가 끊긴다
정답 보기② — 포트 자체는 존재하므로 열리고, 통신 속도가 맞지 않아 첫 대화에서 응답을 해석하지 못합니다. ① 은 **없는 포트**를 지정했을 때의 증상, ④ 는 ESP32 포트를 잘못 지정했을 때입니다. baud 가 다르면 "느려지는" 것이 아니라 **알아들을 수 없게** 됩니다(③ 틀림).

2교시 · 이동 API: 전후 · 측면 · 회전 · 정지#

일곱 개의 이동 메서드#

메서드인수 범위움직임 (로봇 기준)반환
move_forward(speed)0.01 ~ 1.60 m/s앞 (+x)1 / −1
move_backward(speed)0.01 ~ 1.60 m/s뒤 (−x)1 / −1
move_left_lateral(speed)0.01 ~ 1.60 m/s왼쪽 옆 (+y) — 메카넘 휠 전용1 / −1
move_right_lateral(speed)0.01 ~ 1.60 m/s오른쪽 옆 (−y)1 / −1
turn_left(angular_speed)0.01 ~ 7.27 rad/s제자리 반시계 회전 (+ω)1 / −1
turn_right(angular_speed)0.01 ~ 7.27 rad/s제자리 시계 회전 (−ω)1 / −1
stop()없음속도 0 명령1 / −1
  • 인수는 크기만 받습니다. 방향은 메서드 이름이 정하므로 move_forward(-0.3) 처럼 음수를 넣지 않습니다(범위 밖이라 차단됨).
  • ch03 의 (vx, vy, ω) 로 쓰면 move_left_lateral(0.3) = (0, 0.3, 0), turn_right(1.0) = (0, 0, −1.0) 입니다. 네 바퀴 속도로 바꾸는 계산은 컨트롤러가 합니다.
  • 공식 예제는 move_forward(0.5) → time.sleep(3) → turn_left(0.3) 처럼, 명령을 한 번 보내고 다음 명령이나 stop() 까지 기다리는 방식으로 씁니다. 명령이 일정 시간 뒤 스스로 멈추는지(시간 제한)는 문서에 없으므로 확인 필요이며, 이 강좌는 "보낸 명령은 바뀔 때까지 유지된다" 고 보고 안전 구조를 짭니다.

반환값 규칙: 1 성공, −1 실패 또는 차단#

공식 문서의 규칙은 짧습니다. 1 = 성공, −1 = 실패 또는 차단(intercepted). −1 이 나오는 경우는 다음과 같습니다.

원인로그에 보이는 것 (문서 기준)해결
속도 범위 밖 (예: 2.0, 0.005)경고 출력 후 명령 차단범위로 자르는 래퍼 사용 (4교시)
배터리 두 개 모두 19.0 V 미만BACKGROUND VOLTAGE DETECTED! → 동작 잠금충전 (ch05)
모터 걸림 · 과부하STALL DETECTED! → 동작 잠금장애물 제거, 모터 오류 해제 (ch05)
반환값을 보지 않는 코드의 함정

명령이 차단되면 로봇은 새 명령을 받지 않은 것입니다. 그 전에 보낸 명령이 아직 유지되고 있다면 로봇은 이전 속도로 계속 움직입니다(이 강좌의 가정 — 실물 확인 필요). "정지하려고 아주 작은 속도 0.005 를 보냈다" 같은 코드는 −1 을 받고도 그대로 진행해 버립니다. 멈출 때는 언제나 stop() 을 씁니다.

시뮬레이터 2 · 연습장#

빈 연습장(한 칸 0.5 m)입니다. 명령 · 값 · 시간을 고르고 ▶ 실행을 누르면 명령(값) → sleep(시간) → stop() 이 실행됩니다. 실행할 때마다 궤적이 다른 색으로 겹쳐지고, 아래 표에 반환값과 이동 거리가 쌓입니다. 오른쪽 그래프는 마지막 실행의 명령 속도(점선) 와 실제 속도(실선) 입니다.

연습장 · 같은 명령, 다른 값
값 바로 넣기:
#명령반환값실제 이동값 × 시간메모
해 볼 것 (먼저 예측을 적고 확인하세요)
  1. 기본값 move_left_lateral(0.3) + sleep(2) 를 실행하기 전에 로봇이 어느 방향으로 몇 cm 갈지 적습니다. 실행 후 표의 "실제 이동" 과 "값 × 시간" 을 비교합니다.
  2. 명령을 move_forward 로 바꾸고 값을 0.3 · 0.5 · 1.0 으로 바꿔 각각 2초씩 실행합니다. 값 × 시간과의 차이(m)는 속도가 커질수록 어떻게 변하나요? 오른쪽 그래프의 실선이 점선을 따라잡는 데 걸리는 시간을 봅니다.
  3. 값 2.0 과 0.005 를 넣어 봅니다. 반환값은? 로봇은 움직였나요?
  4. 직전 명령 move_forward(0.2) 가 동작 중을 켜고 값 2.0 으로 move_left_lateral 을 실행합니다. 로봇은 어디로 가나요? 이어서 끝에 stop() 호출까지 끄면?
  5. turn_left 를 7.27 과 8.0 으로 1초씩 실행합니다. 7.27 rad/s 로 1초면 몇 바퀴일까요?
관찰 포인트
  • 해 볼 것 1 은 0.6 m 가 아니라 약 0.54 m 입니다. 출발할 때 속도가 0 에서 천천히 올라가고(가속), 측면 이동은 롤러로 힘을 전하므로 전진보다 조금 덜 갑니다(ch03 4교시). 가감속 · 미끄럼 모델을 끄면 정확히 0.600 m 가 됩니다.
  • 전진 2초에서 차이는 0.3 m/s 일 때 2.3 cm, 1.0 m/s 일 때 25 cm 입니다. 차이는 속도의 제곱에 비례합니다(3교시 공식).
  • 범위 밖 값은 반환값 −1 이고 새 명령이 들어가지 않습니다. 직전 명령이 살아 있으면 로봇은 원래 하던 전진을 계속 합니다. 표의 반환값 칸을 보지 않으면 "왼쪽으로 가라고 했는데 앞으로 갔다" 는 이상한 증상으로만 보입니다.
  • stop() 을 빼면 sleep 이 끝난 뒤에도 로봇이 계속 갑니다. 프로그램의 "시간" 은 로봇을 멈추지 않습니다. 멈추는 것은 stop 명령뿐입니다.
  • 7.27 rad/s × 1 s = 7.27 rad ≈ 1.16 바퀴(416°). 8.0 은 범위 밖이라 −1 입니다.

실습 과제 2#

실습 과제 2-1 · 측면 이동 위치 예측 → 확인

move_left_lateral(0.3) 를 2초 실행한 뒤의 위치를 이상적인 모델(ideal=True) 과 교육용 실제 모델 두 가지로 확인합니다. TODO 를 채우고, 실행 전에 두 결과를 예측해 주석에 적으세요.

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

# 예측 (실행 전에 적기)
#   ideal=True  : x = ?, y = ?, 방향 = ?
#   ideal=False : y 는 0.6 보다 (크다 / 작다)?

for ideal in (True, False):
    agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                     esp32_port="/dev/myagvplus_esp32", esp32_baud=115200, ideal=ideal)
    sleep = agv.sleep
    agv.power_on()
    # TODO: move_left_lateral(0.3) 의 반환값을 ret 에 받고, 2초 뒤 stop(), 0.5초 더 기다림
    ret = None
    print("ideal=%s  ret=%s  pose=%s" % (ideal, ret, agv.pose()))
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

for ideal in (True, False):
    agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                     esp32_port="/dev/myagvplus_esp32", esp32_baud=115200, ideal=ideal)
    sleep = agv.sleep
    agv.power_on()
    ret = agv.move_left_lateral(0.3)
    sleep(2)
    agv.stop()
    sleep(0.5)
    print("ideal=%s  ret=%s  pose=%s" % (ideal, ret, agv.pose()))

실행 결과: ideal=True ret=1 pose=(0.0, 0.6, 0.0), ideal=False ret=1 pose=(-0.007, 0.537, 1.5). 로봇 기준 "왼쪽" 은 처음 방향이 +x 이므로 지도의 +y 입니다. 실제 모델에서는 가속 손실(−2.25 cm)과 측면 전달률 0.93 때문에 y 가 0.537 m 로 줄고, 측면 이동 중 1.5° 반시계로 돌면서 x 가 조금 뒤로 밀렸습니다.

실습 과제 2-2 · 반환값 검사 래퍼

범위 밖 값을 섞은 명령 목록을 실행하면서 반환값을 출력합니다. 이어서 반환값이 −1 이면 예외를 일으켜 즉시 멈추는 checked(ret, what) 함수를 완성합니다.

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim (반환값 실습용 축약판): 이동 명령의 범위 검사 · 반환값만 흉내 냄"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27
    def __init__(self, *args, **kw):
        self.cmd, self.powered = (0.0, 0.0, 0.0), True
    def _send(self, vec, s, lo, hi):
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = vec
        return 1
    def move_forward(self, s):      return self._send((s, 0, 0), s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s): return self._send((0, s, 0), s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):         return self._send((0, 0, w), w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = (0.0, 0.0, 0.0)
        return 1

agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600)

tests = [("move_forward", 0.5), ("move_forward", 2.0), ("move_left_lateral", 0.005),
         ("turn_left", 7.27), ("turn_left", 8.0), ("move_forward", 1.6)]
for name, val in tests:
    ret = getattr(agv, name)(val)
    print("%-18s %6.3f -> ret %2d, 로봇이 따르는 명령 (vx, vy, w) = %s" % (name, val, ret, agv.cmd))

def checked(ret, what):
    # TODO: ret 이 1 이 아니면 RuntimeError(what + " 실패 (ret=" + str(ret) + ")") 를 일으킴
    return ret

agv.stop()
try:
    checked(agv.move_forward(0.4), "move_forward(0.4)")
    checked(agv.move_left_lateral(2.0), "move_left_lateral(2.0)")
    print("여기까지 오면 안 됩니다")
except RuntimeError as e:
    print("멈춤:", e)
finally:
    agv.stop()
    print("stop 후 명령:", agv.cmd)
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim (반환값 실습용 축약판): 이동 명령의 범위 검사 · 반환값만 흉내 냄"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27
    def __init__(self, *args, **kw):
        self.cmd, self.powered = (0.0, 0.0, 0.0), True
    def _send(self, vec, s, lo, hi):
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = vec
        return 1
    def move_forward(self, s):      return self._send((s, 0, 0), s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s): return self._send((0, s, 0), s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):         return self._send((0, 0, w), w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = (0.0, 0.0, 0.0)
        return 1

agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600)

tests = [("move_forward", 0.5), ("move_forward", 2.0), ("move_left_lateral", 0.005),
         ("turn_left", 7.27), ("turn_left", 8.0), ("move_forward", 1.6)]
for name, val in tests:
    ret = getattr(agv, name)(val)
    print("%-18s %6.3f -> ret %2d, 로봇이 따르는 명령 (vx, vy, w) = %s" % (name, val, ret, agv.cmd))

def checked(ret, what):
    if ret != 1:
        raise RuntimeError(what + " 실패 (ret=" + str(ret) + ")")
    return ret

agv.stop()
try:
    checked(agv.move_forward(0.4), "move_forward(0.4)")
    checked(agv.move_left_lateral(2.0), "move_left_lateral(2.0)")
    print("여기까지 오면 안 됩니다")
except RuntimeError as e:
    print("멈춤:", e)
finally:
    agv.stop()
    print("stop 후 명령:", agv.cmd)

표를 읽는 법: move_forward 2.0 은 −1 인데 로봇이 따르는 명령은 직전의 (0.5, 0, 0) 그대로입니다. turn_left 8.0 뒤에도 직전 회전 7.27 이 남습니다. 경계값 1.6 · 7.27 은 범위 안이라 1 입니다. checked 를 쓰면 move_left_lateral(2.0) 에서 RuntimeError 가 나고, finally 의 stop() 이 명령을 (0, 0, 0) 으로 되돌립니다. 이 구조는 4교시에서 완성합니다.

확인 문제 2-1

시뮬레이터 2 에서 직전 명령 move_forward(0.2) 가 동작 중인 상태로 move_left_lateral(2.0) 을 보내고 2초 뒤 stop() 했습니다. 관찰한 결과는?

  1. 1.60 m/s 로 잘려서 왼쪽으로 3.2 m 간다
  2. 반환값 −1, 로봇은 2초 동안 앞으로 계속 가다가 stop 에서 멈춘다
  3. 반환값 −1, 로봇은 그 자리에 즉시 멈춘다
  4. 반환값 1, 왼쪽으로 4 m 가다가 벽에 닿는다
정답 보기② — 범위 밖 명령은 경고 후 **차단**되므로 잘라서 실행하지 않습니다(① 틀림). 차단은 "새 명령이 없음" 이지 "정지" 가 아니므로(③ 틀림), 직전의 0.2 m/s 전진이 계속됩니다. 이 강좌는 이전 명령이 유지된다고 가정합니다 — 실물에서 저속으로 확인해 보세요.
확인 문제 2-2

시뮬레이터 2 에서 move_forward 를 2초 실행했을 때, "값 × 시간" 과 "실제 이동" 의 차이가 가장 큰 것은? (가감속 · 미끄럼 모델 켬)

  1. 0.3 m/s
  2. 0.5 m/s
  3. 1.0 m/s
  4. 모두 같다 — 시간이 같으니까
정답 보기③ — 차이는 v²/(2·a가속) − v²/(2·a감속) 로 속도의 제곱에 비례합니다. 0.3 m/s 는 약 2.3 cm, 0.5 m/s 는 6.3 cm, 1.0 m/s 는 25 cm 가 모자랍니다. 그래프에서 실선이 점선을 따라잡는 데 걸리는 시간이 길수록 손실 넓이가 커집니다.
확인 문제 2-3

"로봇을 천천히 세우려고" 다음 코드를 썼습니다. 무슨 일이 생길까요?

python
agv.move_forward(0.5)
time.sleep(2)
agv.move_forward(0.005)   # 거의 0 으로 감속
time.sleep(1)
  1. 0.005 m/s 로 느려져 사실상 멈춘다
  2. 0.01 m/s 로 잘려 아주 느리게 간다
  3. −1 이 돌아오고 로봇은 0.5 m/s 로 계속 간다
  4. 예외가 발생해 프로그램이 즉시 끝난다
정답 보기③ — 0.005 는 최소 0.01 보다 작아 차단됩니다. 반환값을 보지 않으면 오류 메시지 하나 없이 로봇은 0.5 m/s 로 1초 더 갑니다(50 cm). pymycobot 은 범위 밖 값에서 예외가 아니라 경고 + −1 을 돌려주므로(④ 틀림), 멈출 때는 반드시 `stop()` 을 씁니다.

3교시 · 시간 기반 이동 프로그램과 누적 오차#

거리 = 속도 × 시간, 그리고 가감속#

센서 없이 원하는 거리를 가는 가장 쉬운 방법은 시간을 쓰는 것입니다.

python실물 전용
def forward_for(agv, distance, speed=0.3):
    agv.move_forward(speed)
    time.sleep(distance / speed)     # 1 m / 0.3 m/s = 3.33 s
    agv.stop()
    time.sleep(0.5)                  # 완전히 멈출 때까지 기다림

이 식은 로봇이 명령 순간 바로 목표 속도가 되고 stop 순간 바로 0 이 될 때만 맞습니다. 실제 로봇은 질량이 있어 속도가 경사를 그리며 바뀝니다.

move(v) - sleep(t) - stop() 의 실제 속도 (교육용 모델) 시간 속도 명령한 속도 v (점선 넓이 = v x t) 가속 손실 -v²/(2·a가속) 감속 미끄럼 +v²/(2·a감속) move stop 실제 이동 거리 = 파란 넓이 가속이 감속보다 느리면 빨강 > 초록 → 매번 조금씩 짧게 갑니다
명령은 사각형, 실제 속도는 사다리꼴입니다. 이동 거리는 실선 아래 넓이입니다.

이 차시의 교육용 모델(가속 한계 a가속 = 1.0 m/s², 감속 한계 a감속 = 2.0 m/s²)로 계산하면:

text
실제 거리 = v × t  −  v² / (2 × a가속)  +  v² / (2 × a감속)
          = v × t  −  v² / 4                       (교육용 값 대입)
예) 1 m 를 0.3 m/s 로:  1 − 0.09/4 = 0.9775 m   (2.25 cm 부족)
    1 m 를 1.0 m/s 로:  1 − 1.00/4 = 0.75 m     (25 cm 부족)
  • 가속이 감속보다 느리면(출발은 부드럽게, 정지는 단단하게) 매번 조금씩 짧게 갑니다.
  • 오차는 속도의 제곱에 비례합니다. 시간 기반 이동은 느릴수록 정확합니다.
  • 측면 이동은 여기에 측면 전달률(0.93)이, 회전은 회전 전달률(0.96)이 더 곱해집니다(ch03 4교시의 미끄럼).

전방향 이동 vs 회전 후 직진#

메카넘 로봇은 같은 정사각형을 두 가지로 그릴 수 있습니다.

방식명령 순서 (한 바퀴)로봇 방향
회전 방식전진 1 m → 좌회전 90° → (×4)변마다 90° 씩 돔
측면 이동 방식전진 1 m → 왼쪽 1 m → 후진 1 m → 오른쪽 1 m처음 방향 그대로

회전 방식은 일반 차량도 할 수 있는 방법이고, 측면 이동 방식은 전방향 로봇만 할 수 있습니다. 어느 쪽이 오차가 작을까요? 시뮬레이터 3 에서 확인하기 전에 예측을 적어 두세요. 힌트: 회전에서 생긴 1° 오차는 그다음 1 m 를 갈 때 옆으로 몇 cm 의 차이를 만들까요? (1 m × sin 1° ≈ 1.7 cm)

시뮬레이터 3 · 선반 통로#

창고 지도(한 칸 0.5 m)입니다. 왼쪽은 선반 사이 통로, 오른쪽은 연습 구역입니다. 프로그램을 고르고 ▶ 실행을 누르면 명령 → sleep(거리 / 속도) → stop() → sleep(0.5) 로 만든 시간 기반 경로를 반복 횟수만큼 돌고, 바퀴마다 다른 색으로 궤적을 겹쳐 그립니다. 점선은 오차가 없을 때의 경로입니다.

선반 통로 · 시간 기반 경로의 누적 오차
바퀴끝 위치 오차방향 오차선반 접촉메모
해 볼 것 (예측 → 확인)
  1. 1 m 정사각형 · 회전 방식을 3바퀴 실행합니다. 바퀴마다 끝 위치 오차가 어떻게 커지나요? 표의 "직전 바퀴보다 +" 칸을 봅니다.
  2. 같은 조건으로 측면 이동 방식을 실행합니다. 실행 전에 어느 쪽 오차가 작을지 적어 두었나요? 방향 오차 칸도 비교합니다.
  3. 가감속만 켜고 미끄럼을 끄면 두 방식의 오차는 각각 얼마인가요? 반대로 미끄럼만 켜면? 오차의 주된 원인이 무엇인지 가려냅니다.
  4. ㄷ 자 (측면 이동) 으로 선반 A → B → A 를 5바퀴 돕니다. 몇 바퀴째에 선반 접촉이 생기나요? 직선 속도를 0.6 으로 올리면?
  5. ㄷ 자 (회전 방식) 을 3바퀴 돌려 보고, 같은 경로라도 방식에 따라 오차가 얼마나 다른지 비교합니다.
관찰 포인트
  • 회전 방식 3바퀴: 끝 위치 오차 약 65 cm, 방향 약 −54°. 측면 이동 방식 3바퀴: 약 18 cm, +16° 입니다. 같은 정사각형인데 3배 이상 차이가 납니다.
  • 회전 방식의 오차는 대부분 회전 미끄럼에서 나옵니다. 90° 를 명령해도 약 86° 만 돌고, 이 각도 오차가 다음 변 1 m 에 지렛대처럼 곱해져 위치 오차가 됩니다. 각도 오차는 사라지지 않고 바퀴마다 더해집니다.
  • 측면 이동 방식은 전진 · 후진, 왼쪽 · 오른쪽의 짧아짐이 서로 상쇄되어 위치 오차가 작습니다. 남는 것은 측면 이동 중 생기는 작은 회전(1 m 당 약 3°)입니다.
  • 가감속만 있을 때는 두 방식 모두 오차가 거의 없습니다. 모든 변이 같은 비율로 짧아져 도형이 조금 작아질 뿐 닫히기 때문입니다. 방향을 틀어지게 만드는 오차가 가장 위험합니다.
  • ㄷ 자 왕복(0.3 m/s)은 측면 이동 방식이 한 바퀴에 약 23 cm 씩 어긋나 2바퀴째부터 선반에 닿고, 회전 방식은 한 바퀴에 약 −16° 씩 돌아 첫 바퀴부터 닿습니다. 경로가 길수록, 회전이 많을수록 빨리 무너집니다.
  • 오차는 바퀴가 늘수록 커지고, 시간 기반 프로그램은 그 사실을 알 방법이 없습니다. 그래서 로봇이 자기 위치를 재는 센서가 필요합니다.

왜 센서 피드백이 필요할까#

시간 기반 이동은 "명령한 대로 갔을 것" 이라고 믿고 다음 명령을 보내는 방식입니다(개루프, open-loop). 시뮬레이터 3 에서 본 것처럼 작은 오차가 쌓이면 몇 바퀴 만에 통로 폭을 넘어섭니다.

  • 바퀴 회전 · 자이로로 "실제로 얼마나 움직였는지" 재기 → 오도메트리와 센서 융합 (ch06)
  • 주변 벽 · 선반을 보고 "지금 어디 있는지" 알아내기 → LiDAR 와 지도 (ch07)
  • 재어 본 값과 목표의 차이로 명령을 고치는 방식을 폐루프(closed-loop) 제어라 부릅니다. Part 3 에서 시작합니다.

실습 과제 3#

실습 과제 3-1 · 1 m 정사각형 3바퀴: 회전 방식 vs 측면 이동 방식

두 방식의 정사각형 함수를 만들고 3바퀴 뒤 출발점에서의 오차를 비교합니다. 실행 전 예측: 어느 쪽 오차가 작을까요? 이유는?

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

V, W = 0.3, 0.5          # 직선 속도 (m/s), 회전 속도 (rad/s)

def go(agv, method, amount, speed):
    """method(speed) -> sleep(amount / speed) -> stop -> 0.5 s 대기"""
    getattr(agv, method)(speed)
    agv.sleep(amount / speed)
    agv.stop()
    agv.sleep(0.5)

def square_rotate(agv):
    # TODO 1: 전진 1 m 후 좌회전 90도(= pi/2 rad) 를 4번 반복
    pass

def square_lateral(agv):
    # TODO 2: 전진 1 m -> 왼쪽 1 m -> 후진 1 m -> 오른쪽 1 m
    pass

def error_after(square, laps=3, ideal=False):
    agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600, ideal=ideal)
    agv.power_on()
    for _ in range(laps):
        square(agv)
    dist = math.hypot(agv.x, agv.y) * 100
    head = (math.degrees(agv.th) + 180) % 360 - 180
    return dist, head

for name, sq in (("회전 방식", square_rotate), ("측면 이동 방식", square_lateral)):
    d, h = error_after(sq)
    print("%-10s 3바퀴 후 위치 오차 %5.1f cm, 방향 오차 %+6.1f deg" % (name, d, h))
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

V, W = 0.3, 0.5          # 직선 속도 (m/s), 회전 속도 (rad/s)

def go(agv, method, amount, speed):
    """method(speed) -> sleep(amount / speed) -> stop -> 0.5 s 대기"""
    getattr(agv, method)(speed)
    agv.sleep(amount / speed)
    agv.stop()
    agv.sleep(0.5)

def square_rotate(agv):
    for _ in range(4):
        go(agv, "move_forward", 1.0, V)
        go(agv, "turn_left", math.pi / 2, W)

def square_lateral(agv):
    go(agv, "move_forward", 1.0, V)
    go(agv, "move_left_lateral", 1.0, V)
    go(agv, "move_backward", 1.0, V)
    go(agv, "move_right_lateral", 1.0, V)

def error_after(square, laps=3, ideal=False):
    agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600, ideal=ideal)
    agv.power_on()
    for _ in range(laps):
        square(agv)
    dist = math.hypot(agv.x, agv.y) * 100
    head = (math.degrees(agv.th) + 180) % 360 - 180
    return dist, head

for name, sq in (("회전 방식", square_rotate), ("측면 이동 방식", square_lateral)):
    d, h = error_after(sq)
    print("%-10s 3바퀴 후 위치 오차 %5.1f cm, 방향 오차 %+6.1f deg" % (name, d, h))

실행 결과: 회전 방식 65.3 cm, −54.0°, 측면 이동 방식 17.9 cm, +15.6°. 시뮬레이터 3 의 표와 같은 값입니다. error_after(sq, ideal=True) 로 바꾸면 두 방식 모두 1 cm 안쪽으로 닫힙니다. 즉 오차의 원인은 코드가 아니라 로봇과 바닥의 물리이며, 시간 기반 프로그램은 그것을 고칠 수 없습니다.

실습 과제 3-2 · 거리 공식 검증과 시간 보정

속도별로 "1 m 가려고 sleep(1 / v)" 했을 때의 실제 거리를 시뮬로 재고, 공식 v·t − v²/(2·a가속) + v²/(2·a감속) 과 비교합니다. 이어서 손실만큼 sleep 을 늘린 보정 시간으로 다시 재 봅니다.

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim (직선 전용 축약판): 가속 1.0 m/s², 감속 2.0 m/s²"""
    def __init__(self, acc=1.0, dec=2.0):
        self.x, self.v, self.cmd, self.acc, self.dec = 0.0, 0.0, 0.0, acc, dec
    def move_forward(self, s):
        self.cmd = s
        return 1
    def stop(self):
        self.cmd = 0.0
        return 1
    def sleep(self, sec, dt=0.001):
        for _ in range(int(round(sec / dt))):
            lim = (self.acc if self.cmd > self.v else self.dec) * dt
            self.v += max(-lim, min(lim, self.cmd - self.v))
            self.x += self.v * dt

A_ACC, A_DEC = 1.0, 2.0
D = 1.0
for v in (0.2, 0.3, 0.5, 1.0):
    agv = SimAGVPlus(A_ACC, A_DEC)
    t = D / v
    agv.move_forward(v); agv.sleep(t); agv.stop(); agv.sleep(1.0)
    # TODO 1: 공식으로 예상 거리 계산
    formula = 0.0
    # TODO 2: 손실 (D - formula) 만큼 더 가도록 늘린 보정 시간 t2 = t + (D - formula) / v
    t2 = t
    agv2 = SimAGVPlus(A_ACC, A_DEC)
    agv2.move_forward(v); agv2.sleep(t2); agv2.stop(); agv2.sleep(1.0)
    print("v=%.1f  sleep %.3f s -> %.4f m (공식 %.4f) | 보정 sleep %.3f s -> %.4f m"
          % (v, t, agv.x, formula, t2, agv2.x))
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim (직선 전용 축약판): 가속 1.0 m/s², 감속 2.0 m/s²"""
    def __init__(self, acc=1.0, dec=2.0):
        self.x, self.v, self.cmd, self.acc, self.dec = 0.0, 0.0, 0.0, acc, dec
    def move_forward(self, s):
        self.cmd = s
        return 1
    def stop(self):
        self.cmd = 0.0
        return 1
    def sleep(self, sec, dt=0.001):
        for _ in range(int(round(sec / dt))):
            lim = (self.acc if self.cmd > self.v else self.dec) * dt
            self.v += max(-lim, min(lim, self.cmd - self.v))
            self.x += self.v * dt

A_ACC, A_DEC = 1.0, 2.0
D = 1.0
for v in (0.2, 0.3, 0.5, 1.0):
    agv = SimAGVPlus(A_ACC, A_DEC)
    t = D / v
    agv.move_forward(v); agv.sleep(t); agv.stop(); agv.sleep(1.0)
    formula = v * t - v * v / (2 * A_ACC) + v * v / (2 * A_DEC)
    t2 = t + (D - formula) / v
    agv2 = SimAGVPlus(A_ACC, A_DEC)
    agv2.move_forward(v); agv2.sleep(t2); agv2.stop(); agv2.sleep(1.0)
    print("v=%.1f  sleep %.3f s -> %.4f m (공식 %.4f) | 보정 sleep %.3f s -> %.4f m"
          % (v, t, agv.x, formula, t2, agv2.x))

실행 결과: 보정 전 0.99 / 0.9775 / 0.9375 / 0.75 m 로 공식과 같고, 보정 후에는 모두 1.000 m 가 됩니다. 보정이 맞는 것은 가감속 값을 정확히 알 때뿐입니다. 실물의 가감속 한계는 확인 필요이고 적재 · 배터리에 따라 달라지므로, 이런 보정은 오차를 줄일 뿐 없애지는 못합니다. 그래서 다음 Part 에서 센서로 잽니다.

확인 문제 3-1

시뮬레이터 3 에서 1 m 정사각형을 3바퀴 돌았을 때 회전 방식의 오차가 측면 이동 방식보다 훨씬 큰 가장 큰 이유는?

  1. 회전 방식이 명령 수가 더 많아 통신이 느려서
  2. 회전에서 생긴 각도 오차가 다음 직진 거리에 곱해져 위치 오차로 커지고, 바퀴마다 더해지므로
  3. 회전 방식은 속도가 범위를 벗어나 일부 명령이 차단되므로
  4. 측면 이동은 미끄럼이 전혀 없으므로
정답 보기② — 90° 명령에 약 86° 만 돌면, 그 뒤 1 m 직진은 옆으로 약 7 cm 벗어난 방향으로 갑니다. 각도 오차는 저절로 사라지지 않고 계속 쌓입니다. 측면 이동도 미끄럼은 있지만(④ 틀림) 앞뒤 · 좌우 짧아짐이 서로 상쇄되어 위치 오차가 작습니다.
확인 문제 3-2

시뮬레이터 3 에서 미끄럼을 끄고 가감속만 켠 채 1 m 정사각형(측면 이동 방식)을 돌렸습니다. 궤적은 어떻게 보였나요?

  1. 바퀴마다 크게 회전하며 나선을 그린다
  2. 이상 경로(점선)보다 약간 작은 정사각형이 거의 제자리로 닫힌다
  3. 정사각형이 점점 커진다
  4. 첫 변에서 선반에 부딪힌다
정답 보기② — 가감속 손실은 모든 변에서 같은 양(0.3 m/s 에서 2.25 cm)이라 마주 보는 변끼리 상쇄되고, 방향은 변하지 않습니다. 도형이 약간 작아질 뿐 닫힙니다. 오차를 "쌓이게" 만드는 것은 방향을 바꾸는 오차입니다.
확인 문제 3-3

시간 기반으로 1 m 를 가는 프로그램의 정확도를 높이는 방법으로 가장 효과가 큰 것은? (교육용 모델 기준)

  1. 속도를 1.0 m/s 로 올려 빨리 끝낸다
  2. 속도를 0.2 m/s 로 낮춘다
  3. stop() 뒤 sleep(0.5) 를 지운다
  4. move_forward 를 두 번 연달아 보낸다
정답 보기② — 가감속 오차는 v² 에 비례하므로 0.2 m/s 에서 1 cm, 1.0 m/s 에서 25 cm 입니다. ③ 은 아직 감속 중인 로봇에 다음 명령을 보내 오히려 오차를 섞고, ④ 는 같은 명령을 다시 보낼 뿐 효과가 없습니다.

4교시 · 안전한 제어 구조: 정지 보장과 실물 이식#

try / finally: 어떤 길로 끝나도 stop()#

try / finally: 어떤 길로 끝나도 stop() 을 지나가게 만들기 power_on() try: move_forward(safe(v)) sleep(t) ... 경로 실행 (여기서 예외 · 정지 버튼 가능) 정상 종료 예외 발생 KeyboardInterrupt (정지 버튼) finally: agv.stop() agv.power_off() 세 길 모두 반드시 지나감 finally 가 없으면 예외가 난 순간 프로그램만 끝나고, 마지막으로 보낸 속도 명령은 로봇에 남아 있을 수 있습니다.
프로그램이 끝나는 길은 세 가지입니다. 정상 종료 · 예외 · 사용자 중단(Ctrl+C, Playground 정지 버튼). finally 는 셋 모두에서 실행됩니다.
python실물 전용
agv.power_on()
try:
    agv.move_forward(0.5)
    time.sleep(3)
    agv.turn_left(0.3)       # 여기서 오타 · 예외가 나도
    time.sleep(2)
finally:
    agv.stop()               # 반드시 실행
    agv.power_off()
  • Ctrl+C 는 Python 안에서 KeyboardInterrupt 예외가 됩니다. finally 는 이 예외에도 실행됩니다.
  • except Exception: 으로는 KeyboardInterrupt 를 잡지 못합니다(BaseException 계열). 정지 보장에는 finally 를 씁니다.
  • 프로그램이 죽어도 로봇의 마지막 명령은 로봇에 남아 있을 수 있습니다. Python 이 종료되면서 자동으로 stop 을 보내 준다는 보장은 문서에 없습니다(확인 필요).

속도 제한 래퍼#

사용자 입력 · 계산 결과를 그대로 넣지 않고 안전 최고 속도로 자르는(clamp) 함수를 거칩니다.

python실물 전용
SAFE_MAX = 0.5      # 실내 · 사람 주변 안전 최고 속도 (m/s) - 현장 규칙에 맞춰 정함

def safe(v):
    return max(0.01, min(SAFE_MAX, abs(v)))
입력 vsafe(v)그냥 보냈을 때
1.20.51.2 m/s 로 실행 (범위 안이라 통과)
2.00.5−1, 차단 (이전 명령 유지)
0.0050.01−1, 차단
−0.30.3−1, 차단

safe() 는 2교시의 "범위 밖 → 차단" 문제와, 범위 안이지만 위험하게 빠른 1.2 m/s 문제를 한 번에 막습니다. 멈추려는 의도라면 safe() 가 아니라 stop() 을 씁니다.

시뮬레이터 4 · 정지 보장 비교#

공식 예제 흐름(power_on → LED 빨강 → 전진 3초 → 좌회전 0.3 rad/s 2초 → stop → power_off)을 세 가지 코드 구조로 실행합니다. 실행 중에 ■ 정지 버튼을 누르면 그 순간 KeyboardInterrupt 가 발생합니다. 오른쪽 코드에서 지금 실행 중인 줄이 강조됩니다. 로봇 앞 3 m 에는 보관 랙(벽)이 있습니다.

정지 보장 비교 · 같은 동작, 다른 구조
해 볼 것 (예측 → 확인)
  1. A 로 그냥 실행합니다(정상 종료). 로봇은 어디서 멈추나요? 공식 예제 흐름이 맞게 동작하는지 봅니다.
  2. A 로 실행하고 전진 중(time.sleep(3) 줄)에 ■ 정지 버튼을 누릅니다. 예측: 프로그램이 끝나면 로봇도 멈출까요? 결과를 봅니다.
  3. 같은 일을 B 로 합니다. 강조된 줄이 어디로 점프하나요? 로봇은 몇 cm 안에 멈추나요?
  4. turn_left 줄에 오타를 켜고 A 와 B 를 차례로 실행합니다(정지 버튼은 누르지 않음). 오타는 몇 초에 드러나나요? 그동안 로봇은 무엇을 하고 있었나요?
  5. 요청 속도를 1.2 와 2.0 으로 바꿔 A · B · C 를 실행합니다. 각각 랙까지 남은 거리와 반환값을 비교합니다.
관찰 포인트
  • A 에서 정지 버튼을 누르면 프로그램만 끝나고 로봇은 마지막 명령(0.5 m/s 전진)을 계속 따릅니다. 이 시뮬에서는 보관 랙에 부딪힙니다. "Ctrl+C 를 눌렀는데 로봇이 안 선다" 는 실물에서 가장 흔한 사고 직전 상황입니다.
  • B 는 예외가 난 줄에서 finally: 로 점프해 stop() · power_off() 를 실행합니다. 감속 2.0 m/s² 로 0.5 m/s 에서 약 0.25 s, 약 6 cm 안에 섭니다.
  • 오타(AttributeError)는 그 줄에 도착해서야 드러납니다. A 는 3초 전진 뒤 오타에서 죽고, 로봇은 계속 전진합니다. 문법 오류와 달리 이름 오타는 실행 전에 잡히지 않으므로, 실물 전에 시뮬에서 끝까지 한 번 돌려 보는 것이 중요합니다.
  • v = 1.2 는 범위 안이라 A · B 모두 그대로 실행되어 3초 동안 약 2.9 m 를 달리고, 감속 거리까지 더해 랙에 부딪힙니다. v = 2.0 은 −1 로 차단되어 로봇이 전진하지 않는데, A · B 는 그 사실을 모른 채 회전으로 넘어갑니다. C 는 두 경우 모두 0.5 m/s 로 잘라 계획한 1.5 m 만 갑니다.

실물 실행 절차: 시뮬 → 바퀴 띄우기 → 바닥 저속 → 목표 속도#

시뮬에서 검증한 코드도 실물에서는 단계를 밟아 속도를 올립니다.

단계설정확인할 것
0. 시뮬Playground 에서 끝까지 실행, 정지 버튼 시험모든 줄 실행 · finally 동작 · 반환값
1. 바퀴 띄우기차체 밑에 받침대를 받쳐 바퀴가 바닥에 닿지 않게, SAFE_MAX = 0.1명령마다 네 바퀴 회전 방향이 ch03 표와 맞는지, Ctrl+C 에 바퀴가 서는지
2. 바닥 저속빈 공간 3 m × 3 m 이상, SAFE_MAX = 0.2실제 이동 방향 · 거리, 정지 거리
3. 목표 속도계획한 속도 (실내 0.5 이하 권장)경로 · 오차, 보조자 위치

실습 과제 4#

실습 과제 4-1 · 정지 버튼을 눌렀을 때: 멈추지 않는 코드 vs 멈추는 코드

시뮬 shim 의 interrupt_at 으로 "t = 8.0 s 에 정지 버튼을 누른 것" 을 흉내 냅니다(power_on 6초 + 전진 2초 지점). run_unsafe 는 그대로 두고, run_safe 에 safe() 와 try / finally 를 넣어 프로그램이 끝난 3초 뒤 로봇이 멈춰 있게 만드세요.

python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

SAFE_MAX = 0.5

def safe(v):
    # TODO 1: v 의 크기를 0.01 ~ SAFE_MAX 로 자름
    return v

def run_unsafe(agv, v):
    sleep = agv.sleep
    agv.power_on()
    agv.move_forward(v)
    sleep(3)
    agv.turn_left(0.3)
    sleep(2)
    agv.stop()
    agv.power_off()

def run_safe(agv, v):
    sleep = agv.sleep
    agv.power_on()
    # TODO 2: 아래 동작을 try 안에 넣고, finally 에서 stop() 과 power_off() 실행
    # TODO 3: move_forward 에는 safe(v) 를 넣음
    agv.move_forward(v)
    sleep(3)
    agv.turn_left(0.3)
    sleep(2)
    agv.stop()
    agv.power_off()

for name, prog in (("unsafe", run_unsafe), ("safe", run_safe)):
    for v in (0.5, 1.2):
        agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600)
        agv.interrupt_at = 8.0                  # t = 8 s 에 정지 버튼
        try:
            prog(agv, v)
        except KeyboardInterrupt:
            pass
        x_end = agv.x
        agv.sleep(3.0)                          # 프로그램이 끝난 뒤 3초 동안의 로봇
        print("%-6s v=%.1f  중단 시 x=%.2f m -> 3초 뒤 x=%.2f m, 명령 속도 %.2f m/s"
              % (name, v, x_end, agv.x, agv.cmd[0]))
풀이 코드 보기
python시뮬 실행 가능
import math

class SimAGVPlus:
    """교육용 시뮬 shim: pymycobot MyAGVPlus 와 같은 메서드 이름 · 반환값 (물리값은 교육용 가정)"""
    V_MIN, V_MAX, W_MIN, W_MAX = 0.01, 1.60, 0.01, 7.27

    def __init__(self, port, baudrate=921600, esp32_port=None, esp32_baud=115200, debug=False, ideal=False):
        self.ok = (baudrate == 921600)
        self.x = self.y = self.th = 0.0             # 지도 좌표 (m, m, rad)
        self.v = [0.0, 0.0, 0.0]                    # 실제 속도 (vx, vy, w) - 로봇 기준
        self.cmd = [0.0, 0.0, 0.0]                  # 마지막으로 받아들인 명령
        self.t, self.powered, self.locked = 0.0, False, False
        self.k = (1.0, 1.0, 1.0) if ideal else (1.0, 0.93, 0.96)    # 전진 · 측면 · 회전 전달률
        self.acc = (1e9, 1e9) if ideal else (1.0, 4.0)              # 가속 한계 (m/s², rad/s²)
        self.dec = (1e9, 1e9) if ideal else (2.0, 8.0)              # 감속 한계
        self.drift = 0.0 if ideal else 0.05                         # 측면 1 m 당 반시계 회전 (rad)
        self.interrupt_at = None                                    # 이 시각에 정지 버튼을 누른 것처럼

    def get_system_version(self): return 1.0 if self.ok else None
    def get_modify_version(self): return 2.0 if self.ok else None

    def power_on(self):
        if not self.ok: return 0
        self.sleep(6.0)                             # 릴레이 - 모터 활성 - 속도 모드 (약 6초)
        self.powered = True
        return 1

    def power_off(self):
        self.cmd, self.powered = [0.0, 0.0, 0.0], False
        return 1

    def _send(self, vx, vy, w, s, lo, hi):
        if not self.powered or self.locked:
            print("  [shim] 전원 꺼짐 또는 잠금 상태 - 명령 차단"); return -1
        if not lo <= s <= hi:
            print("  [shim] 경고: %.3f 는 범위 %.2f~%.2f 밖 - 명령 차단" % (s, lo, hi)); return -1
        self.cmd = [vx, vy, w]
        return 1

    def move_forward(self, s):       return self._send(s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_backward(self, s):      return self._send(-s, 0, 0, s, self.V_MIN, self.V_MAX)
    def move_left_lateral(self, s):  return self._send(0, s, 0, s, self.V_MIN, self.V_MAX)
    def move_right_lateral(self, s): return self._send(0, -s, 0, s, self.V_MIN, self.V_MAX)
    def turn_left(self, w):          return self._send(0, 0, w, w, self.W_MIN, self.W_MAX)
    def turn_right(self, w):         return self._send(0, 0, -w, w, self.W_MIN, self.W_MAX)
    def stop(self):
        self.cmd = [0.0, 0.0, 0.0]
        return 1

    def sleep(self, sec, dt=0.01):                  # time.sleep 대신: 시뮬 시간을 진행
        for _ in range(int(round(sec / dt))):
            if self.interrupt_at is not None and self.t >= self.interrupt_at:
                self.interrupt_at = None
                raise KeyboardInterrupt
            for i in range(3):
                d = self.cmd[i] - self.v[i]
                up = abs(self.cmd[i]) > abs(self.v[i]) and self.cmd[i] * self.v[i] >= 0
                lim = (self.acc if up else self.dec)[0 if i < 2 else 1] * dt
                self.v[i] += max(-lim, min(lim, d))
            bx, by, bw = (self.v[i] * self.k[i] for i in range(3))
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (bx * c - by * s) * dt
            self.y += (bx * s + by * c) * dt
            self.th += (bw + self.drift * abs(by)) * dt
            self.t += dt

    def pose(self):
        return round(self.x, 3), round(self.y, 3), round(math.degrees(self.th), 1)

SAFE_MAX = 0.5

def safe(v):
    return max(0.01, min(SAFE_MAX, abs(v)))

def run_unsafe(agv, v):
    sleep = agv.sleep
    agv.power_on()
    agv.move_forward(v)
    sleep(3)
    agv.turn_left(0.3)
    sleep(2)
    agv.stop()
    agv.power_off()

def run_safe(agv, v):
    sleep = agv.sleep
    agv.power_on()
    try:
        agv.move_forward(safe(v))
        sleep(3)
        agv.turn_left(0.3)
        sleep(2)
    finally:
        agv.stop()
        agv.power_off()

for name, prog in (("unsafe", run_unsafe), ("safe", run_safe)):
    for v in (0.5, 1.2):
        agv = SimAGVPlus("/dev/myagvplus_controller", baudrate=921600)
        agv.interrupt_at = 8.0                  # t = 8 s 에 정지 버튼
        try:
            prog(agv, v)
        except KeyboardInterrupt:
            pass
        x_end = agv.x
        agv.sleep(3.0)                          # 프로그램이 끝난 뒤 3초 동안의 로봇
        print("%-6s v=%.1f  중단 시 x=%.2f m -> 3초 뒤 x=%.2f m, 명령 속도 %.2f m/s"
              % (name, v, x_end, agv.x, agv.cmd[0]))

실행 결과: unsafe 는 중단 뒤에도 명령 속도 0.5 · 1.2 m/s 가 남아 3초 동안 1.5 m · 3.6 m 를 더 갑니다. safe 는 두 경우 모두 명령 속도가 0 이고 중단 위치에서 몇 cm 안에 멈춥니다. 1.2 를 요청해도 safe() 덕분에 0.5 m/s 로만 달립니다. finally 안에서 KeyboardInterrupt 는 다시 위로 올라가므로, 맨 바깥의 except KeyboardInterrupt 가 받아 "중단됨" 을 처리합니다.

확인 문제 4-1

시뮬레이터 4 에서 전진 중에 정지 버튼을 눌렀을 때 로봇이 멈추는 코드를 모두 고르면?

  1. A 만
  2. B 와 C
  3. A, B, C 모두 — 프로그램이 끝나면 로봇도 멈추므로
  4. C 만 — safe() 가 있어야 멈추므로
정답 보기② — 정지를 보장하는 것은 `finally` 의 `stop()` 입니다. B 와 C 는 모두 finally 가 있어 멈춥니다. safe() 는 속도를 제한할 뿐 멈추게 하지는 않습니다(④ 틀림). A 는 프로그램만 끝나고 마지막 명령 0.5 m/s 가 남아 랙에 부딪힙니다(③ 틀림).
확인 문제 4-2

사용자가 속도 2.0 을 입력했습니다. 시뮬레이터 4 의 B (try / finally 만) 로 실행했을 때 관찰한 것은?

  1. 1.60 m/s 로 잘려 랙에 부딪힌다
  2. move_forward 가 −1 로 차단되어 로봇은 전진하지 않고, 프로그램은 그대로 회전 단계로 넘어간다
  3. RuntimeError 가 나서 finally 로 점프한다
  4. 2.0 m/s 로 달려 랙에 부딪힌다
정답 보기② — B 는 반환값을 확인하지 않으므로 차단 사실을 모른 채 다음 줄로 갑니다. 로봇은 제자리에서 회전만 하고, "전진 3초" 는 아무 일도 하지 않습니다. ③ 은 반환값을 검사하는 C 에서 safe() 를 뺐을 때의 동작이고, C 는 safe() 가 0.5 로 잘라 정상 실행됩니다.
확인 문제 4-3

안전 구조가 올바른 코드는? (보기 ① ~ ④)

python
# ①
agv.power_on()
agv.move_forward(speed)
time.sleep(3)
agv.stop()

# ②
agv.power_on()
try:
    agv.move_forward(speed)
    time.sleep(3)
except Exception:
    agv.stop()

# ③
agv.power_on()
try:
    agv.move_forward(max(0.01, min(0.5, speed)))
    time.sleep(3)
finally:
    agv.stop()
    agv.power_off()

# ④
try:
    agv.move_forward(speed)
    time.sleep(3)
finally:
    agv.power_on()
  1. ① — stop() 이 마지막 줄에 있으므로 충분하다
  2. ② — 예외가 나면 stop() 을 부르므로 안전하다
  3. ③ — 속도를 자르고, 어떤 길로 끝나도 stop() · power_off() 를 실행한다
  4. ④ — finally 가 있으므로 안전하다
정답 보기③ — 속도를 안전 범위로 자르고, 정상 종료 · 예외 · Ctrl+C 모두에서 stop() 과 power_off() 를 실행합니다. ② 는 `except Exception` 이 KeyboardInterrupt 를 잡지 못하고, 정상 종료 때 stop 을 보내지도 않습니다. ④ 는 power_on 을 마지막에 두어 앞의 move 가 동작하지 않습니다.

실습 (실물)#

실물 실행 전 확인

실물 로봇의 터미널에서 아래 파일을 move_demo.py 로 저장하고 python3 move_demo.py 로 실행합니다. 공식 예제 흐름에 안전 구조를 더한 것입니다.

python실물 전용
import time
from pymycobot import MyAGVPlus

SAFE_MAX = 0.1          # 1단계(바퀴 띄우기) 0.1 -> 2단계 0.2 -> 3단계 0.5

def safe(v):
    return max(0.01, min(SAFE_MAX, abs(v)))

def checked(ret, what):
    if ret != 1:
        raise RuntimeError("%s 실패 (ret=%s)" % (what, ret))

agv = MyAGVPlus("/dev/myagvplus_controller", baudrate=921600,
                esp32_port="/dev/myagvplus_esp32", esp32_baud=115200, debug=True)

print("version:", agv.get_system_version(), agv.get_modify_version())
if agv.power_on() != 1:
    raise SystemExit("power_on 실패 - 배선 · 배터리 확인")

try:
    agv.set_led_mode(1)                         # LED 직접 제어 모드 (ch05)
    agv.set_led_color(255, (255, 0, 0))         # 빨강: 동작 중 표시
    checked(agv.move_forward(safe(0.5)), "move_forward")
    time.sleep(3)
    checked(agv.turn_left(0.3), "turn_left")
    time.sleep(2)
finally:
    agv.stop()
    agv.power_off()
    print("stopped and powered off")
실물 실습 순서
  1. 바퀴 띄우기 (SAFE_MAX = 0.1): 실행 후 전진 3초 동안 네 바퀴가 모두 같은 방향(앞으로 굴리는 쪽)으로 도는지, 회전 2초 동안 왼쪽 · 오른쪽 바퀴가 반대로 도는지 봅니다. 한 번 더 실행해 전진 중에 Ctrl+C 를 눌러 바퀴가 서는지 확인합니다.
  2. 바닥 저속 (SAFE_MAX = 0.2): 바닥에 테이프로 출발선을 붙이고 실행합니다. 0.2 m/s × 3 s = 0.6 m 와 실제 이동 거리를 줄자로 잽니다.
  3. move_left_lateral 추가: 전진 대신 move_left_lateral(safe(0.3)) 로 2초를 실행하고 거리와 방향 틀어짐을 잽니다. 시뮬레이터 2 의 결과와 비교합니다.
  4. 목표 속도 (SAFE_MAX = 0.5): 보조자와 함께 원래 예제 속도로 실행합니다.

자주 나는 오류와 해결#

1) import 에서 MyAGVPlus 를 찾지 못함#

text
ImportError: cannot import name 'MyAGVPlus' from 'pymycobot'
  • 원인: 설치된 pymycobot 이 MyAGVPlus 를 넣기 전 버전입니다. 또는 다른 Python(가상환경 · 시스템)에 설치했습니다.
  • 해결: pip install --upgrade pymycobot 후 python -c "import pymycobot, sys; print(pymycobot.__file__, sys.executable)" 로 같은 Python 인지 확인합니다. 문서의 다른 형태 from pymycobot.myagvplus import MyAGVPlus 도 시험해 봅니다.

2) 포트를 열 수 없음#

text
serial.serialutil.SerialException: [Errno 2] could not open port /dev/myagvplus_controller: [Errno 2] No such file or directory
  • 원인: 포트 이름이 장치 설정과 다릅니다(문서도 ESP32 를 /dev/ttyACM0 으로 쓰는 예가 있습니다). 노트북 등 로봇이 아닌 컴퓨터에서 실행했을 수도 있습니다.
  • 해결: 로봇 터미널에서 ls -l /dev/myagvplus* /dev/ttyACM* /dev/ttyUSB* 로 실제 이름을 확인해 생성자에 넣습니다. [Errno 13] Permission denied 이면 사용자를 dialout 그룹에 넣거나 권한을 확인합니다(정확한 설정은 공식 문서 확인 필요).

3) 버전이 None, power_on 이 0#

text
system version: None
power_on -> 0
  • 원인: 포트는 열렸지만 baud 가 맞지 않거나 포트 두 개를 서로 바꿔 적었습니다(모터 포트에 115200, ESP32 포트에 921600 등). 시뮬레이터 1 의 해 볼 것 4 와 같은 증상입니다.
  • 해결: 모터 컨트롤러 baudrate=921600, ESP32 esp32_baud=115200 이 각자의 포트와 짝이 맞는지 확인합니다. 버전 확인을 power_on() 보다 먼저 두어 6초를 기다리기 전에 걸러냅니다.

4) 명령이 −1 이고 로봇이 움직이지 않음#

text
move_forward -> -1
BACKGROUND VOLTAGE DETECTED!
  • 원인: (a) 속도가 0.01~1.60 m/s (회전 0.01~7.27 rad/s) 밖, (b) 배터리 두 개 모두 19.0 V 미만으로 동작 잠금, (c) STALL DETECTED! — 모터 걸림 · 과부하로 잠금, (d) power_on() 을 하지 않았거나 실패.
  • 해결: 반환값과 로그를 함께 출력합니다. (a) 는 safe() 로 자르고, (b) 는 충전, (c) 는 바퀴 주변 이물질 · 과적재를 확인한 뒤 모터 오류를 해제합니다(ch05). (d) 는 power_on() 의 반환값 1 을 확인합니다.

5) 왼쪽으로 가라고 했는데 계속 앞으로 감#

text
(오류 메시지 없음) move_left_lateral(2.0) 을 보냈는데 로봇이 이전 전진을 계속함
  • 원인: 새 명령이 범위 밖이라 차단(−1)되었고, 직전 명령이 그대로 유지되고 있습니다(2교시 해 볼 것 4).
  • 해결: 모든 이동 명령을 checked() 로 감싸 −1 이면 예외 → finally 의 stop 으로 가게 합니다. 속도는 safe() 를 거쳐 보냅니다.

6) Ctrl+C 를 눌렀는데 로봇이 서지 않음#

text
^CTraceback (most recent call last):
  File "move_demo.py", line 12, in <module>
    time.sleep(3)
KeyboardInterrupt
  • 원인: 프로그램은 끝났지만 stop() 을 보내지 않아 마지막 속도 명령이 로봇에 남았습니다. except Exception: 은 KeyboardInterrupt 를 잡지 못합니다.
  • 해결: 이동 코드를 try: 로 감싸고 finally: 에서 stop() · power_off() 를 실행합니다(4교시). 당장은 다른 터미널에서 python3 -c 로 stop 을 보내거나 보조자가 전원을 끕니다.

7) 오타가 몇 초 뒤에야 드러남#

text
AttributeError: 'MyAGVPlus' object has no attribute 'turn_lefft'
  • 원인: 메서드 이름 오타는 그 줄을 실행할 때 비로소 오류가 납니다. 그 전에 보낸 이동 명령은 계속 유효합니다.
  • 해결: try / finally 구조로 정지를 보장하고, 실물 전에 Playground 에서 끝까지 실행합니다. 편집기의 자동완성이나 python -m pyflakes move_demo.py 같은 정적 검사도 도움이 됩니다.

8) 정사각형이 닫히지 않고 바퀴마다 어긋남#

text
(오류 메시지 없음) 1 m 정사각형 3바퀴 후 출발점에서 수십 cm, 수십 도 어긋남
  • 원인: 시간 기반 이동은 가감속 · 바퀴 미끄럼을 모릅니다. 특히 회전 각도 오차가 다음 직진에 곱해져 쌓입니다(3교시).
  • 해결: 속도를 낮추고, 메카넘 로봇은 회전 대신 측면 이동을 쓰면 오차가 줄어듭니다. 근본 해결은 오도메트리 · LiDAR 피드백입니다(ch06 · ch07).

9) Playground 에서 pymycobot 을 찾지 못함#

text
ModuleNotFoundError: No module named 'pymycobot'
  • 원인: 이 강좌의 Playground 에는 pymycobot shim 이 아직 없습니다. 실물용 코드(python robot 배지)를 그대로 붙여 넣었습니다.
  • 해결: 이 차시 실습 코드처럼 맨 위에 SimAGVPlus 클래스를 넣고 agv = SimAGVPlus(...), sleep = agv.sleep 으로 바꿔 실행합니다.

과제#

  1. 반환값 로그: 실습 과제 2-2 의 명령 목록에 move_backward, turn_right 와 경계값(0.01, 1.60, 7.27, 0.0099, 1.601)을 더해 반환값 표를 만드세요. 범위 밖 명령이 들어간 뒤 "로봇이 따르는 명령" 이 무엇인지 칸을 하나 더 둡니다.
  2. 선반 왕복 프로그램: 시뮬레이터 3 의 ㄷ 자 경로(A → B → A)를 go() 함수로 짜고, 직선 속도 0.2 / 0.3 / 0.5 m/s 에서 5바퀴 뒤 오차를 표로 만드세요. 오차가 15 cm 를 넘지 않는 최대 속도와 반복 횟수를 3줄로 정리합니다.
  3. 안전 템플릿: safe() · checked() · try / finally 를 갖춘 실물 실행용 템플릿 파일을 만들고, 정지 버튼 시험(실습 과제 4-1 방식)을 통과한 것을 캡처해 제출합니다.

참고자료#

  • myAGV Plus 공식 문서 (영문): https://github.com/elephantrobotics/myagvPlus_docs/tree/main/MYAGV_PLUS_EN
  • 공식 Python API · 예제 (6.1 ApplicationBasePython — 설치, API, RGB, 이동 제어): https://github.com/elephantrobotics/myagvPlus_docs/tree/main/MYAGV_PLUS_EN/6-Software_Development_Guide/6.1-ApplicationBasePython
  • pymycobot 저장소 (Elephant Robotics Python 라이브러리): https://github.com/elephantrobotics/pymycobot
  • myagv_ros2 저장소 (ROS 2 패키지 — ch09 에서 다룸): https://github.com/elephantrobotics/myagv_ros2
  • myAGV Plus 제품 사진 · 소개 (hyenc.net): https://www.hyenc.net/products/35
  • pySerial 문서 (포트 · baud · SerialException): https://pyserial.readthedocs.io/
  • Python 공식 문서 — try / finally 와 KeyboardInterrupt: https://docs.python.org/3/tutorial/errors.html
  • 이 사이트의 도구: Python Playground
  • 이전 차시: ch03 메카넘 휠과 전방향 운동학 · 다음 차시: ch05 상태 진단 · LED · IO · 원격 제어