전체 과정 P1 로봇과 첫 만남 — 구조와 움직임 · 약 200분 · 중급

CH03Python 으로 움직이기 — MyAGVPro API

pymycobot 의 MyAGVPro 클래스로 이동 · 정지 · 상태 조회를 하고, Playground 의 시뮬레이터 타깃에서 코드를 먼저 검증합니다.

선수 챕터: CH02
Python Playground시뮬레이터

학습 목표#

  • pymycobot 의 MyAGVPro(직렬) · MyAGVProSocket(무선)으로 연결하고, power_on → is_power_on → 이동 → stop → power_off 흐름으로 프로그램을 짤 수 있습니다.
  • 이동 명령이 "거리" 가 아니라 속도를 걸어 두는 명령임을 설명하고, 범위(앞뒤 0 ~ 1.5 m/s, 옆 0 ~ 1.0 m/s)를 넘는 값을 보낼 때의 위험을 클램프 함수로 막을 수 있습니다.
  • 속도 × 시간 = 거리 방식(열린 루프)의 오차 원인 — 가속 · 감속 · 통신 지연 · 슬립 — 을 시뮬레이터로 분리해 보고, 보정값이 왜 조건이 바뀌면 깨지는지 말할 수 있습니다.
  • 자동 보고 메시지(get_auto_report_message)와 모터 조회 함수로 속도 · 배터리 전압 · 모터 상태를 읽고, 부하에 따른 전압 처짐에 속지 않는 배터리 감시 루프를 만들 수 있습니다.
  • set_led_color · get_pin_input · set_pin_output 으로 라이트 커튼 정지 · 재출발 상태 머신을 만들고, 폴링 주기 · 디바운스가 반응 거리에 주는 영향을 숫자로 설명할 수 있습니다.

이론#

이번 차시부터 로봇을 코드로 움직입니다. ch01 에서 확인한 "움직이기 전 점검"(비상정지 해제, is_power_on())이 출발점이고, ch02 에서 배운 vx · vy · ω 가 이번 차시 이동 명령의 정체입니다.

MyAGVPro API 지도 — 프로그램 한 개가 지나가는 순서 ① 연결 MyAGVPro( "/dev/agvpro_controller", baudrate=1000000) 무선(Wi-Fi AP): MyAGVProSocket( "192.168.4.1", 9000) ② 전원 · 안전 확인 get_estop_state() 0=해제 is_power_on() 1=켜짐 power_on() power_off() 끄면 바퀴가 풀림(자유 회전) ③ 이동 명령 — 속도를 "걸어 두는" 명령 move_forward(v) · move_backward(v) 0 ~ 1.5 m/s move_left_lateral(v) · move_right_lateral(v) 0 ~ 1.0 m/s turn_left(w) · turn_right(w) 범위 확인 필요 stop() ← 다음 명령이 올 때까지 속도는 유지됩니다 거리는 직접 정할 수 없습니다: 거리 = 속도 × (time.sleep 시간) ④ 상태 읽기 set_auto_report_state(1) get_auto_report_message() -> [rx, ry, rw, 기계상태, 모터정보, 배터리V, enable] get_motor_speeds() · get_motor_temps() get_motor_torques() · get_motor_loss_count() ⑤ 주변 장치 set_led_color(position, brightness, (R, G, B)) position 0 = 왼쪽, 1 = 오른쪽 · 밝기 0 ~ 255 get_pin_input(pin) -> 0 / 1 (-1 = 없는 핀) set_pin_output(pin, 0 / 1) 핀 번호 1 ~ 6 (라이트 커튼 · 경광등 · 컨베이어 신호)
이번 차시에서 쓰는 MyAGVPro API. 연결 → 전원 확인 → 이동 명령 ↔ 상태 읽기 → 주변 장치 순서로 프로그램이 흘러갑니다.
이 차시의 시뮬레이터와 Playground 코드에 대해
  • 실습 1-1 ~ 4-2 는 코드 맨 위에 메서드 이름이 똑같은 교육용 시뮬레이터 클래스(AGVSim 등)를 두고 실행합니다. 가상 시계라서 결과가 매번 같고 빠릅니다.
  • 실습 5 는 Playground 의 시뮬 타깃(myAGV Pro 물류창고 시뮬레이터)에 from pymycobot import MyAGVPro 를 그대로 씁니다. 브라우저용 대체 모듈(shim)이 명령을 3D 시뮬레이터로 보내므로, 실물 코드와 한 글자도 다르지 않습니다.
  • 실물로 옮길 때는 agv = AGVSim() 한 줄을 agv = MyAGVPro(...) 로, 가상 시계 agv.wait(...) 를 time.sleep(...) 으로 바꾸면 됩니다. 나머지 코드는 그대로입니다.
  • 공식 문서에 적혀 있지 않은 동작(범위를 넘는 속도의 처리, 회전 속도의 단위 · 상한, 명령 타임아웃 유무)은 시뮬레이터에서 교육용 가정으로 두고, 본문에 "(확인 필요)" 로 표시했습니다.

1교시 · 연결과 기본 이동 명령#

연결: 직렬과 무선#

공식 문서의 예제는 두 가지 연결을 보여 줍니다.

연결코드언제
직렬(USB-C)MyAGVPro("/dev/agvpro_controller", baudrate=1000000)로봇 내장 컴퓨터 · 노트북을 케이블로 연결. 1 000 000 bps, 8N1
직렬(PC 에서)MyAGVPro("/dev/ttyACM0", baudrate=1000000)PC 에 USB 로 꽂으면 보통 ttyACM* 로 잡힙니다. CH340 드라이버를 설치한 리눅스는 /dev/ttyCH341USB0 (공식 문서 4.1), Windows 는 COM3 같은 이름
무선(Wi-Fi AP)MyAGVProSocket("192.168.4.1", 9000)로봇의 AP 에 접속한 뒤. 공식 문서 기준 SSID ElephantAGVPro-AP2.4G, 주소 192.168.4.1:9000
무선으로 바꾸는 순서 (공식 문서 기준 — 펌웨어 버전에 따라 다를 수 있음)
  1. 먼저 직렬로 연결해 get_wifi_account() · get_wifi_ip_port() 로 AP 이름 · 비밀번호 · 주소를 읽습니다.
  2. set_communication_state(1) 로 통신 모드를 소켓(1)으로 바꿉니다 (0 = 직렬, 2 = 블루투스).
  3. PC 를 로봇의 AP 에 접속한 뒤 MyAGVProSocket(ip, port) 로 연결합니다.

AP 비밀번호 · 주소는 기본값을 외워 쓰지 말고 1단계에서 읽은 값을 씁니다. 공유 실습실이라면 비밀번호를 바꿀 수 있는지도 확인합니다 (확인 필요).

전원 흐름#

text
연결  ->  get_estop_state() == 0 ?  ->  is_power_on() == 1 ?  --아니오-->  power_on()
                                              |
                                              v
                            이동 명령 ... stop()  ->  (작업 끝)  power_off()
  • power_on() 은 모터 제어를 켭니다. 전원이 꺼진 상태에서 보낸 이동 명령은 아무 일도 일으키지 않습니다. 오류 메시지도 없이 로봇이 가만히 있어서 초보자가 가장 오래 헤매는 지점입니다.
  • power_off() 는 바퀴를 풀어 줍니다(공식 프로토콜 설명: wheels released). 경사로에서 끄면 로봇이 굴러갈 수 있습니다.
  • 공식 함수는 대부분 성공 1 · 실패 0 을 돌려줍니다. 반환값을 버리지 말고 확인하는 습관을 들입니다.

이동 명령 = 속도를 "걸어 두는" 명령#

명령움직임 (ch02 의 차체 속도)인자 범위 (공식 문서)
move_forward(v) · move_backward(v)vx = +v · vx = −v0 ~ 1.5 m/s
move_left_lateral(v) · move_right_lateral(v)vy = +v · vy = −v (ROS 관례: 왼쪽이 +y)0 ~ 1.0 m/s
turn_left(w) · turn_right(w)제자리 회전, 위에서 볼 때 반시계 · 시계범위 · 단위가 API 문서에 비어 있음 (확인 필요, 공식 예제는 turn_right(0.5)(6.1.1) · turn_left(0.1) · turn_right(0.2)(4.1))
stop()vx = vy = ω = 0—

핵심은 두 가지입니다.

  1. 거리를 직접 말할 수 없습니다. move_forward(0.5) 는 "0.5 m/s 로 달리기 시작" 이고, 얼마나 갈지는 그다음 time.sleep(T) 가 정합니다.
  2. 다음 명령이 올 때까지 마지막 속도가 유지됩니다. stop() 을 빼먹거나, 중간에 프로그램이 오류로 죽으면 로봇은 마지막 명령대로 계속 갑니다 (2교시에서 자세히).

인자는 모두 양수 크기입니다. 방향은 함수 이름이 정합니다. move_forward(-0.5) 로 후진하려는 코드는 범위를 벗어난 값입니다.

시뮬레이터 1 · 명령 시퀀스 실행기#

이 시뮬레이터의 모델 (교육용 가정)
  • 6 × 4 m 창고 바닥, 회색은 선반입니다. 로봇(0.53 × 0.36 m)은 (1, 1) 에서 오른쪽(+x)을 보고 출발합니다. 위쪽이 +y = 로봇의 왼쪽입니다.
  • 가감속 · 지연 · 슬립은 없습니다 (그건 2교시). 명령을 받으면 그 속도로 즉시 움직입니다.
  • 회전 명령의 단위는 rad/s, 상한은 1.0 rad/s 로 가정했습니다.
  • 범위를 넘는 속도를 받았을 때 실제 펌웨어가 어떻게 하는지는 공식 문서에 없습니다. 그래서 두 가지 경우(잘라서 실행 / 오류로 중단)를 골라 볼 수 있게 했습니다.

먼저 예측하세요. move_forward(2.0) 을 보내고 2 초 기다리면 로봇은 몇 m 갈까요? 4 m? 3 m? 0 m? 그리고 그 명령이 오류를 낸다면, 로봇은 어떻게 될까요?

시뮬레이터 1 · MyAGVPro 명령 시퀀스 → 2D 창고 바닥 (오른쪽 = 출발 시 로봇 앞 +x, 위쪽 = 로봇 왼쪽 +y)
· 범위 밖 속도 처리

해 볼 것

  1. 실습 순서 넣기 를 누르고 실행합니다. 오른쪽 코드 창에서 지금 실행 중인 줄이 강조되는 것을 보며, 끝 위치가 "앞 1.00 m, 왼쪽 0.50 m, 방향 90°" 인지 확인합니다. (turn_left 는 0.5 rad/s × π s = π/2 rad 입니다.)
  2. 모두 지우고 move_forward · 속도 2.0 · 2 s 를 추가한 뒤 stop() 을 추가합니다. "클램프" 와 "오류" 를 번갈아 골라 보세요. 각각 몇 m 갔나요? 예측과 비교합니다.
  3. 오류 모드에서 move_forward(0.5) 2 s → move_left_lateral(1.2) 2 s → stop() 을 만듭니다. 오류가 난 뒤 로봇은 멈추나요? 빨간 궤적은 무엇을 뜻하나요?
  4. 실습 순서에서 마지막 stop() 을 지우고(마지막 줄 지우기) 실행합니다. 프로그램이 끝난 뒤 로봇은?
  5. power_on() 호출 체크를 끄고 실행합니다. 화면에 오류가 있나요? 실물에서 이 증상을 어떻게 알아챌 수 있을까요?

관찰 포인트 — 이동 명령은 "속도를 걸어 두는 스위치" 입니다. 거리는 속도 × sleep 시간 이 만들고, 스위치를 내리는 것(stop())은 언제나 프로그래머 몫입니다. 범위를 넘는 값은 어느 쪽이든 위험합니다. 클램프되면 조용히 다른 거리를 가고(2.0 × 2 s = 4 m 를 기대했는데 3 m), 오류가 나면 프로그램만 죽고 로봇은 직전 명령대로 계속 갑니다. 그래서 2교시 실습에서 "범위를 내가 먼저 자르는" 함수와 "어떤 경우에도 stop() 을 부르는" 구조를 만듭니다.

확인 문제 1-1

시뮬레이터 1 을 "오류" 모드로 두고 move_forward(0.5) · 2 s → move_left_lateral(1.2) · 2 s → stop() 을 실행했습니다. 화면에서 볼 수 있는 결과로 알맞은 것은?

  1. 두 번째 줄에서 오류가 나 로봇이 그 자리에 바로 멈춘다
  2. 두 번째 줄이 1.0 m/s 로 바뀌어 실행되고 마지막에 멈춘다
  3. 두 번째 줄에서 프로그램이 중단되어 stop() 이 실행되지 않고, 로봇은 move_forward(0.5) 를 계속 수행해 선반 쪽으로 간다
  4. 전원이 자동으로 꺼진다
정답 보기③ — 예외는 프로그램을 멈추지만 로봇에 걸린 마지막 속도 명령을 지우지 않습니다. 앞으로 0.5 m/s 가 계속 유지되어 빨간 궤적으로 이어집니다. ② 는 "클램프" 모드의 결과입니다. 그래서 실물 코드는 반드시 try/finally 로 stop() 을 보장해야 합니다 (실습 2-2).
확인 문제 1-2

시뮬레이터 1 (회전 상한 1.0 rad/s 가정, 클램프 모드)에서 turn_left(2.0) 을 보내고 time.sleep(π/2 ≈ 1.57) 뒤 stop() 했습니다. 프로그래머는 180° 를 기대했습니다. 실제 회전각은?

  1. 180°
  2. 90°
  3. 0° (명령이 거부됨)
  4. 360°
정답 보기② — 2.0 이 1.0 rad/s 로 잘려 1.0 × 1.57 = 1.57 rad = 90° 만 돕니다. 오류 메시지가 없으니 "회전이 덜 됐다" 는 결과만 남습니다. 실제 펌웨어의 회전 상한 · 처리 방식은 확인이 필요하므로, 내 코드에서 미리 범위를 확인하는 것이 안전합니다.

2교시 · 시간 기반 이동과 그 한계#

열린 루프 제어#

1교시의 방식 — "0.5 m/s 로 2 초 가면 1 m" — 는 명령만 보내고 결과를 확인하지 않습니다. 이것을 열린 루프(open-loop) 제어라고 합니다.

열린 루프(open-loop) 제어 — 명령은 나가지만, 결과는 돌아오지 않습니다 목표 거리 d = 1.00 m 시간 계산 T = d / v = 2.0 s 로봇 + 바닥 (보이지 않는 부분) 가속 · 감속 · 통신 지연 · 슬립 실제 거리 0.90 ~ 1.05 m ? move_forward(0.5) sleep(T); stop() 되먹임(feedback) 없음 — 오차를 모른 채 끝남 오차가 생기는 곳 • 가속 시간 ta: 처음 ta 동안 덜 감 → 약 v·ta/2 부족 • 감속 시간 td: stop() 뒤에도 미끄러져 감 → 약 v·td/2 초과 • 통신 지연의 흔들림: 출발 · 정지 시각이 매번 조금씩 다름 → 매번 다른 거리 • 슬립 s: 바퀴는 돌았지만 차체는 덜 감 → 실제 거리 × (1 − s), 거리에 비례해 커짐 바퀴 · 센서로 실제 움직임을 재서 고치는 닫힌 루프(closed-loop)는 ch04 오도메트리부터 다룹니다.
목표 거리에서 시간을 계산해 명령을 보내지만, 실제 이동 거리를 재서 고치는 길(되먹임)이 없습니다.

식으로 쓰면, 최고 속도에 도달한 경우 실제 거리는 대략

d ≈ (1 − s) · v · (T + L정지 − L출발 − ta/2 + td/2)

  • v 명령 속도, T sleep 시간, s 슬립 비율
  • L출발 · L정지 출발 · 정지 명령이 로봇에 도착하기까지의 지연
  • ta 가속 시간(0 → v), td 감속 시간(v → 0)

입니다. 지연이 출발 · 정지에 똑같이 걸리면 서로 지워지지만, 매번 다르게 흔들리면 그만큼 거리가 흔들립니다.

시뮬레이터 2 · 1 m 를 정확히 가 보기#

이 시뮬레이터의 모델 (교육용 가정)
  • 프로그램: move_forward(v) → time.sleep(T) → stop(). 목표선은 1.00 m, 2.50 m 에 벽이 있습니다.
  • 속도는 가속 시간 ta 동안 0 → v 로, 감속 시간 td 동안 v → 0 으로 일정하게 변합니다.
  • 명령마다 지연 = 평균 ± 흔들림(균일 분포). 같은 설정으로 10 번 달려 끝 위치를 점으로 찍습니다.
  • 안전 타임아웃(watchdog): 로봇이 마지막 명령을 받은 뒤 이 시간 동안 새 명령이 없으면 스스로 멈춘다고 가정합니다. myAGV Pro 에 이런 기능이 있는지는 공식 문서에 없습니다 (확인 필요). 없으면 내 프로그램이 만들어야 합니다.

먼저 예측하세요. 기본값(0.5 m/s · 2.0 s · 가속 0.3 s · 감속 0.1 s)에서 로봇은 1 m 보다 더 갈까요, 덜 갈까요? 몇 cm 차이일까요?

시뮬레이터 2 · 속도 × 시간 = 거리? — 10 회 반복 주행
· ·

해 볼 것

  1. 기본값의 평균 거리를 읽고 예측과 비교합니다. 근사식 0.5 × (2.0 − 0.15 + 0.05) 로 손계산한 값과 맞나요?
  2. T 슬라이더만 움직여 평균이 1.000 m 가 되는 T 를 찾습니다 (보정). 몇 초인가요? 그다음 가속 시간을 0.3 → 0.6 s 로 바꾸면 보정이 유지되나요?
  3. 보정한 T 그대로 슬립을 0 → 10 % 로 올립니다. 오차는 몇 cm 인가요? 지연 흔들림을 ±0.10 s 로 키우면 점들의 퍼짐(폭)은?
  4. stop() 빼먹기를 켭니다. 로봇은 어디서 멈추나요? 안전 타임아웃을 1.0 s 로 켜면?
  5. stop() 을 다시 켜고 타임아웃 1.0 s 를 둔 채 T = 2.1 s 로 달려 봅니다. 왜 1 m 를 못 가나요? "0.1 s 마다 다시 보내기" 를 켜면?

관찰 포인트 — 가속 손실(v·ta/2)과 감속 미끄러짐(v·td/2)은 매번 같은 크기라 T 보정으로 지울 수 있습니다. 하지만 보정값은 그 속도 · 그 바닥 · 그 적재에서만 맞습니다. 지연 흔들림은 매번 다른 크기라 보정으로 지울 수 없고, 슬립은 거리에 비례해 커집니다. 결과를 재지 않는 한 로봇은 자기가 얼마나 틀렸는지 모릅니다. 안전 타임아웃은 "명령이 끊기면 멈춘다" 는 장치라서, 쓰는 쪽도 주기적으로 명령을 보내야 합니다. 이 원리는 ROS 2 의 /cmd_vel 운용(ch09)에서도 그대로 나옵니다.

확인 문제 2-1

시뮬레이터 2 기본값(v 0.5 m/s, T 2.0 s, 가속 0.3 s, 감속 0.1 s, 슬립 0)에서 평균 거리가 약 0.95 m 로 나왔습니다. 모자란 5 cm 의 가장 큰 원인은?

  1. 통신 지연 평균 0.05 s 가 출발에만 걸려서
  2. 가속에서 잃은 거리(0.5 × 0.3 / 2 = 7.5 cm)가 감속에서 더 간 거리(0.5 × 0.1 / 2 = 2.5 cm)보다 커서
  3. 슬립 때문에
  4. 지연 흔들림 ±0.02 s 때문에
정답 보기② — 출발 지연과 정지 지연은 평균이 같아 서로 지워집니다. 남는 것은 가감속의 비대칭 7.5 − 2.5 = 5 cm 입니다. 매번 같은 크기라서 T 를 2.10 s 로 늘리면 보정됩니다. 흔들림 ±0.02 s 는 점들을 약 ±1 cm 퍼뜨릴 뿐 평균을 옮기지 않습니다.
확인 문제 2-2

stop() 이 있는 정상 프로그램(T = 2.1 s)에 안전 타임아웃 1.0 s 를 켰더니 로봇이 약 0.45 m 에서 멈췄습니다. 가장 알맞은 해석과 해결은?

  1. 타임아웃 장치가 고장 났다 → 타임아웃을 끈다
  2. 명령을 출발 때 한 번만 보내서, 1.0 s 동안 새 명령이 없자 로봇이 스스로 멈췄다 → sleep 대신 짧은 주기로 같은 명령을 다시 보내는 루프를 쓴다
  3. 슬립이 커졌다 → T 를 두 배로 늘린다
  4. 배터리가 부족하다 → 충전한다
정답 보기② — 타임아웃은 "마지막 명령 수신 뒤 일정 시간" 을 잽니다. 긴 sleep 한 번은 명령이 끊긴 것과 구별되지 않습니다. 짧은 주기(예: 0.1 s)로 명령을 다시 보내면 정상 주행 중에는 타임아웃이 걸리지 않고, 프로그램이 멈추면 그때 로봇도 멈춥니다. 타임아웃을 끄는 것은 안전장치를 없애는 것입니다.

3교시 · 상태 읽기 — 자동 보고 · 모터 · 배터리#

자동 보고 메시지#

set_auto_report_state(1) 로 자동 보고를 켜면, 로봇이 상태를 주기적으로(공식 프로토콜 기준 20 Hz) 보내고 get_auto_report_message() 가 가장 최근 값을 목록으로 돌려줍니다.

순서값뜻
0 · 1 · 2rx · ry · rw (float)차체 속도 x · y · 회전 (프로토콜 설명 기준 — 위치가 아니라 속도)
3기계 상태 (list[int])비상정지 · 미기동 · 범퍼 1 · 2 · 모터 1 ~ 4 연결 상태. 0 = 정상
4모터 정보 (list[int])바퀴 1 ~ 4 오류 표시. 0 = 정상
5배터리 전압 (float)V
6모터 사용 상태 (int)0 = Enabled, 1 = Disabled
0 과 1 의 뜻이 함수마다 다릅니다

자동 보고의 6번 칸은 0 이 "모터 켜짐" 인데, get_motor_enable_status() 는 1 이 "켜짐" 입니다. is_power_on() 은 1 이 켜짐, get_estop_state() 는 1 이 "눌림" 입니다. 상태 코드는 기억에 의존하지 말고 이름 붙은 상수로 바꿔 쓰세요 (실습 3-1). 목록 구성은 펌웨어 버전에 따라 다를 수 있으니 실물에서 한 번 출력해 확인합니다.

모터 조회 함수#

함수돌려주는 값 (바퀴 4개 목록)읽는 법
get_motor_speeds()바퀴 속도프로토콜 설명 기준 rad/s, ±44 rad/s 범위. ch02 의 ω = v / r 와 비교
get_motor_torques()바퀴 토크부하 · 가속이 클수록 큼. 단위는 문서마다 표기가 달라 확인 필요
get_motor_temps()모터 온도 (°C)오래 무겁게 달리면 오름. 과열 시 get_motor_status() 에 오류 비트
get_motor_loss_count()통신 손실 횟수0 이 정상. 늘어나면 배선 · 잡음 · 과부하 의심
get_motor_status()오류 코드0 = 정상. 저전압 · 드라이버 · 과열 · 엔코더 · 과부하 · 미보정 비트

한 단계 아래 — 직렬 프로토콜 프레임 (공식 문서 6.3.1)#

pymycobot 은 함수 호출을 14 바이트 프레임으로 바꿔 직렬 포트(1 000 000 bps, 8N1)로 보냅니다. 라이브러리 없이도 같은 프레임을 만들 수 있고, 통신 문제를 추적할 때 이 모양을 알면 빠릅니다.

위치바이트뜻
0 · 1FE FE프레임 머리
20B길이 (고정)
3기능 코드0x10 기동 · 0x11 끄기 · 0x21 이동 · 0x22 정지 · 0x23 ~ 0x25 자동 보고 · 0x31 모터 상태 · 0x35 온도 · 0x36 속도 · 0x3A LED 모드 · 0x40 · 0x41 IO …
4 ~ 11데이터 8 바이트모자라면 0 으로 채움
12 · 13CRC16-Modbus높은 바이트 먼저

이동(0x21)의 데이터는 2 바이트씩 앞뒤 속도 × 100 · 좌우 속도 × 100 · 회전 속도 × 100 · 예약(0) 입니다 (부호 있는 정수, 큰 바이트 먼저). 예: 1 m/s 전진 → 00 64(=100) → FE FE 0B 21 00 64 00 00 00 00 00 00 4D 39.

회전 부호가 ROS 와 반대입니다

프로토콜 설명은 회전 값 "양수 = 시계 방향" 입니다. ROS 관례(ch01 · ch02)는 반시계가 +ω 입니다. turn_left · turn_right 를 쓰면 라이브러리가 맞춰 주지만, 프레임을 직접 만들거나 다른 언어로 옮길 때는 부호를 한 번 뒤집어야 합니다.

python시뮬 실행 가능
# 공식 문서 6.3.1 의 예제 프레임을 직접 만들어 CRC 까지 맞춰 봅니다 (실물 없이 실행)
def crc16_modbus(data):
    crc = 0xFFFF
    for b in data:
        crc ^= b
        for _ in range(8):
            crc = (crc >> 1) ^ 0xA001 if crc & 1 else crc >> 1
    return crc

def frame(func, payload=b""):
    body = bytes([0xFE, 0xFE, 0x0B, func]) + payload.ljust(8, b"\x00")
    c = crc16_modbus(body)
    return body + bytes([c >> 8, c & 0xFF])          # 높은 바이트 먼저

def i16(v):
    return int(round(v * 100)).to_bytes(2, "big", signed=True)

def show(b):
    return " ".join(f"{x:02X}" for x in b)

print("1 m/s forward :", show(frame(0x21, i16(1.0))))
print("0.5 m/s right :", show(frame(0x21, i16(0) + i16(-0.5))))
print("start         :", show(frame(0x10)))
# 문서 값: ... 4D 39 / ... FF CE 00 00 00 00 54 61 / ... 1A 45

먼저 예측하세요. 0.5 m/s 오른쪽 의 좌우 속도 바이트는 왜 FF CE 일까요? (힌트: −50 을 2 바이트 2의 보수로)

배터리 전압은 "부하에 따라 처집니다"#

배터리 단자 전압은 V = V휴지 − I · R내부 입니다. 무거운 짐을 싣고 세게 가속하면 전류 I 가 커져 잔량이 그대로여도 전압이 순간적으로 떨어집니다. 그래서 "전압 < 임계값이면 정지" 라는 단순한 감시는 가속할 때마다 오작동할 수 있습니다. 시뮬레이터 3 에서 직접 확인합니다.

시뮬레이터 3 · 적재 · 속도 → 토크 · 전압 · 감시 루프#

이 시뮬레이터의 모델 (교육용 가정)
  • 왕복 주행: 가속(1.0 m/s²) → 3 s 정속 → 감속 → 2 s 정차 를 되풀이합니다. 총 질량 = 40 kg(차체) + 적재.
  • 바퀴당 토크 = 질량 × (가속도 + 0.06 × 9.81) × 0.05 m ÷ 4, 전력 = 힘 × 속도 ÷ 0.75 + 대기 25 W.
  • 배터리 휴지 전압은 잔량에 따라 정해지는 LiFePO4 형태의 가정 곡선, 내부 저항 0.12 Ω. 시간은 배터리만 60 배 빠르게 흐릅니다 (1 s = 1 분 소모).
  • 상단 텍스트는 자동 보고 메시지를 20 Hz 로 읽은 모양을 흉내 낸 것입니다. 실제 값의 크기 · 단위는 실물에서 확인하세요.

먼저 예측하세요. 적재를 0 → 50 kg 으로 늘리면 가속 순간의 바퀴 토크는 몇 배가 될까요? 배터리 전압 그래프는 어떤 모양이 될까요?

시뮬레이터 3 · 자동 보고 대시보드 + 배터리 감시 루프


감시 방식 · 배속 ·

해 볼 것

  1. 적재 0 kg · 1.0 m/s 에서 토크 그래프(주황)의 모양을 봅니다. 가속 · 정속 · 감속 구간에서 토크는 각각 어떤가요? 감속 때 음수가 되는 이유는?
  2. 적재를 50 kg 으로 올립니다. 가속 구간의 토크 봉우리가 몇 배가 되나요? (40 kg → 90 kg 이면 예측은?) 단자 전압(회색)의 출렁임은 어떻게 변하나요?
  3. 적재 50 kg · 1.5 m/s · 감시 "원시값" 으로 리셋 합니다. 감시 루프가 언제 stop() 을 부르나요? 그때 휴지 전압(초록)은 임계보다 높나요?
  4. 같은 조건에서 감시 방식을 "3 s 평균" · "정차 중 값만" 으로 바꾸고 각각 리셋합니다. 어느 방식이 잔량이 실제로 낮아졌을 때 멈추나요?
  5. 시작 잔량을 10 % 로 두고 "정차 중 값만" 으로 리셋합니다. 이 방식의 단점(멈출 때까지 걸리는 시간, 정속 주행이 긴 경로)은 무엇일까요?

관찰 포인트 — 토크는 질량 × (가속도 + 구름 저항) 에 비례하므로, 적재가 늘면 특히 가속 순간의 부하가 커집니다. 전류가 커지면 I · R 만큼 전압이 처지고, 원시값 한 번으로 판정하는 감시는 이 처짐을 "배터리 부족" 으로 오해합니다. 센서 값으로 판단할 때는 언제 · 어떤 조건에서 읽은 값인지가 값 자체만큼 중요합니다. 평균(시간으로 거르기)이나 정차 중 판정(조건으로 거르기)처럼 판단 규칙을 설계해야 합니다.

확인 문제 3-1

시뮬레이터 3 에서 적재 50 kg · 1.5 m/s · 시작 잔량 30 % · 임계 24.6 V · 감시 "원시값" 으로 리셋하자 1 초 남짓 만에 stop() 이 호출되었고, 그때 휴지 전압은 약 25.7 V 였습니다. 가장 알맞은 해석은?

  1. 배터리 잔량이 이미 바닥이었다
  2. 첫 가속 때 큰 전류가 흘러 단자 전압이 1 V 넘게 처졌고, 원시값 한 번이 임계 아래로 내려가 오탐이 났다
  3. 모터가 과열되어 펌웨어가 멈췄다
  4. 임계 전압이 너무 낮게 설정되었다
정답 보기② — 가속 중에는 전류가 9 A 를 넘게 흘러 0.12 Ω × 9 A ≈ 1.1 V 가 처집니다 (최고 속도 직전에는 약 12 A, 1.4 V). 휴지 전압 25.7 V 는 임계 24.6 V 보다 1 V 넘게 높으니 배터리는 충분합니다. 평균을 쓰거나 정차 중에 판정해야 합니다.
확인 문제 3-2

속도 1.0 m/s 에서 적재를 0 kg → 50 kg 으로 바꾸었습니다. 시뮬레이터 모델에서 가속 구간 바퀴당 토크는 대략 몇 배가 되나요?

  1. 변하지 않는다 (속도가 같으므로)
  2. 약 1.25 배 (50 kg 이 최대 적재라서)
  3. 약 2.25 배 (총 질량 40 kg → 90 kg)
  4. 약 50 배
정답 보기③ — 토크 = 질량 × (가속도 + 구름 저항) × r ÷ 4 이고 가속도 · 구름 저항 계수는 그대로이므로 토크는 총 질량에 비례합니다. 40 → 90 kg 이면 2.25 배(약 0.79 → 1.79 N·m)입니다. 속도는 토크가 아니라 전력(= 힘 × 속도)에 영향을 줍니다.

4교시 · LED · 디지털 IO 로 주변 장치 다루기#

LED 로 상태 알리기#

set_led_color(position, brightness, color) — position 0 = 왼쪽, 1 = 오른쪽 LED, 밝기 0 ~ 255, 색은 (R, G, B) 튜플입니다. 물류 현장에서는 사람이 멀리서도 로봇의 상태를 알아야 하므로, 색 규칙을 정해 둡니다.

상태색호출 예
대기(IDLE)초록set_led_color(0, 255, (0, 255, 0)) · set_led_color(1, 255, (0, 255, 0))
이동(MOVING)파랑(0, 0, 255)
차단 · 오류(BLOCKED)빨강(255, 0, 0)
LED 모드 (프로토콜 0x3A)

LED 에는 배터리 표시 모드(0) 와 사용자 지정 모드(1) 가 있습니다 (공식 문서 6.3.1). 배터리 표시 모드에서는 펌웨어가 잔량에 따라 색을 정하므로, set_led_color 가 기대대로 보이지 않으면 모드부터 의심합니다. pymycobot 에서 모드를 바꾸는 함수 이름은 API 문서(6.1.2)에 없어 버전별로 확인이 필요합니다.

디지털 입출력 (IO)#

myAGV Pro 에는 입력 6 · 출력 6 개의 디지털 IO 가 있습니다 (ch01). 핀 번호는 1 ~ 6 입니다.

  • get_pin_input(pin) → 0 (Low) · 1 (High), 없는 핀이면 −1
  • set_pin_output(pin, state) → state 0 = Low, 1 = High

이 차시 예제의 배선 (실제 배선 · 전압 레벨은 장비 설명서로 확인):

핀방향연결 장치뜻
IN 1입력라이트 커튼1 = 빛 통과(안전), 0 = 빛 가려짐(사람 · 물체)
IN 2입력출발 버튼누르면 1
OUT 1출력경광등1 = 켬
OUT 2출력컨베이어 운전 신호1 = 컨베이어 돌림
안전 신호는 "1 이 안전" 으로 배선합니다

라이트 커튼처럼 안전에 관련된 입력은 신호가 있을 때(1) 안전으로 씁니다. 그러면 전선이 빠지거나 끊어져 신호가 0 이 되었을 때도 로봇은 "위험" 으로 판단하고 멈춥니다 (fail-safe). 반대로 "1 = 위험" 으로 짜면, 선이 빠진 순간 로봇은 영원히 "안전" 으로 읽습니다.

상태 머신#

IO 를 다루는 프로그램은 상태 머신(state machine) 으로 짜면 꼬이지 않습니다. 매 폴링마다 "지금 상태 + 입력" 을 보고 다음 상태와 할 일을 정합니다.

text
          커튼 정상 & 대기 끝                 커튼 차단
 [IDLE 초록] ─────────────────> [MOVING 파랑] ─────────────> [BLOCKED 빨강]
      ^                              |   ^                          |
      └────── 목적지 도착 ───────────┘   └──── 커튼 복구 (+ 재출발 조건) ┘

시뮬레이터 4 · 라이트 커튼과 상태 머신#

이 시뮬레이터의 모델 (교육용 가정)
  • 로봇은 통로의 A ↔ B 를 왕복합니다(목적지 도착 · 정차 2 s 처리는 시뮬레이터가 대신). 통로 가운데에 라이트 커튼이 있습니다.
  • 제어 프로그램은 폴링 주기마다 get_pin_input(1) 을 읽고 상태 머신을 한 번 돌립니다. 폴링 사이에는 마지막 명령대로 움직입니다.
  • 정지는 1.0 m/s² 로 감속합니다. "배선 잡음" 을 켜면 IN 1 이 가끔 아주 짧게(0.06 s) 0 으로 튑니다.
  • 디바운스 N: 같은 값을 N 번 연속 읽어야 바뀐 것으로 받아들입니다.

먼저 예측하세요. 0.5 m/s 로 달리는 중에 사람이 커튼을 지나갑니다. 폴링 주기가 0.1 s 일 때와 1.0 s 일 때, 커튼이 끊긴 순간부터 로봇이 완전히 설 때까지 각각 몇 cm 를 더 갈까요?

시뮬레이터 4 · IO 패널 · LED · 상태 머신
입력
출력
복구 후 재출발 · ·

해 볼 것

  1. 로봇이 A → B 로 가는 중에 사람 지나가기 를 누릅니다. LED 색, 경광등(OUT1), 오른쪽 API 호출 기록이 어떤 순서로 바뀌나요? 커튼이 끊긴 뒤 몇 cm 더 갔나요?
  2. 폴링 주기를 0.1 s → 1.0 s 로 바꾸고 다시 해 봅니다. 반응 거리는 얼마나 늘었나요? 아래 "이론" 줄과 비교합니다.
  3. 재출발 방식을 "즉시 자동" · "1 s 연속 정상" · "출발 버튼" 으로 바꿔 가며, 사람이 지나간 뒤 로봇이 언제 다시 출발하는지 봅니다. 사람이 커튼 바로 뒤에 서 있을 수 있는 현장이라면 어느 방식을 쓰겠습니까?
  4. 배선 잡음 을 켜고 디바운스 N = 1 로 1 분쯤 둡니다. 오정지 횟수는? N 을 3 으로 올리면 오정지는 어떻게 되고, 이론 반응 거리는 몇 cm 늘어나나요?
  5. IN1 버튼으로 커튼을 계속 가린 채 B 에 도착하게 해 봅니다. 대기(IDLE)에서 출발하지 않는 이유를 상태 머신 그림에서 찾습니다.

관찰 포인트 — 폴링 방식에서 로봇은 다음 폴링 때까지 입력 변화를 모릅니다. 반응 거리 = v × (폴링 주기 × 디바운스 횟수) + 제동 거리 이므로, 폴링 주기와 디바운스는 공짜가 아닙니다. 잡음을 거르려고 N 을 키우면 오정지는 줄지만 반응이 늦어집니다. 사람의 안전이 걸린 신호는 소프트웨어 폴링에만 맡기지 말고, 라이트 커튼의 안전 출력을 비상정지 회로에 하드웨어로 연결하는 것이 원칙입니다 (ch05 에서 다룸).

확인 문제 4-1

시뮬레이터 4 에서 속도 0.5 m/s, 디바운스 N = 1, 정지 감속 1.0 m/s² 입니다. 폴링 주기를 1.0 s 로 두면 커튼이 끊긴 뒤 로봇이 서기까지 최악의 경우 얼마나 더 가나요?

  1. 약 12.5 cm (제동 거리만)
  2. 약 17.5 cm
  3. 약 62.5 cm
  4. 0 cm (커튼이 끊기면 즉시 선다)
정답 보기③ — 끊긴 직후 폴링이 막 지나갔다면 다음 폴링까지 1.0 s × 0.5 m/s = 50 cm 를 모른 채 달리고, 그 뒤 제동 거리 0.5² / (2 × 1.0) = 12.5 cm 를 더 갑니다. 폴링 0.1 s 면 5 + 12.5 = 17.5 cm 입니다(②). 실제 반응 거리는 끊긴 시점에 따라 이 사이 값이 나옵니다.
확인 문제 4-2

배선 잡음을 켰더니 디바운스 N = 1 에서 로봇이 가끔 혼자 멈췄다 섭니다. N = 3 (폴링 0.1 s)으로 올리자 오정지가 사라졌습니다. 이 결과의 해석으로 알맞은 것은?

  1. 잡음이 사라졌다
  2. 0.06 s 짜리 짧은 튐은 3 번 연속(0.3 s) 0 으로 읽히지 않아 무시되지만, 진짜 차단도 최대 0.2 s 늦게 받아들여 반응 거리가 약 10 cm 늘었다
  3. N 을 키우면 반응이 빨라진다
  4. N 은 LED 색에만 영향을 준다
정답 보기② — 디바운스는 "N 번 연속 같은 값" 을 요구하므로 짧은 튐을 거르는 대신, 진짜 변화도 (N − 1) × 폴링 주기만큼 늦게 인정합니다. 0.5 m/s 에서 0.2 s 는 10 cm 입니다. 잡음 자체는 배선 · 접지를 고쳐서 없애는 것이 먼저입니다.

실습 (시뮬레이터)#

교시마다 Playground 에서 코드를 직접 돌립니다. starter 의 TODO 를 채워 실행한 뒤, 풀이 와 비교하세요. 코드 맨 위의 AGVSim · FakeIO 같은 클래스는 MyAGVPro 와 메서드 이름이 같은 교육용 대역입니다. 실물로 옮길 때는 그 클래스를 만드는 줄만 MyAGVPro(...) 로 바꿉니다.

Playground 열기

실습 1-1 · 앞 1 m → 왼쪽 0.5 m → 90° 회전 → 정지 (1교시)

AGVSim 으로 시퀀스를 짭니다. 각 단계 뒤에 agv.pose() 를 출력해 위치가 계획대로인지 확인하고, 마지막에 범위를 넘는 move_forward(2.0) 을 1 s 보내 결과를 예측과 비교하세요. 시뮬레이터 1 의 "실습 순서 넣기" 결과(앞 1.00 m, 왼쪽 0.50 m, 90°)와 같아야 합니다.

python시뮬 실행 가능
import math

class AGVSim:
    """MyAGVPro 와 메서드 이름이 같은 교육용 2D 시뮬레이터 (가상 시계)"""
    LIM = {"fwd": 1.5, "lat": 1.0, "turn": 1.0}   # turn 상한은 교육용 가정

    def __init__(self):
        self.x = self.y = self.th = self.t = 0.0
        self.cmd = (0.0, 0.0, 0.0)
        self.powered = 0

    def power_on(self):
        self.powered = 1
        return 1

    def power_off(self):
        self.powered = 0
        self.cmd = (0.0, 0.0, 0.0)
        return 1

    def is_power_on(self):
        return self.powered

    def _clip(self, v, kind):
        lim = self.LIM[kind]
        if v < 0 or v > lim:
            print(f"[sim] speed {v} out of range 0~{lim} -> clamped")
        return min(max(v, 0.0), lim)

    def _set(self, vx, vy, w):
        if not self.powered:
            print("[sim] power off - command ignored")
            return 0
        self.cmd = (vx, vy, w)
        return 1

    def move_forward(self, s):       return self._set(self._clip(s, "fwd"), 0.0, 0.0)
    def move_backward(self, s):      return self._set(-self._clip(s, "fwd"), 0.0, 0.0)
    def move_left_lateral(self, s):  return self._set(0.0, self._clip(s, "lat"), 0.0)
    def move_right_lateral(self, s): return self._set(0.0, -self._clip(s, "lat"), 0.0)
    def turn_left(self, s):          return self._set(0.0, 0.0, self._clip(s, "turn"))
    def turn_right(self, s):         return self._set(0.0, 0.0, -self._clip(s, "turn"))

    def stop(self):
        self.cmd = (0.0, 0.0, 0.0)
        return 1

    def wait(self, sec, dt=0.01):
        # time.sleep(sec) 대신: 가상 시계를 sec 만큼 진행하며 위치를 적분
        for _ in range(int(round(sec / dt))):
            vx, vy, w = self.cmd
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (vx * c - vy * s) * dt
            self.y += (vx * s + vy * c) * dt
            self.th += w * dt
            self.t += dt

    def pose(self):
        return (f"t={self.t:5.2f}s  x={self.x:+.3f}  y={self.y:+.3f}  "
                f"th={math.degrees(self.th):+6.1f}deg  cmd={self.cmd}")


agv = AGVSim()        # 실물: agv = MyAGVPro("/dev/agvpro_controller", baudrate=1000000)
sleep = agv.wait      # 실물: sleep = time.sleep

if agv.is_power_on() != 1:
    agv.power_on()

# 1) 앞으로 1 m - 0.5 m/s 로 몇 초?
agv.move_forward(0.5)
sleep(0.0)            # TODO: 시간 계산
print("1)", agv.pose())

# 2) 왼쪽으로 0.5 m - 0.25 m/s 로
# TODO: move_left_lateral + sleep
print("2)", agv.pose())

# 3) 제자리 왼쪽 90도 - turn_left(0.5), 단위 rad/s 로 가정
# TODO: turn_left + sleep (math.pi 사용)
print("3)", agv.pose())

# 4) 정지하고 1 s 기다려도 그대로인지 확인
# TODO: stop + sleep(1.0)
print("4)", agv.pose())

# 예측: move_forward(2.0) 을 1 s 보내면 몇 m?
agv2 = AGVSim()
agv2.power_on()
# TODO: move_forward(2.0) -> wait(1.0) -> stop() 후 pose 출력
풀이
python시뮬 실행 가능
import math

class AGVSim:
    """MyAGVPro 와 메서드 이름이 같은 교육용 2D 시뮬레이터 (가상 시계)"""
    LIM = {"fwd": 1.5, "lat": 1.0, "turn": 1.0}   # turn 상한은 교육용 가정

    def __init__(self):
        self.x = self.y = self.th = self.t = 0.0
        self.cmd = (0.0, 0.0, 0.0)
        self.powered = 0

    def power_on(self):
        self.powered = 1
        return 1

    def power_off(self):
        self.powered = 0
        self.cmd = (0.0, 0.0, 0.0)
        return 1

    def is_power_on(self):
        return self.powered

    def _clip(self, v, kind):
        lim = self.LIM[kind]
        if v < 0 or v > lim:
            print(f"[sim] speed {v} out of range 0~{lim} -> clamped")
        return min(max(v, 0.0), lim)

    def _set(self, vx, vy, w):
        if not self.powered:
            print("[sim] power off - command ignored")
            return 0
        self.cmd = (vx, vy, w)
        return 1

    def move_forward(self, s):       return self._set(self._clip(s, "fwd"), 0.0, 0.0)
    def move_backward(self, s):      return self._set(-self._clip(s, "fwd"), 0.0, 0.0)
    def move_left_lateral(self, s):  return self._set(0.0, self._clip(s, "lat"), 0.0)
    def move_right_lateral(self, s): return self._set(0.0, -self._clip(s, "lat"), 0.0)
    def turn_left(self, s):          return self._set(0.0, 0.0, self._clip(s, "turn"))
    def turn_right(self, s):         return self._set(0.0, 0.0, -self._clip(s, "turn"))

    def stop(self):
        self.cmd = (0.0, 0.0, 0.0)
        return 1

    def wait(self, sec, dt=0.01):
        # time.sleep(sec) 대신: 가상 시계를 sec 만큼 진행하며 위치를 적분
        for _ in range(int(round(sec / dt))):
            vx, vy, w = self.cmd
            c, s = math.cos(self.th), math.sin(self.th)
            self.x += (vx * c - vy * s) * dt
            self.y += (vx * s + vy * c) * dt
            self.th += w * dt
            self.t += dt

    def pose(self):
        return (f"t={self.t:5.2f}s  x={self.x:+.3f}  y={self.y:+.3f}  "
                f"th={math.degrees(self.th):+6.1f}deg  cmd={self.cmd}")


agv = AGVSim()        # 실물: agv = MyAGVPro("/dev/agvpro_controller", baudrate=1000000)
sleep = agv.wait      # 실물: sleep = time.sleep

if agv.is_power_on() != 1:
    agv.power_on()

agv.move_forward(0.5)
sleep(1.0 / 0.5)                      # 1 m / 0.5 m/s = 2.0 s
print("1)", agv.pose())

agv.move_left_lateral(0.25)
sleep(0.5 / 0.25)                     # 0.5 m / 0.25 m/s = 2.0 s
print("2)", agv.pose())

agv.turn_left(0.5)
sleep((math.pi / 2) / 0.5)            # 90도 / 0.5 rad/s = 3.14 s
print("3)", agv.pose())

agv.stop()
sleep(1.0)
print("4)", agv.pose())

agv2 = AGVSim()
agv2.power_on()
agv2.move_forward(2.0)
agv2.wait(1.0)
agv2.stop()
print(agv2.pose())
# 1) t= 2.00s  x=+1.000  y=+0.000  th=  +0.0deg  cmd=(0.5, 0.0, 0.0)
# 2) t= 4.00s  x=+1.000  y=+0.500  th=  +0.0deg  cmd=(0.0, 0.25, 0.0)
# 3) t= 7.14s  x=+1.000  y=+0.500  th= +90.0deg  cmd=(0.0, 0.0, 0.5)
# 4) t= 8.14s  x=+1.000  y=+0.500  th= +90.0deg  cmd=(0.0, 0.0, 0.0)
# [sim] speed 2.0 out of range 0~1.5 -> clamped
# t= 1.00s  x=+1.500  ...

3) 의 cmd 가 아직 회전 중인 것에 주목하세요. stop() 전까지는 "돌고 있는" 상태입니다. 클램프는 경고 한 줄만 남기고 1.5 m 를 갑니다 — 2.0 m 를 기대한 코드에는 조용한 오류입니다.

실습 1-2 · 내 코드에서 먼저 속도를 자르기 (1교시)

펌웨어가 범위 밖 값을 어떻게 처리하든 상관없도록, 보내기 전에 범위를 확인하는 safe_move() 를 만듭니다. 첫 시험 운전용으로 공식 범위보다 낮은 상한 SAFE_MAX = 0.5 도 함께 겁니다. 없는 명령 이름은 ValueError 로 막습니다.

python시뮬 실행 가능
LIMITS = {"move_forward": 1.5, "move_backward": 1.5,
          "move_left_lateral": 1.0, "move_right_lateral": 1.0,
          "turn_left": 1.0, "turn_right": 1.0}     # turn 상한은 교육용 가정
SAFE_MAX = 0.5                                     # 첫 시험 운전 상한 (내 규칙)

class Recorder:
    """보낸 명령만 기록하는 가짜 로봇"""
    def __init__(self):
        self.sent = []
    def __getattr__(self, name):
        return lambda *a: self.sent.append((name,) + a) or 1

def safe_move(agv, name, speed):
    # TODO 1: name 이 LIMITS 에 없으면 ValueError
    # TODO 2: hi = min(LIMITS[name], SAFE_MAX), v 를 0 ~ hi 로 자르기
    # TODO 3: 잘렸으면 경고 출력
    v = speed
    getattr(agv, name)(v)
    return v

agv = Recorder()
tests = [("move_forward", 2.0), ("move_left_lateral", -0.3),
         ("turn_left", 0.3), ("move_up", 0.2)]
for name, sp in tests:
    try:
        print(name, sp, "->", safe_move(agv, name, sp))
    except ValueError as e:
        print("  error:", e)
print("sent:", agv.sent)
풀이
python시뮬 실행 가능
LIMITS = {"move_forward": 1.5, "move_backward": 1.5,
          "move_left_lateral": 1.0, "move_right_lateral": 1.0,
          "turn_left": 1.0, "turn_right": 1.0}     # turn 상한은 교육용 가정
SAFE_MAX = 0.5                                     # 첫 시험 운전 상한 (내 규칙)

class Recorder:
    """보낸 명령만 기록하는 가짜 로봇"""
    def __init__(self):
        self.sent = []
    def __getattr__(self, name):
        return lambda *a: self.sent.append((name,) + a) or 1

def safe_move(agv, name, speed):
    if name not in LIMITS:
        raise ValueError(f"unknown command: {name}")
    hi = min(LIMITS[name], SAFE_MAX)
    v = min(max(float(speed), 0.0), hi)
    if v != speed:
        print(f"  warn: {name}({speed}) -> {v} (range 0~{hi})")
    getattr(agv, name)(v)
    return v

agv = Recorder()
tests = [("move_forward", 2.0), ("move_left_lateral", -0.3),
         ("turn_left", 0.3), ("move_up", 0.2)]
for name, sp in tests:
    try:
        print(name, sp, "->", safe_move(agv, name, sp))
    except ValueError as e:
        print("  error:", e)
print("sent:", agv.sent)
# sent: [('move_forward', 0.5), ('move_left_lateral', 0.0), ('turn_left', 0.3)]

음수 속도를 0 으로 자르는 것은 "반대로 가라" 는 뜻을 무시하는 것입니다. 실무에서는 경고 대신 ValueError 로 막는 편이 더 안전할 수 있습니다 — 어느 쪽이든 내 코드가 정한 규칙으로 처리된다는 점이 핵심입니다.

실습 2-1 · 1 m 시간 보정과 그 한계 (2교시)

시뮬레이터 2 와 같은 모델 drive() 가 주어집니다. 목표 1 m 에 맞는 T 를 반복 보정(T += (목표 − 실제) / v)으로 찾고, 그 T 를 그대로 둔 채 슬립 · 지연 비대칭 · 거리 3 배를 바꿔 보정이 깨지는지 확인하세요.

python시뮬 실행 가능
def drive(v, T, ta=0.3, td=0.1, lat_start=0.05, lat_stop=0.05, slip=0.0, dt=0.001):
    """시뮬레이터 2 와 같은 모델: move_forward(v) -> sleep(T) -> stop() 의 실제 이동 거리"""
    t, vel, pos = 0.0, 0.0, 0.0
    t_on, t_off = lat_start, T + lat_stop
    up = v / ta if ta > 0 else 1e9
    dn = v / td if td > 0 else 1e9
    while t < t_off + td + 1.0:
        target = v if t_on <= t < t_off else 0.0
        if vel < target:
            vel = min(target, vel + up * dt)
        elif vel > target:
            vel = max(target, vel - dn * dt)
        pos += (1 - slip) * vel * dt
        t += dt
    return pos

v, goal = 0.5, 1.0
T = goal / v
print(f"naive  T={T:.3f} s -> {drive(v, T):.3f} m")
for i in range(3):
    d = drive(v, T)
    # TODO: T 를 보정 (T += ...)
    print(f"iter {i + 1} T={T:.3f} s -> {drive(v, T):.3f} m")

print("--- same T, different floor / link ---")
# TODO: slip 0.0, 0.05, 0.10 에서 drive(v, T, slip=...) 출력
# TODO: (lat_start, lat_stop) = (0.05, 0.05), (0.02, 0.08), (0.08, 0.02) 출력
# TODO: 3 m 를 가려고 T * 3 을 쓰면?
풀이
python시뮬 실행 가능
def drive(v, T, ta=0.3, td=0.1, lat_start=0.05, lat_stop=0.05, slip=0.0, dt=0.001):
    """시뮬레이터 2 와 같은 모델: move_forward(v) -> sleep(T) -> stop() 의 실제 이동 거리"""
    t, vel, pos = 0.0, 0.0, 0.0
    t_on, t_off = lat_start, T + lat_stop
    up = v / ta if ta > 0 else 1e9
    dn = v / td if td > 0 else 1e9
    while t < t_off + td + 1.0:
        target = v if t_on <= t < t_off else 0.0
        if vel < target:
            vel = min(target, vel + up * dt)
        elif vel > target:
            vel = max(target, vel - dn * dt)
        pos += (1 - slip) * vel * dt
        t += dt
    return pos

v, goal = 0.5, 1.0
T = goal / v
print(f"naive  T={T:.3f} s -> {drive(v, T):.3f} m")
for i in range(3):
    d = drive(v, T)
    T += (goal - d) / v
    print(f"iter {i + 1} T={T:.3f} s -> {drive(v, T):.3f} m")

print("--- same T, different floor / link ---")
for slip in [0.0, 0.05, 0.10]:
    print(f"slip {slip:4.2f}: {drive(v, T, slip=slip):.3f} m")
for ls, le in [(0.05, 0.05), (0.02, 0.08), (0.08, 0.02)]:
    print(f"latency start {ls:.2f} stop {le:.2f}: {drive(v, T, lat_start=ls, lat_stop=le):.3f} m")
print("--- same T, 3 m goal by T*3 ---")
print(f"T*3={3*T:.3f} s -> {drive(v, 3*T):.3f} m (goal 3.000)")
# naive  T=2.000 s -> 0.950 m
# iter 1 T=2.099 s -> 1.000 m
# slip 0.10: 0.900 m
# latency start 0.02 stop 0.08: 1.030 m
# T*3=6.297 s -> 3.099 m (goal 3.000)

보정은 고정된 오차(가감속 비대칭 5 cm)만 지웁니다. 슬립은 거리에 비례해 커지고, 지연이 한쪽으로 치우치면 ±3 cm 가 생깁니다. T × 3 이 3 m 보다 10 cm 더 가는 이유도 같습니다 — 고정 오차를 메우려고 늘린 0.1 s 까지 3 배가 되어 버리기 때문입니다. 보정은 "비율" 이 아니라 "더하는 상수" 로 넣어야 합니다 (과제 2).

실습 2-2 · 어떤 경우에도 stop() 을 부르는 구조 (2교시)

deliver() 는 상자 수가 0 이면 ZeroDivisionError 로 죽습니다. run_unsafe 로 돌리면 로봇에 속도 명령이 남습니다. try / finally 로 run_safely() 를 완성해, 예외가 나도 stop() 이 반드시 호출되게 하세요.

python시뮬 실행 가능
class MiniAGV:
    def __init__(self):
        self.cmd, self.t = 0.0, 0.0
    def move_forward(self, v):
        self.cmd = v
        print(f"  t={self.t:4.1f}s move_forward({v})")
    def stop(self):
        self.cmd = 0.0
        print(f"  t={self.t:4.1f}s stop()")
    def wait(self, sec):
        self.t += sec

def deliver(agv, n_boxes):
    agv.move_forward(0.3)
    agv.wait(1.0)
    per_box = 10 / n_boxes        # n_boxes = 0 이면 ZeroDivisionError
    agv.wait(per_box)
    agv.stop()

def run_unsafe(agv, job, *args):
    job(agv, *args)

def run_safely(agv, job, *args):
    # TODO: try / finally 로 감싸서 agv.stop() 을 반드시 호출
    job(agv, *args)

for runner in (run_unsafe, run_safely):
    agv = MiniAGV()
    print(runner.__name__)
    try:
        runner(agv, deliver, 0)
    except ZeroDivisionError as e:
        print("  error:", e)
    print("  speed command left on robot:", agv.cmd)
풀이
python시뮬 실행 가능
class MiniAGV:
    def __init__(self):
        self.cmd, self.t = 0.0, 0.0
    def move_forward(self, v):
        self.cmd = v
        print(f"  t={self.t:4.1f}s move_forward({v})")
    def stop(self):
        self.cmd = 0.0
        print(f"  t={self.t:4.1f}s stop()")
    def wait(self, sec):
        self.t += sec

def deliver(agv, n_boxes):
    agv.move_forward(0.3)
    agv.wait(1.0)
    per_box = 10 / n_boxes        # n_boxes = 0 이면 ZeroDivisionError
    agv.wait(per_box)
    agv.stop()

def run_unsafe(agv, job, *args):
    job(agv, *args)

def run_safely(agv, job, *args):
    try:
        job(agv, *args)
    finally:
        agv.stop()                # 정상 종료든 예외든 반드시 실행

for runner in (run_unsafe, run_safely):
    agv = MiniAGV()
    print(runner.__name__)
    try:
        runner(agv, deliver, 0)
    except ZeroDivisionError as e:
        print("  error:", e)
    print("  speed command left on robot:", agv.cmd)
# run_unsafe ... speed command left on robot: 0.3
# run_safely ... stop() ... speed command left on robot: 0.0

finally 는 정상 종료 · 예외 · Ctrl+C(KeyboardInterrupt) 모두에서 실행됩니다. 단, 전원이 꺼지거나 케이블이 빠지는 경우는 막지 못하므로 비상정지 버튼 · 안전 타임아웃이 따로 필요합니다.

실습 3-1 · 자동 보고 메시지 대시보드 (3교시)

자동 보고 메시지 3 개를 한 줄짜리 대시보드로 바꿉니다. 기계 상태 · 모터 오류 목록에서 1 인 칸의 이름을 뽑고, 6번 칸(0 = Enabled)을 글자로 바꾸세요.

python시뮬 실행 가능
MACHINE = ["E-stop", "not started", "bumper1", "bumper2",
           "motor1 link", "motor2 link", "motor3 link", "motor4 link"]

samples = [
    [0.50, 0.00, 0.00, [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0], 25.8, 0],
    [0.00, 0.25, 0.00, [0, 0, 1, 0, 0, 0, 0, 0], [0, 0, 0, 0], 25.6, 0],
    [0.00, 0.00, 0.00, [1, 0, 0, 0, 0, 0, 0, 0], [0, 0, 1, 0], 24.1, 1],
]

def dashboard(msg):
    rx, ry, rw, machine, motor, batt, enable = msg
    alarms = []       # TODO: machine 에서 1 인 칸의 MACHINE 이름
    bad = []          # TODO: motor 에서 1 인 칸 -> "wheel1" ~ "wheel4"
    en = "?"          # TODO: enable == 0 이면 "ENABLED", 아니면 "DISABLED"
    status = "OK" if not alarms and not bad else "CHECK"
    return (f"[{status:5}] v=({rx:+.2f},{ry:+.2f},{rw:+.2f}) batt={batt:4.1f}V "
            f"motor={en:8} alarm={alarms or '-'} motor_err={bad or '-'}")

for i, m in enumerate(samples):
    print(i, dashboard(m))
풀이
python시뮬 실행 가능
MACHINE = ["E-stop", "not started", "bumper1", "bumper2",
           "motor1 link", "motor2 link", "motor3 link", "motor4 link"]

samples = [
    [0.50, 0.00, 0.00, [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0], 25.8, 0],
    [0.00, 0.25, 0.00, [0, 0, 1, 0, 0, 0, 0, 0], [0, 0, 0, 0], 25.6, 0],
    [0.00, 0.00, 0.00, [1, 0, 0, 0, 0, 0, 0, 0], [0, 0, 1, 0], 24.1, 1],
]

def dashboard(msg):
    rx, ry, rw, machine, motor, batt, enable = msg
    alarms = [MACHINE[i] for i, b in enumerate(machine) if b]
    bad = [f"wheel{i + 1}" for i, b in enumerate(motor) if b]
    en = "ENABLED" if enable == 0 else "DISABLED"     # 자동 보고: 0 = Enabled
    status = "OK" if not alarms and not bad else "CHECK"
    return (f"[{status:5}] v=({rx:+.2f},{ry:+.2f},{rw:+.2f}) batt={batt:4.1f}V "
            f"motor={en:8} alarm={alarms or '-'} motor_err={bad or '-'}")

for i, m in enumerate(samples):
    print(i, dashboard(m))
# 0 [OK   ] v=(+0.50,+0.00,+0.00) batt=25.8V motor=ENABLED  alarm=- motor_err=-
# 1 [CHECK] v=(+0.00,+0.25,+0.00) batt=25.6V motor=ENABLED  alarm=['bumper1'] motor_err=-
# 2 [CHECK] v=(+0.00,+0.00,+0.00) batt=24.1V motor=DISABLED alarm=['E-stop'] motor_err=['wheel3']

실물에서는 set_auto_report_state(1) 뒤 get_auto_report_message() 를 0.2 s 마다 읽어 이 함수로 출력하면 텍스트 대시보드가 됩니다 (아래 실물 실습).

실습 3-2 · 배터리 감시 루프 — 오탐 없이 멈추기 (3교시)

시뮬레이터 3 과 같은 모델로 만든 20 Hz 보고값 목록 make_trace() 가 주어집니다. monitor() 에 세 가지 판정 방식을 넣고, 각 방식이 언제 stop() 을 부르는지, 그때 휴지 전압이 임계보다 얼마나 높은지(rest-thr, 클수록 오탐)를 비교하세요.

python시뮬 실행 가능
OCV = [(0, 21.0), (5, 23.6), (10, 24.6), (20, 25.4), (30, 25.7),
       (50, 26.0), (70, 26.2), (90, 26.5), (100, 27.0)]       # 교육용 가정 곡선

def ocv(soc):
    for (s0, v0), (s1, v1) in zip(OCV, OCV[1:]):
        if soc <= s1:
            return v0 + (v1 - v0) * (soc - s0) / (s1 - s0)
    return OCV[-1][1]

def make_trace(load=50, vmax=1.5, soc=30.0, sec=120, R=0.12, K=60):
    """자동 보고(20 Hz)를 흉내 낸 (t, 속도, 배터리 전압, 휴지 전압) 목록 - 시뮬레이터 3 과 같은 모델"""
    m, a, mu, g = 40 + load, 1.0, 0.06, 9.81
    t_acc = vmax / a
    cycle = [(t_acc, "acc"), (3.0, "run"), (t_acc, "dec"), (2.0, "dwell")]
    out, t, dt = [], 0.0, 0.05
    while t < sec:
        tc = t % sum(d for d, _ in cycle)
        for d, ph in cycle:
            if tc < d:
                break
            tc -= d
        v = {"acc": a * tc, "run": vmax, "dec": vmax - a * tc, "dwell": 0.0}[ph]
        acc = {"acc": a, "dec": -a}.get(ph, 0.0)
        F = m * (acc + mu * g) if v > 0 else 0.0
        P = max(0.0, F * v) / 0.75 + 25
        I = P / ocv(soc)
        out.append((round(t, 2), v, ocv(soc) - I * R, ocv(soc)))
        soc -= I * dt * K / (20 * 3600) * 100
        t += dt
    return out

def monitor(trace, thr, mode, n=60):
    hist = []
    for t, v, volt, rest in trace:
        if mode == "raw":
            judged = volt
        elif mode == "avg":
            judged = volt     # TODO: 최근 n 개 평균 (hist 사용)
        else:                 # "idle"
            judged = volt     # TODO: 움직이는 중(v > 0)이면 판정하지 않고 건너뛰기
        if judged < thr:
            return t, judged, rest
    return None

trace = make_trace()
thr = 24.6
for mode in ["raw", "avg", "idle"]:
    r = monitor(trace, thr, mode)
    if r is None:
        print(f"{mode:5}: no stop in {trace[-1][0]:.0f} s")
    else:
        t, judged, rest = r
        print(f"{mode:5}: stop at t={t:6.2f}s judged={judged:5.2f}V "
              f"rest={rest:5.2f}V  rest-thr={rest - thr:+.2f}V")
풀이
python시뮬 실행 가능
OCV = [(0, 21.0), (5, 23.6), (10, 24.6), (20, 25.4), (30, 25.7),
       (50, 26.0), (70, 26.2), (90, 26.5), (100, 27.0)]       # 교육용 가정 곡선

def ocv(soc):
    for (s0, v0), (s1, v1) in zip(OCV, OCV[1:]):
        if soc <= s1:
            return v0 + (v1 - v0) * (soc - s0) / (s1 - s0)
    return OCV[-1][1]

def make_trace(load=50, vmax=1.5, soc=30.0, sec=120, R=0.12, K=60):
    """자동 보고(20 Hz)를 흉내 낸 (t, 속도, 배터리 전압, 휴지 전압) 목록 - 시뮬레이터 3 과 같은 모델"""
    m, a, mu, g = 40 + load, 1.0, 0.06, 9.81
    t_acc = vmax / a
    cycle = [(t_acc, "acc"), (3.0, "run"), (t_acc, "dec"), (2.0, "dwell")]
    out, t, dt = [], 0.0, 0.05
    while t < sec:
        tc = t % sum(d for d, _ in cycle)
        for d, ph in cycle:
            if tc < d:
                break
            tc -= d
        v = {"acc": a * tc, "run": vmax, "dec": vmax - a * tc, "dwell": 0.0}[ph]
        acc = {"acc": a, "dec": -a}.get(ph, 0.0)
        F = m * (acc + mu * g) if v > 0 else 0.0
        P = max(0.0, F * v) / 0.75 + 25
        I = P / ocv(soc)
        out.append((round(t, 2), v, ocv(soc) - I * R, ocv(soc)))
        soc -= I * dt * K / (20 * 3600) * 100
        t += dt
    return out

def monitor(trace, thr, mode, n=60):
    hist = []
    for t, v, volt, rest in trace:
        if mode == "raw":
            judged = volt
        elif mode == "avg":
            hist = (hist + [volt])[-n:]
            judged = sum(hist) / len(hist)
        else:                           # "idle": 서 있을 때 읽은 값만 판정
            if v > 0:
                continue
            judged = volt
        if judged < thr:
            return t, judged, rest
    return None

trace = make_trace()
thr = 24.6
for mode in ["raw", "avg", "idle"]:
    r = monitor(trace, thr, mode)
    if r is None:
        print(f"{mode:5}: no stop in {trace[-1][0]:.0f} s")
    else:
        t, judged, rest = r
        print(f"{mode:5}: stop at t={t:6.2f}s judged={judged:5.2f}V "
              f"rest={rest:5.2f}V  rest-thr={rest - thr:+.2f}V")
# raw  : stop at t=  1.10s judged=24.59V rest=25.69V  rest-thr=+1.09V
# avg  : stop at t= 42.40s judged=24.59V rest=25.15V  rest-thr=+0.55V
# idle : stop at t= 62.05s judged=24.55V rest=24.67V  rest-thr=+0.07V

원시값은 첫 가속에서 바로 멈추고(1 V 넘는 오탐), 3 s 평균은 처짐을 절반쯤 거르지만 여전히 이릅니다. 정차 중 판정이 휴지 전압과 0.07 V 차이로 가장 정확합니다. 실물에서는 stop() 과 함께 LED 를 빨강으로 바꿔 사람에게 알립니다.

실습 4-1 · 라이트 커튼 정지 · 재출발 상태 머신 (4교시)

입력 1번(라이트 커튼: 1 = 정상, 0 = 차단)이 끊기면 정지 + 빨간 LED + 경광등(출력 1번), 10 번 연속(약 1 s) 정상이면 파란 LED 로 재출발하는 step() 을 완성합니다. 시간표에는 2.3 ~ 2.6 s 에 잠깐 복구되는 구간이 있습니다. 이때 재출발하면 안 됩니다.

python시뮬 실행 가능
GREEN, BLUE, RED = (0, 255, 0), (0, 0, 255), (255, 0, 0)

class FakeIO:
    """입력 핀 1 을 시간표대로 바꾸고, 보낸 명령을 기록하는 가짜 로봇"""
    def __init__(self, curtain):
        self.curtain, self.t = curtain, 0.0      # curtain: [(시각, 값), ...]
    def get_pin_input(self, pin):
        val = 1
        for t0, v in self.curtain:
            if self.t >= t0:
                val = v
        return val if pin == 1 else 0
    def _log(self, s):
        print(f"t={self.t:4.1f}s  {s}")
    def set_led_color(self, pos, bri, rgb): self._log(f"set_led_color({pos}, {bri}, {rgb})")
    def set_pin_output(self, pin, st):      self._log(f"set_pin_output({pin}, {st})")
    def move_forward(self, v):              self._log(f"move_forward({v})")
    def stop(self):                         self._log("stop()")

def leds(agv, rgb):
    agv.set_led_color(0, 255, rgb)
    agv.set_led_color(1, 255, rgb)

def step(agv, state, curtain_ok, clear_n, restart_n=10):
    """한 번의 폴링. curtain_ok: 1 = 빛 통과(정상), 0 = 차단
    clear_n: 연속으로 '정상' 을 읽은 횟수. restart_n 번 연속이면 재출발"""
    if state == "MOVING" and not curtain_ok:
        # TODO: stop, 빨간 LED, 경광등(출력 1번) 켜기
        return "BLOCKED"
    if state == "BLOCKED" and clear_n >= restart_n:
        # TODO: 경광등 끄기, 파란 LED, move_forward(0.5)
        return "MOVING"
    if state == "IDLE" and curtain_ok:
        leds(agv, BLUE)
        agv.move_forward(0.5)
        return "MOVING"
    return state

agv = FakeIO(curtain=[(2.0, 0), (2.3, 1), (2.6, 0), (3.5, 1)])
state, clear_n, period = "IDLE", 0, 0.1
leds(agv, GREEN)
for k in range(61):                          # 0 ~ 6 s, 0.1 s 마다 폴링
    agv.t = k * period
    ok = agv.get_pin_input(1)
    clear_n = clear_n + 1 if ok else 0
    state = step(agv, state, ok, clear_n)
agv.stop()
leds(agv, GREEN)
print("final state:", state)
풀이
python시뮬 실행 가능
GREEN, BLUE, RED = (0, 255, 0), (0, 0, 255), (255, 0, 0)

class FakeIO:
    """입력 핀 1 을 시간표대로 바꾸고, 보낸 명령을 기록하는 가짜 로봇"""
    def __init__(self, curtain):
        self.curtain, self.t = curtain, 0.0      # curtain: [(시각, 값), ...]
    def get_pin_input(self, pin):
        val = 1
        for t0, v in self.curtain:
            if self.t >= t0:
                val = v
        return val if pin == 1 else 0
    def _log(self, s):
        print(f"t={self.t:4.1f}s  {s}")
    def set_led_color(self, pos, bri, rgb): self._log(f"set_led_color({pos}, {bri}, {rgb})")
    def set_pin_output(self, pin, st):      self._log(f"set_pin_output({pin}, {st})")
    def move_forward(self, v):              self._log(f"move_forward({v})")
    def stop(self):                         self._log("stop()")

def leds(agv, rgb):
    agv.set_led_color(0, 255, rgb)
    agv.set_led_color(1, 255, rgb)

def step(agv, state, curtain_ok, clear_n, restart_n=10):
    """한 번의 폴링. curtain_ok: 1 = 빛 통과(정상), 0 = 차단
    clear_n: 연속으로 '정상' 을 읽은 횟수. restart_n 번 연속이면 재출발"""
    if state == "MOVING" and not curtain_ok:
        agv.stop()
        leds(agv, RED)
        agv.set_pin_output(1, 1)            # 경광등 켬
        return "BLOCKED"
    if state == "BLOCKED" and clear_n >= restart_n:
        agv.set_pin_output(1, 0)
        leds(agv, BLUE)
        agv.move_forward(0.5)
        return "MOVING"
    if state == "IDLE" and curtain_ok:
        leds(agv, BLUE)
        agv.move_forward(0.5)
        return "MOVING"
    return state

agv = FakeIO(curtain=[(2.0, 0), (2.3, 1), (2.6, 0), (3.5, 1)])
state, clear_n, period = "IDLE", 0, 0.1
leds(agv, GREEN)
for k in range(61):                          # 0 ~ 6 s, 0.1 s 마다 폴링
    agv.t = k * period
    ok = agv.get_pin_input(1)
    clear_n = clear_n + 1 if ok else 0
    state = step(agv, state, ok, clear_n)
agv.stop()
leds(agv, GREEN)
print("final state:", state)
# t= 2.0s  stop() -> 빨강 -> set_pin_output(1, 1)
# (2.3 ~ 2.6 s 의 짧은 복구는 무시)
# t= 4.4s  set_pin_output(1, 0) -> 파랑 -> move_forward(0.5)

3.5 s 에 복구된 뒤 10 번째 연속 정상 읽기(4.4 s)에서 재출발합니다. clear_n 하나가 디바운스와 "복구 후 대기" 를 함께 해 줍니다. 시뮬레이터 4 의 "1 s 연속 정상이면 자동" 과 같은 규칙입니다.

실습 4-2 · 출발 전 점검 함수 (4교시)

"전원 미투입 상태 명령" 같은 조용한 실패를 막기 위해, 이동 전에 비상정지 · 전원 · 모터 상태 · 통신 모드를 확인해 문제 목록을 돌려주는 precheck() 를 만듭니다. 모터 상태 코드는 비트 묶음입니다 (예: 8 = 0b1000 → 3번 비트 = 과열).

python시뮬 실행 가능
class FakeAGV:
    def __init__(self, power=1, estop=0, motor=(0, 0, 0, 0), comm=0):
        self.power, self.estop, self.motor, self.comm = power, estop, list(motor), comm
    def is_power_on(self):           return self.power
    def get_estop_state(self):       return self.estop
    def get_motor_status(self):      return self.motor
    def get_communication_state(self): return self.comm

MOTOR_BITS = {1: "under-voltage", 2: "driver", 3: "overheat",
              4: "encoder", 5: "overload", 6: "uncalibrated"}

def precheck(agv):
    problems = []
    # TODO 1: get_estop_state() == 1 이면 문제 추가
    # TODO 2: is_power_on() != 1 이면 문제 추가
    # TODO 3: get_motor_status() 의 각 코드에서 켜진 비트 이름 찾기 (code >> b & 1)
    # TODO 4: get_communication_state() != 0 이면 문제 추가
    return problems

cases = {
    "normal": FakeAGV(),
    "after boot": FakeAGV(power=0),
    "estop + hot motor": FakeAGV(estop=1, motor=(0, 8, 0, 0)),
    "socket mode": FakeAGV(comm=1),
}
for name, agv in cases.items():
    p = precheck(agv)
    print(f"{name:18}: {'READY' if not p else 'NOT READY'}")
    for msg in p:
        print("   -", msg)
풀이
python시뮬 실행 가능
class FakeAGV:
    def __init__(self, power=1, estop=0, motor=(0, 0, 0, 0), comm=0):
        self.power, self.estop, self.motor, self.comm = power, estop, list(motor), comm
    def is_power_on(self):           return self.power
    def get_estop_state(self):       return self.estop
    def get_motor_status(self):      return self.motor
    def get_communication_state(self): return self.comm

MOTOR_BITS = {1: "under-voltage", 2: "driver", 3: "overheat",
              4: "encoder", 5: "overload", 6: "uncalibrated"}

def precheck(agv):
    problems = []
    if agv.get_estop_state() == 1:
        problems.append("E-stop pressed: release it after checking the area")
    if agv.is_power_on() != 1:
        problems.append("power off: call power_on() (motion commands do nothing)")
    for i, code in enumerate(agv.get_motor_status()):
        if code:
            names = [n for b, n in MOTOR_BITS.items() if code >> b & 1]
            problems.append(f"motor {i + 1} error code {code} {names}")
    if agv.get_communication_state() != 0:
        problems.append("comm mode is not serial(0): serial replies may not come")
    return problems

cases = {
    "normal": FakeAGV(),
    "after boot": FakeAGV(power=0),
    "estop + hot motor": FakeAGV(estop=1, motor=(0, 8, 0, 0)),
    "socket mode": FakeAGV(comm=1),
}
for name, agv in cases.items():
    p = precheck(agv)
    print(f"{name:18}: {'READY' if not p else 'NOT READY'}")
    for msg in p:
        print("   -", msg)

비트 번호 해석(1 = 저전압, 2 = 드라이버, 3 = 과열 …)은 공식 프로토콜 설명을 따랐습니다. 펌웨어 버전에 따라 다를 수 있으니 실물에서 비상정지를 일부러 눌러 보며 값이 어떻게 바뀌는지 확인하세요.

창고 시뮬레이터에서 진짜 API 로#

이제 대역 클래스 없이 실물과 같은 코드를 씁니다. Playground 의 타깃을 Simulator 로 두면 오른쪽에 3D 창고가 뜨고, MyAGVPro 의 명령이 그 로봇으로 갑니다. 시뮬레이터에는 가속 한계(기본 1.0 m/s²) · 라이다 보호 영역(0.35 m 정지 · 0.8 m 감속) · 배터리 전압 처짐이 들어 있습니다 (모두 교육용 가정, 실물 값은 확인 필요). agvsim 모듈은 참값 위치처럼 실물에는 없는 정보를 읽는 시뮬레이터 전용 도구입니다.

Playground (시뮬레이터 타깃) 열기

시뮬레이터만 따로 열기 (키보드 운전 · IO 버튼)

실습 5-1 · 1 m 를 정말 갔을까 (2교시 복습)

먼저 예측하세요. move_forward(0.5) 후 time.sleep(2.0) 이면 몇 m 갈까요? 가속 1.0 m/s² 이 있다면 더 짧을까요, 길까요? stop() 뒤에도 감속하며 조금 더 가는 것까지 생각해 보세요.

python시뮬 실행 가능
from pymycobot import MyAGVPro
import agvsim, time

agv = MyAGVPro("/dev/agvpro_controller", baudrate=1000000)
agvsim.set_pose(0, 0, 0)

if agv.get_estop_state() == 1:
    raise SystemExit("E-stop pressed")
if agv.is_power_on() != 1:
    print("power_on:", agv.power_on())

try:
    agv.move_forward(0.5)
    time.sleep(2.0)
finally:
    agv.stop()
time.sleep(1.0)                      # 감속이 끝날 때까지
x, y, th = agvsim.get_pose()         # 참값 (실물에서는 줄자로 잽니다)
print(f"moved x = {x:.3f} m  (target 1.000 m)")
# TODO: 1.000 m 에 맞도록 sleep 시간을 바꿔 보고, 속도 1.0 m/s 에서도 같은 보정이 맞는지 확인
풀이 · 해설가속 0.5 s 동안 0.125 m 를 덜 가고, 정지 뒤 감속 0.5 s 동안 0.125 m 를 더 가서 1.00 m 에 가깝게 나옵니다 — 가속과 감속이 대칭이면 서로 상쇄됩니다. 여기에 명령 전달 지연(브라우저 · 통신)이 더해져 몇 cm 씩 흔들리는 것도 관찰하세요. 보호 영역 감속이나 미끄러짐(ch04)이 끼면 이 상쇄는 더 이상 맞지 않습니다. 2교시의 "보정값은 그 조건에서만 맞는다" 를 숫자로 확인하세요.
실습 5-2 · 자동 보고로 속도와 전압 읽기 (3교시 복습)

get_auto_report_message() 의 7 칸을 이름 붙은 변수로 풀고, 가속 중 · 정속 중 · 정지 후의 rx 와 배터리 전압을 비교합니다.

python시뮬 실행 가능
from pymycobot import MyAGVPro
import time

agv = MyAGVPro("/dev/agvpro_controller", baudrate=1000000)
if agv.is_power_on() != 1:
    agv.power_on()
agv.set_auto_report_state(1)

def report(tag):
    rx, ry, rw, machine, motor, volt, enable = agv.get_auto_report_message()
    print(f"{tag:8} rx={rx:+.2f} ry={ry:+.2f} rw={rw:+.2f}  V={volt:.1f}  estop={machine[0]} enable={'ON' if enable == 0 else 'OFF'}")

report("rest")
agv.move_forward(1.2)
for k in range(6):
    time.sleep(0.25)
    report(f"t={0.25 * (k + 1):.2f}")
agv.stop()
time.sleep(1.5)
report("stopped")

관찰할 것: rx 는 명령 1.2 로 바로 뛰지 않고 오릅니다. 전압은 달리는 동안 처졌다가 멈추면 되돌아옵니다 — 3교시 "전압 < 임계값이면 정지" 규칙이 왜 위험한지 그대로 보입니다. (빈 바닥 장면에서 실행하세요. 앞에 벽이 있으면 보호 영역이 속도를 줄입니다.)

실습 5-3 · 라이트 커튼 상태 머신을 시뮬레이터 IO 로 (4교시 복습)

시뮬레이터를 새 탭으로 열고(Playground 의 시뮬 위치 → 새 탭), 패널의 IN1 버튼을 라이트 커튼이라고 생각합니다 (1 = 통과 가능, 0 = 차단). 아래 코드를 실행하는 동안 IN1 을 눌러 0 으로 바꿔 보세요. 차단 → 정지 · 빨강 LED, 해제 후 0.5 s 연속 통과 → 재출발 · 파랑 LED 가 되어야 합니다.

python시뮬 실행 가능
from pymycobot import MyAGVPro
import time

agv = MyAGVPro("/dev/agvpro_controller", baudrate=1000000)
if agv.is_power_on() != 1:
    agv.power_on()

GREEN, BLUE, RED = (0, 255, 0), (0, 0, 255), (255, 0, 0)
def leds(c):
    agv.set_led_color(0, 255, c)
    agv.set_led_color(1, 255, c)

PERIOD, NEED = 0.1, 5                 # 0.1 s 폴링, 5 번 연속 통과면 재출발
state, clear_n = "MOVING", 0
agv.move_forward(0.2)
leds(BLUE)
t0 = time.time()
try:
    while time.time() - t0 < 20:
        ok = agv.get_pin_input(1)
        clear_n = clear_n + 1 if ok == 1 else 0
        if state == "MOVING" and ok == 0:
            agv.stop(); leds(RED); state = "BLOCKED"
            print(f"{time.time() - t0:5.1f}s BLOCKED")
        elif state == "BLOCKED" and clear_n >= NEED:
            agv.move_forward(0.2); leds(BLUE); state = "MOVING"
            print(f"{time.time() - t0:5.1f}s MOVING again")
        time.sleep(PERIOD)
finally:
    agv.stop()
    leds(GREEN)

내장 시뮬레이터(이 페이지 안)에서는 IO 버튼이 보이지 않으므로, 대신 코드 안에서 import agvsim 후 agvsim.set_pin_input(1, 0) 으로 커튼을 가릴 수 있습니다.

실습 (실물)#

실물 구동 전 안전 확인

PC 에 pip install pymycobot --upgrade 로 설치하고 직렬로 연결합니다. 로봇 내장 컴퓨터에서는 /dev/agvpro_controller, PC 에서는 /dev/ttyACM0 (Windows: COM3 등)를 씁니다.

python실물 전용
import time
from pymycobot import MyAGVPro

SAFE_MAX = 0.2
agv = MyAGVPro("/dev/agvpro_controller", baudrate=1000000, debug=False)

def leds(rgb):
    agv.set_led_color(0, 255, rgb)
    agv.set_led_color(1, 255, rgb)

def move_for(name, speed, sec):
    speed = min(max(speed, 0.0), SAFE_MAX)
    getattr(agv, name)(speed)
    time.sleep(sec)
    agv.stop()
    time.sleep(0.5)

try:
    assert agv.get_estop_state() == 0, "E-stop pressed"
    if agv.is_power_on() != 1:
        agv.power_on()
    agv.set_auto_report_state(1)
    leds((0, 0, 255))
    move_for("move_forward", 0.2, 1.0)        # 약 0.2 m
    move_for("move_left_lateral", 0.2, 1.0)   # 약 0.2 m
    move_for("turn_left", 0.2, 1.0)           # 회전각을 재서 단위 확인
    print("report:", agv.get_auto_report_message())
    print("speeds:", agv.get_motor_speeds(), "temps:", agv.get_motor_temps())
    print("loss:", agv.get_motor_loss_count(), "status:", agv.get_motor_status())
finally:
    agv.stop()
    leds((0, 255, 0))

실물에서 해 볼 것:

  1. 바닥에 테이프로 출발선을 표시하고 move_forward(0.2) · 1 s 의 실제 거리를 줄자로 5 번 잽니다. 평균과 퍼짐을 시뮬레이터 2 의 점들과 비교합니다.
  2. turn_left(0.2) · 1 s 의 회전각을 재서 회전 인자의 단위를 확인합니다 (약 11.5° 면 rad/s).
  3. 실습 3-1 의 dashboard() 를 붙여 0.2 s 마다 10 번 출력합니다. 정지 중 · 주행 중 배터리 전압 차이를 기록합니다.
  4. (IO 배선이 준비된 경우) 입력 1번에 스위치를 연결하고, 실습 4-1 의 상태 머신을 FakeIO 대신 agv 로 돌립니다.

무선으로 바꿀 때 (공식 문서의 순서):

python실물 전용
from pymycobot import MyAGVPro, MyAGVProSocket

agv = MyAGVPro("/dev/ttyACM0", baudrate=1000000)
print(agv.get_wifi_account(), agv.get_wifi_ip_port())   # AP 이름 · 비밀번호 · (ip, port)
agv.set_communication_state(1)                          # 0 직렬, 1 소켓, 2 블루투스

# PC 를 로봇 AP 에 접속한 뒤, 위에서 읽은 값으로
agv = MyAGVProSocket("192.168.4.1", 9000)
print(agv.is_power_on())

자주 나는 오류와 해결#

1) 포트를 열 수 없음 (권한)#

text
serial.serialutil.SerialException: [Errno 13] could not open port /dev/ttyACM0: [Errno 13] Permission denied: '/dev/ttyACM0'
  • 원인: 리눅스에서 일반 사용자는 직렬 포트 접근 권한이 없습니다. 또는 다른 프로그램(ROS 2 드라이버, 시리얼 모니터)이 포트를 쓰고 있습니다.
  • 해결: sudo usermod -aG dialout $USER 후 다시 로그인합니다. 포트를 쓰는 다른 프로세스를 끕니다 (fuser /dev/ttyACM0). sudo python 으로 우회하지 않습니다.

2) 포트 이름이 없음#

text
serial.serialutil.SerialException: [Errno 2] could not open port /dev/agvpro_controller: [Errno 2] No such file or directory: '/dev/agvpro_controller'
  • 원인: /dev/agvpro_controller 는 로봇 내장 컴퓨터에 설정된 이름입니다. PC 에서는 /dev/ttyACM0, CH340 드라이버를 쓰면 /dev/ttyCH341USB0 (Windows 는 COM3 등)으로 잡힙니다. 충전 전용 케이블이어도 이 오류가 납니다.
  • 해결: ls /dev/ttyACM* /dev/ttyCH341USB* (Windows: 장치 관리자 → 포트)로 실제 이름을 찾습니다. 장치가 안 보이면 공식 문서 4.1 의 CH340 드라이버 설치 절차를 따릅니다. 데이터용 USB-C 케이블인지 확인합니다.

3) 응답이 없거나 값이 이상함 (baudrate · 통신 모드)#

text
>>> agv.is_power_on()
None
  • 원인: baudrate 를 1000000 이 아닌 값(예: 115200)으로 열었거나, 통신 모드를 소켓(1)으로 바꾼 뒤 직렬로 명령을 보내고 있습니다. 응답이 없을 때의 반환값 모양은 라이브러리 버전에 따라 다를 수 있습니다 (확인 필요).
  • 해결: baudrate=1000000 으로 다시 엽니다. 무선으로 바꾼 적이 있다면 MyAGVProSocket 으로 접속해 set_communication_state(0) 으로 되돌립니다.

4) 명령은 보냈는데 로봇이 안 움직임 (전원 미투입)#

text
>>> agv.move_forward(0.3)
>>> agv.is_power_on()
0
  • 원인: power_on() 을 부르지 않았거나 비상정지가 눌려 있습니다. 오류 없이 조용히 무시됩니다 (시뮬레이터 1 의 체크 끄기).
  • 해결: 실습 4-2 의 precheck() 를 프로그램 맨 앞에 둡니다. 비상정지는 주변을 확인한 뒤 해제하고 power_on() 합니다.

5) 프로그램이 오류로 끝났는데 로봇이 계속 달림#

text
Traceback (most recent call last):
  File "deliver.py", line 12, in <module>
ZeroDivisionError: division by zero
  • 원인: 이동 명령은 속도를 걸어 두는 명령이라, 예외로 프로그램이 끝나도 마지막 속도가 남습니다.
  • 해결: 즉시 비상정지 버튼. 코드는 try / finally: agv.stop() 구조로 고칩니다 (실습 2-2).

6) 같은 코드인데 매번 거리가 다름#

text
run 1: 0.97 m   run 2: 1.02 m   run 3: 0.95 m   (target 1.00 m)
  • 원인: 열린 루프 제어의 한계입니다. 가감속 · 지연 흔들림 · 슬립을 프로그램이 모릅니다.
  • 해결: 짧은 거리 · 낮은 속도에서 T 를 보정하되, 보정값은 그 조건에서만 맞는다고 기록해 둡니다. 정확한 위치가 필요하면 실제 이동을 재는 방법(ch04 오도메트리)으로 넘어갑니다.

7) MyAGVPro 를 가져올 수 없음#

text
ImportError: cannot import name 'MyAGVPro' from 'pymycobot'
  • 원인: 설치된 pymycobot 이 오래되어 MyAGVPro 클래스가 없습니다. 또는 내 파일 이름을 pymycobot.py 로 저장해 라이브러리를 가렸습니다.
  • 해결: pip install pymycobot --upgrade 후 pip show pymycobot 으로 버전을 확인합니다. 내 파일 이름을 바꿉니다.

8) 로봇이 갑자기 멈췄고 이유를 모름 (기계 상태 · 모터 오류 코드)#

text
>>> agv.get_robot_status()
[0, 0, 1, 0, 0, 0, 0, 0]
>>> agv.get_motor_status()
[0, 8, 0, 0]
  • 원인: 공식 문서(5.5.1 예외 정보)는 이상이 생기면 get_robot_status() 와 get_motor_status() 로 원인을 읽으라고 안내합니다. 기계 상태는 비트 8 개이고 0 = 정상, 1 = 이상 입니다.
비트01234 ~ 7
뜻비상정지미기동(전원 안 켜짐)범퍼 1범퍼 2모터 1 ~ 4 연결 끊김
  • 모터 상태는 바퀴마다 오류 비트입니다: bit1 저전압 · bit2 드라이버 이상 · bit3 과열 · bit4 자기 엔코더 이상 · bit5 과부하 · bit6 미보정 (6.3.1). 위 예의 8 = 이진 1000 = bit3 → 2번 모터 과열.
  • 해결: 범퍼(비트 2 · 3)는 장애물을 치운 뒤 다시 출발합니다. 과열은 식힌 뒤 적재 · 가속을 줄입니다. 반환 목록의 모양은 펌웨어 · 라이브러리 버전에 따라 다를 수 있으니(get_robot_status 는 6.1.2 API 목록에 없음) 정상일 때 한 번 출력해 두고 비교합니다. 시뮬레이터에서 벽에 부딪히면 범퍼 비트가 1 이 되는 것을 확인할 수 있습니다.

과제#

  1. 명령 카드: 시뮬레이터 1 에서 "앞 1 m → 왼쪽 0.5 m → 90° → 정지" 를 만든 뒤, 각 줄의 vx · vy · ω 를 표로 적고 stop() 을 뺐을 때와 오류 모드에서 일어나는 일을 한 문장씩 적습니다.
  2. 보정식: 실습 2-1 을 확장해 속도 0.3 · 0.5 · 1.0 m/s 와 거리 1 · 2 · 3 m 에서 맞는 T 를 구하고, T = d / v + c 꼴로 정리해 상수 c 가 무엇을 뜻하는지(가감속 시간과의 관계) 설명합니다.
  3. 감시 규칙 설계서: 실습 3-2 의 세 방식을 표로 비교하고(멈춘 시각, rest − thr), 정차가 드문 긴 통로 현장이라면 어떤 규칙을 쓸지 근거와 함께 3줄로 씁니다.
  4. IO 배선표: 입력 1 ~ 6, 출력 1 ~ 6 에 무엇을 연결할지 표를 만들고, 각 안전 신호가 fail-safe(1 = 안전)인지 표시합니다. 시뮬레이터 4 에서 고른 폴링 주기 · 디바운스 값과 그때의 최악 반응 거리를 함께 적습니다.

참고자료#

  • myAGV Pro 공식 문서: https://docs.elephantrobotics.com/docs/myAGV_Pro_en/
    • Python API (이동 · 상태 · LED · IO 함수와 범위): https://docs.elephantrobotics.com/docs/myAGV_Pro_en/6-SDKDevelopment/6.1-ApplicationBasePython/6.1.2-API.html
    • Python 환경 설치 · 예제: https://docs.elephantrobotics.com/docs/myAGV_Pro_en/6-SDKDevelopment/6.1-ApplicationBasePython/6.1.1-download.html
    • 직렬 통신 프로토콜 (1 000 000 bps, 자동 보고 20 Hz, 상태 비트): https://docs.elephantrobotics.com/docs/myAGV_Pro_en/6-SDKDevelopment/6.3-ApplicationBaseSerialPortProtocol/6.3.1-Protocol_Introduction.html
  • pymycobot 저장소: https://github.com/elephantrobotics/pymycobot
  • ROS 2 패키지: https://github.com/elephantrobotics/agv_pro_ros2
  • 제품 페이지: https://www.elephantrobotics.com/en/myagv-pro/
  • 제품 소개 · 이미지 (현영이앤씨): https://www.hyenc.net/products/36
  • pyserial 문서 (포트 · 예외): https://pyserial.readthedocs.io/
  • Python try 문 (finally): https://docs.python.org/3/reference/compound_stmts.html#the-try-statement
    • 예외 정보 조회: https://docs.elephantrobotics.com/docs/myAGV_Pro_en/5-BasicApplication/5.5-ExceptionInformation/5.5.1-ExceptionInformation.html
  • 공식 문서 원본 저장소: https://github.com/elephantrobotics/myagvPro_docs/tree/main/MYAGV_PRO_EN
  • 이 사이트의 도구: Playground · 물류창고 시뮬레이터
  • 앞 차시: ch02 전방향 휠 기구학 · 다음 차시: ch04 오도메트리 — 바퀴로 위치를 세다