pyaidrone 2.8__tar.gz → 2.9__tar.gz

{pyaidrone-2.8 → pyaidrone-2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyaidrone
-Version: 2.8
+Version: 2.9
 Summary: Library for AIDrone Products
 Home-page: http://www.ir-brain.com
 Author: IR-Brain

pyaidrone-2.9/pyaidrone/aiDrone.py

@@ -0,0 +1,685 @@
+# -*- coding: utf-8 -*-
+"""
+pyaidrone.aiDrone — AIDrone 제어 클래스
+
+수정 이력 (v1.0)
+  [치명] takeoff()가 posX/posY/rot 및 ROLL/PITCH/YAW 필드를 초기화하지 않아
+         "이륙 -> 이동 -> 착륙 -> 재이륙" 시 이전 좌표로 즉시 돌진하던 문제 수정.
+  [치명] velocity()와 move()가 서로 반대 축을 갱신하지 않아, POSTYPE 비트가 바뀌는
+         순간 잔류값이 거리<->속도로 오해석되던 문제 수정.
+  [중요] 송신을 수신 루프에 종속시키던 구조를 분리. 전용 송신 스레드(기본 20Hz).
+  [중요] rotation() 각도 정규화가 1회 가감뿐이라 범위를 벗어나던 문제 -> 모듈러 연산.
+  [중요] altitude()/move()/velocity() 범위 제한 추가 (OverflowError 방지).
+  [중요] emergency()의 serial None 검사 추가.
+  [개선] class AIDrone(Parse, Packet) 다중 상속 제거. 합성만 사용.
+  [개선] Open() 자동 탐색에서 첫 번째 CH340 포트를 선택하도록 break 추가.
+  [추가] TYPE 5/6/7/8 및 PID 설정 API.
+  [추가] stop(), hovering(), getFrame() 편의 메서드.
+
+수정 이력 (v1.0 → v1.1)
+  [치명] _sendCommand()가 명령을 1회만 전송했다. 송신 스레드가 20Hz로 제어 패킷을
+         계속 흘리는 중이라 명령이 그 사이에 끼어 유실되는 일이 잦았다.
+         (재현: 20Hz 스트림 중 TYPE9 요청이 CTRL 사이에 1개만 삽입됨)
+         -> 명령 전송 동안 송신 스레드를 잠시 멈추고(_txPaused), 30ms 간격으로
+            3회 반복 전송한다. 이제 비행 중에도 txHz를 낮출 필요가 없다.
+  [치명] Close()가 센서 출력을 멈추지 않아, 프로그램을 끝내도 드론이 계속 출력
+         패킷을 쏟아냈다. 다음 실행 때 이전 스트림이 남아 진단을 어렵게 했다.
+         -> Close()에서 stopSensor()를 먼저 호출한다.
+  [중요] Open()을 두 번 호출하면 스레드가 중복 생성되고 이전 포트가 누수됐다.
+         -> 이미 열려 있으면 경고 후 무시. 열 때 입력 버퍼를 비운다.
+  [중요] Close() 후에도 수신 스레드가 self.serial=None 을 참조해 예외 메시지를
+         뿜던 문제 -> 루프 진입 시 연결 상태를 검사하고, 스레드를 join 한다.
+  [중요] emergency()가 간격 없이 3회를 연속 write 해 드라이버 버퍼에 뭉쳐 나갔다.
+         -> 짧은 간격을 둔다.
+  [추가] 내장 센서. AIDrone(sensor=True) 로 생성하면 콜백을 직접 쓰지 않아도
+         getBattery() / getAttitude() / getState() 로 값을 읽을 수 있다.
+         (수업에서 스레드·콜백 개념 없이 센서 실습을 시키기 위한 것)
+  [추가] startSensor() / stopSensor() — 요청 후 실제로 데이터가 오는지 확인한다.
+  [추가] disarm() — ARM 해제 수단이 emergency() 뿐이라 수업에서 쓰기 부담스러웠다.
+  [추가] waitReady() — OPT1 bit1(비행 준비) 폴링.
+  [추가] setTxRate() — 송신 주기 변경.
+"""
+
+import serial
+from time import sleep, time
+from threading import Thread, Lock, Event
+from contextlib import contextmanager
+from serial.tools.list_ports import comports
+
+from pyaidrone.parse import Parse
+from pyaidrone.packet import Packet
+from pyaidrone.sensor import AIDroneSensor
+from pyaidrone.deflib import *
+
+
+class AIDrone:
+    """AIDrone 제어 객체.
+
+    사용 흐름 (기존):
+        aidrone = AIDrone(receiveCallback)
+        aidrone.Open("COM3")
+        ...
+        aidrone.Close()
+
+    사용 흐름 (v1.1 내장 센서):
+        with AIDrone(sensor=True) as aidrone:
+            aidrone.Open("COM3")
+            aidrone.startSensor()
+            print(aidrone.getBattery(), aidrone.getAttitude())
+    """
+
+    CMD_REPEAT = 3       # 명령 패킷 반복 전송 횟수
+    CMD_GAP = 0.03       # 반복 간격(초)
+
+    def __init__(self, receiveCallback=None, txHz=20, sensor=False):
+        self.serial = None
+        self.isThreadRun = False
+        self.parse = Parse(AIDRONE)
+        self.makepkt = Packet(AIDRONE)
+        self.receiveCallback = receiveCallback
+
+        # [v1.1 추가] 내장 센서. sensor=True 면 콜백 없이도 값을 읽을 수 있다.
+        self.sensor = AIDroneSensor() if sensor else None
+        self._sensorTypes = set()      # 현재 출력 요청 중인 TYPE 목록
+
+        self._lock = Lock()
+        self._txPeriod = 1.0 / max(1.0, float(txHz))
+        self._txEnabled = Event()
+        self._txEnabled.set()
+        self._rxThread = None
+        self._txThread = None
+
+        # 내부 좌표 (이륙 지점 기준 절대 위치)
+        self.posX = 0
+        self.posY = 0
+        self.rot = 0
+
+        # 영상 스트리밍 기본값
+        self.stream_host = "192.168.4.1"
+        self.stream_port = 80
+        self.stream_path = "/?action=stream"
+        self._cap = None
+
+    # ==================================================================
+    # 연결 / 해제
+    # ==================================================================
+    def Open(self, portName=None):
+        """시리얼 포트를 19200bps로 열고 송·수신 스레드를 시작한다."""
+        # [v1.1 수정] 중복 Open 방지. 이전에는 스레드가 중복 생성되고 포트가 누수됐다.
+        if self.isOpen():
+            print("이미 연결되어 있습니다. Close() 후 다시 시도하세요.")
+            return True
+
+        if portName is None:
+            for node in comports():
+                if node.description and "CH340" in node.description:
+                    portName = node.device
+                    break
+            if portName is None:
+                print("Can't find Serial Port")
+                raise ConnectionError("CH340 시리얼 포트를 찾을 수 없습니다.")
+
+        try:
+            self.serial = serial.Serial(port=portName, baudrate=19200, timeout=0.05)
+        except serial.SerialException as e:
+            print(f"시리얼 포트 오류: {e}")
+            raise
+        except Exception as e:
+            print(f"Can't open {portName}: {e}")
+            raise ConnectionError(f"포트 연결 실패: {portName}") from e
+
+        if not self.serial.isOpen():
+            raise ConnectionError(f"포트를 열 수 없습니다: {portName}")
+
+        # [v1.1 추가] 이전 세션의 잔여 바이트를 버린다. 파서가 헤더를 오인하지 않도록.
+        try:
+            self.serial.reset_input_buffer()
+            self.serial.reset_output_buffer()
+        except Exception:
+            pass
+
+        # 안전한 중립 상태(OPTION=0)에서 시작
+        self.makepkt.clearPacket()
+        self.parse.reset()
+        self.posX = self.posY = self.rot = 0
+        self._sensorTypes.clear()
+
+        self.isThreadRun = True
+        self._txEnabled.set()
+        self._rxThread = Thread(target=self._receiveHandler, daemon=True, name="aidrone-rx")
+        self._txThread = Thread(target=self._transmitHandler, daemon=True, name="aidrone-tx")
+        self._rxThread.start()
+        self._txThread.start()
+        print("Connected to", portName)
+        return True
+
+    def Close(self):
+        """센서 출력을 멈추고 중립 패킷을 보낸 뒤 포트를 닫는다."""
+        if self.serial is None:
+            return
+        try:
+            if self.serial.isOpen():
+                # [v1.1 추가] 센서 출력을 먼저 멈춘다. 이걸 빠뜨리면 프로그램을
+                # 끝내도 드론이 계속 패킷을 쏟아낸다.
+                self.stopSensor()
+
+                # 모터 테스트 모드였다면 속도 0으로 먼저 정지시킨다
+                if (self.makepkt.getField(Packet.IDX_OPTION, signed=False) & 0x8000) == 0x8000:
+                    self.makepkt.clearPacket()
+                    self.setOption(OPT_MOTORTEST)
+                    self._write(self.makepkt.getPacket())
+                    sleep(0.2)
+                # 중립(ARM 해제) 패킷을 여러 번 보내 유실에 대비
+                self.makepkt.clearPacket()
+                for _ in range(5):
+                    self._write(self.makepkt.getPacket())
+                    sleep(0.05)
+        except Exception as e:
+            print(f"[Close] 정지 패킷 전송 실패: {e}")
+        finally:
+            self.isThreadRun = False
+            self._txEnabled.set()          # 일시 정지 중이어도 스레드가 빠져나오도록
+            # [v1.1 추가] 스레드가 끝난 뒤에 포트를 닫는다.
+            for th in (self._txThread, self._rxThread):
+                if th is not None and th.is_alive():
+                    th.join(timeout=1.0)
+            self._txThread = self._rxThread = None
+            self.streamoff()
+            try:
+                if self.serial is not None and self.serial.isOpen():
+                    self.serial.close()
+            except Exception:
+                pass
+            self.serial = None
+
+    def isOpen(self):
+        return self.serial is not None and self.serial.isOpen()
+
+    # ==================================================================
+    # 스레드
+    # ==================================================================
+    def _write(self, data):
+        """모든 송신은 이 메서드를 통한다 (Lock 보호 + 연결 검사)."""
+        if self.serial is None or not self.serial.isOpen():
+            return False
+        try:
+            with self._lock:
+                self.serial.write(data)
+            return True
+        except serial.SerialException as e:
+            print(f"[_write] 시리얼 오류: {e}")
+            self.isThreadRun = False
+            return False
+        except Exception as e:
+            print(f"[_write] 송신 오류: {e}")
+            return False
+
+    def _receiveHandler(self):
+        """수신 전용 스레드."""
+        while self.isThreadRun:
+            # [v1.1 수정] Close() 도중 self.serial 이 None 이 되어 예외 메시지를
+            # 뿜던 문제. 루프 진입 시 연결 상태를 먼저 확인한다.
+            port = self.serial
+            if port is None or not port.isOpen():
+                break
+            try:
+                n = port.in_waiting
+                readData = port.read(n if n else 1)
+                if not readData:
+                    continue
+                for packet in self.parse.feed(readData):
+                    if self.sensor is not None:
+                        try:
+                            self.sensor.parse(packet)
+                        except Exception as e:
+                            print(f"[sensor] 파싱 오류: {e}")
+                    if self.receiveCallback is not None:
+                        try:
+                            self.receiveCallback(packet)
+                        except Exception as e:
+                            print(f"[receiveCallback] 사용자 콜백 오류: {e}")
+            except serial.SerialException as e:
+                print(f"[receiveHandler] 시리얼 오류: {e}")
+                self.isThreadRun = False
+                break
+            except Exception as e:
+                if not self.isThreadRun:
+                    break
+                print(f"[receiveHandler] 일시 오류 (계속 실행): {e}")
+                sleep(0.01)
+
+    def _transmitHandler(self):
+        """송신 전용 스레드. 제어 패킷을 일정 주기로 반복 전송한다.
+
+        [v1.1 수정] _txEnabled 가 내려가 있으면 송신하지 않는다.
+        명령 패킷을 보낼 때 제어 스트림이 잠시 비켜 주기 위한 장치.
+        """
+        while self.isThreadRun:
+            if not self._txEnabled.wait(timeout=0.1):
+                continue
+            if not self.isThreadRun:
+                break
+            self._write(self.makepkt.getPacket())
+            sleep(self._txPeriod)
+
+    def setTxRate(self, txHz):
+        """제어 패킷 송신 주기를 바꾼다. 비행 중에는 20Hz 이상을 권장한다."""
+        self._txPeriod = 1.0 / max(1.0, float(txHz))
+        return self._txPeriod
+
+    @contextmanager
+    def _txPaused(self, settle=0.02):
+        """명령 전송 동안 제어 스트림을 잠시 멈춘다.
+
+        [v1.1 추가] 이 장치가 없으면 명령 패킷이 20Hz 제어 패킷 사이에 끼어
+        드론 쪽 수신 버퍼에서 밀린다. 예제에서 txHz를 2로 낮춰 우회하던 문제를
+        라이브러리에서 해결한다.
+        """
+        ev = getattr(self, '_txEnabled', None)
+        if ev is None:                 # 패킷 로직만 검사하는 단위 테스트 경로
+            yield
+            return
+        ev.clear()
+        sleep(settle)
+        try:
+            yield
+        finally:
+            ev.set()
+
+    # ==================================================================
+    # 비행 제어
+    # ==================================================================
+    def setOption(self, option):
+        """OPTION 필드를 직접 설정한다."""
+        self.makepkt.setField(Packet.IDX_OPTION, int(option) & 0xFFFF, signed=False)
+
+    def _resetAxes(self):
+        """ROLL/PITCH/YAW 필드와 내부 좌표를 0으로 되돌린다."""
+        self.posX = self.posY = self.rot = 0
+        self.makepkt.setField(Packet.IDX_ROLL, 0)
+        self.makepkt.setField(Packet.IDX_PITCH, 0)
+        self.makepkt.setField(Packet.IDX_YAW, 0)
+
+    def takeoff(self, alt=70):
+        """목표 고도(기본 70cm)로 이륙한다."""
+        alt = DefLib.constrain(int(alt), ALT_MAX, 1)
+        self._resetAxes()
+        self.makepkt.setField(Packet.IDX_THR, alt, signed=False)
+        self.setOption(OPT_FLIGHT_POS)
+
+    def landing(self):
+        """목표 고도를 0으로 설정해 착륙한다.
+
+        주의: ARM 비트는 그대로 유지된다. 착륙이 끝난 뒤 모터를 완전히 내리려면
+              disarm() 을 호출한다.
+        """
+        self.makepkt.setField(Packet.IDX_THR, 0, signed=False)
+
+    def disarm(self):
+        """[v1.1 추가] ARM 비트를 내려 모터를 정지한다.
+
+        emergency() 와 동작은 같지만, 착륙이 끝난 뒤 정상 종료 용도로 쓴다.
+        **공중에서 호출하면 추락한다.**
+        """
+        self._resetAxes()
+        self.makepkt.setField(Packet.IDX_THR, 0, signed=False)
+        self.setOption(OPT_STOP)
+
+    def altitude(self, alt):
+        """목표 고도를 cm 단위로 설정한다 (0~150)."""
+        alt = DefLib.constrain(int(alt), ALT_MAX, ALT_MIN)
+        self.makepkt.setField(Packet.IDX_THR, alt, signed=False)
+
+    def velocity(self, dir=FRONT, vel=100):
+        """지정 방향으로 속도 제어(cm/s). 누적되지 않는다."""
+        if dir > LEFT or dir < FRONT:
+            return
+        vel = DefLib.constrain(int(vel), VEL_MAX, VEL_MIN)
+        if dir == BACK or dir == LEFT:
+            vel = -vel
+        if dir == FRONT or dir == BACK:
+            self.makepkt.setField(Packet.IDX_PITCH, vel)
+            self.makepkt.setField(Packet.IDX_ROLL, 0)
+        else:
+            self.makepkt.setField(Packet.IDX_ROLL, vel)
+            self.makepkt.setField(Packet.IDX_PITCH, 0)
+        self.posX = self.posY = 0
+        self.setOption(OPT_FLIGHT_VEL)
+
+    def rc_control(self, roll=0, pitch=0, yaw=0, throttle=None):
+        """roll·pitch·yaw 를 한 번에 준다 (실시간 수동 조종용).
+
+        velocity() 를 앞뒤·좌우로 따로 부르면 서로 필드를 0으로 덮어써서
+        한 방향만 먹는다. 대각선 이동이나 방향키 동시 입력에는 이 메서드를 쓴다.
+
+          roll     : 좌우 속도 (오른쪽 +, 왼쪽 -)   -VEL_MAX ~ VEL_MAX
+          pitch    : 전후 속도 (앞 +, 뒤 -)
+          yaw      : 회전 속도 (오른쪽 +, 왼쪽 -)
+          throttle : 고도(cm). None 이면 기존 고도 유지
+
+        Tello 의 send_rc_control(lr, fb, ud, yaw) 에 대응한다.
+        """
+        roll = DefLib.constrain(int(roll), VEL_MAX, VEL_MIN)
+        pitch = DefLib.constrain(int(pitch), VEL_MAX, VEL_MIN)
+        yaw = DefLib.constrain(int(yaw), YAWVEL_MAX, -YAWVEL_MAX)
+        self.makepkt.setField(Packet.IDX_ROLL, roll)
+        self.makepkt.setField(Packet.IDX_PITCH, pitch)
+        self.makepkt.setField(Packet.IDX_YAW, yaw)
+        if throttle is not None:
+            self.makepkt.setField(Packet.IDX_THR,
+                                  DefLib.constrain(int(throttle), ALT_MAX, ALT_MIN),
+                                  signed=False)
+        self.posX = self.posY = 0
+        self.setOption(OPT_FLIGHT_VEL)
+
+    def move(self, dir=FRONT, dist=100):
+        """이륙 지점 기준 누적 절대 위치로 이동한다 (cm)."""
+        if dir > LEFT or dir < FRONT:
+            return
+        dist = int(dist)
+        if dir == BACK or dir == LEFT:
+            dist = -dist
+        if dir == FRONT or dir == BACK:
+            self.posX = DefLib.constrain(self.posX + dist, POS_MAX, POS_MIN)
+        else:
+            self.posY = DefLib.constrain(self.posY + dist, POS_MAX, POS_MIN)
+        self.makepkt.setField(Packet.IDX_PITCH, self.posX)
+        self.makepkt.setField(Packet.IDX_ROLL, self.posY)
+        self.setOption(OPT_FLIGHT_POS)
+
+    def moveTo(self, x=0, y=0):
+        """이륙 지점 기준 절대 좌표로 직접 이동한다 (누적 아님)."""
+        self.posX = DefLib.constrain(int(x), POS_MAX, POS_MIN)
+        self.posY = DefLib.constrain(int(y), POS_MAX, POS_MIN)
+        self.makepkt.setField(Packet.IDX_PITCH, self.posX)
+        self.makepkt.setField(Packet.IDX_ROLL, self.posY)
+        self.setOption(OPT_FLIGHT_POS)
+
+    def rotation(self, rot=90):
+        """rot(도)만큼 회전한다. 양수는 시계방향. 내부적으로 절대각을 누적한다."""
+        self.rot = (int(self.rot + rot) + 180) % 360 - 180
+        self.makepkt.setField(Packet.IDX_YAW, self.rot)
+
+    def rotationTo(self, angle=0):
+        """이륙 시점 기준 절대 각도로 회전한다 (누적 아님)."""
+        self.rot = (int(angle) + 180) % 360 - 180
+        self.makepkt.setField(Packet.IDX_YAW, self.rot)
+
+    def stop(self):
+        """수평 이동을 정지하고 제자리 호버링한다."""
+        self.makepkt.setField(Packet.IDX_ROLL, 0)
+        self.makepkt.setField(Packet.IDX_PITCH, 0)
+        self.posX = self.posY = 0
+        self.setOption(OPT_FLIGHT_VEL)
+
+    hovering = stop
+
+    def setSpeed(self, posvel=100, yawvel=100):
+        """이동 속도(cm/s)와 회전 각속도(도/s) 기본값을 설정한다."""
+        self.makepkt.setField(Packet.IDX_POSVEL,
+                              DefLib.constrain(int(posvel), POSVEL_MAX, 0), signed=False)
+        self.makepkt.setField(Packet.IDX_YAWVEL,
+                              DefLib.constrain(int(yawvel), YAWVEL_MAX, 0), signed=False)
+
+    def motor(self, what, speed):
+        """개별 모터 직접 구동 (테스트용). **반드시 프로펠러를 제거하고 사용할 것.**"""
+        if what < 0 or what > 3:
+            return
+        speed = DefLib.constrain(int(speed), 100, 0)
+        self.makepkt.setField(what * 2 + 6, speed)
+        self.setOption(OPT_MOTORTEST)
+
+    def emergency(self):
+        """ARM 비트를 내려 모터를 즉시 정지한다. 공중에서 호출하면 추락한다."""
+        self._resetAxes()
+        self.makepkt.setField(Packet.IDX_THR, 0, signed=False)
+        self.setOption(OPT_STOP)
+        # [v1.1 수정] 간격 없이 연속 write 하면 드라이버 버퍼에 뭉쳐 나간다.
+        for i in range(3):
+            self._write(self.makepkt.getPacket())
+            if i < 2:
+                sleep(0.02)
+
+    # ==================================================================
+    # Command Packet (설정 / 요청)
+    # ==================================================================
+    def _sendCommand(self, header4, type_no, payload=b"", repeat=None, gap=None):
+        """Command Packet을 구성해 전송한다. LEN/CS는 자동 계산.
+
+        [v1.1 수정] 송신 스레드를 잠시 멈추고 여러 번 반복 전송한다.
+        이전 버전은 1회만 보내 제어 스트림 사이에서 유실되는 일이 잦았다.
+        """
+        repeat = self.CMD_REPEAT if repeat is None else max(1, int(repeat))
+        gap = self.CMD_GAP if gap is None else float(gap)
+
+        length = 7 + len(payload)
+        pkt = bytearray([0x26, 0xA8, 0x14, header4, length, 0x00, type_no]) + bytes(payload)
+        pkt[5] = DefLib.checksum(pkt)
+
+        ok = False
+        with self._txPaused():
+            for i in range(repeat):
+                ok = self._write(pkt) or ok
+                if i < repeat - 1:
+                    sleep(gap)
+        return ok
+
+    # ---- 센서 / 정보 요청 -------------------------------------------
+    def _trackSensor(self, data_type, on):
+        """출력 요청 중인 TYPE 목록을 갱신한다 (Close() 자동 정지에 사용).
+
+        __init__ 을 거치지 않은 객체(단위 테스트)에서도 안전하도록 방어한다.
+        """
+        types = getattr(self, '_sensorTypes', None)
+        if types is None:
+            return
+        types.add(data_type) if on else types.discard(data_type)
+
+    def requestSensorData(self, data_type, sig_mode=None):
+        """센서 데이터 출력을 요청한다.
+
+        data_type 9  : 비행정보 (roll/pitch/height/pos_x/pos_y), sig_mode 기본 1
+        data_type 10 : 센서·제어 신호, sig_mode 기본 0x06(POS_SIGNAL)
+        """
+        if data_type == TYPE_FLIGHTINFO:
+            mode = 1 if sig_mode is None else (int(sig_mode) & 0xFF)
+            ok = self._sendCommand(0xB2, TYPE_FLIGHTINFO, bytes([mode]))
+            self._trackSensor(TYPE_FLIGHTINFO, ok and bool(mode))
+            return ok
+        elif data_type == TYPE_SIGNAL:
+            sig = SIG_POS if sig_mode is None else (int(sig_mode) & 0xFF)
+            ok = self._sendCommand(0xB1, TYPE_SIGNAL, bytes([sig]))
+            self._trackSensor(TYPE_SIGNAL, ok and sig != SIG_STOP)
+            return ok
+        return False
+
+    def stopSensorData(self, data_type):
+        """센서 데이터 출력을 중지한다."""
+        if data_type == TYPE_FLIGHTINFO:
+            ok = self._sendCommand(0xB2, TYPE_FLIGHTINFO, bytes([0x00]))
+            self._trackSensor(TYPE_FLIGHTINFO, False)
+            return ok
+        elif data_type == TYPE_SIGNAL:
+            ok = self._sendCommand(0xB1, TYPE_SIGNAL, bytes([SIG_STOP]))
+            self._trackSensor(TYPE_SIGNAL, False)
+            return ok
+        return False
+
+    def startSensor(self, flight=True, signal=False, timeout=3.0):
+        """[v1.1 추가] 센서 출력을 시작하고 실제로 들어오는지 확인한다.
+
+        내장 센서(sensor=True)로 생성한 경우에만 도착 확인이 가능하며,
+        확인에 성공하면 True를 반환한다.
+        """
+        base = self.sensor.info_count if self.sensor is not None else 0
+        if flight:
+            self.requestSensorData(TYPE_FLIGHTINFO)
+        if signal:
+            self.requestSensorData(TYPE_SIGNAL)
+        if self.sensor is None:
+            return True                      # 확인할 방법이 없으므로 전송 성공으로 간주
+
+        deadline = time() + timeout
+        while time() < deadline:
+            if self.sensor.info_count > base:
+                return True
+            sleep(0.05)
+        return False
+
+    def stopSensor(self):
+        """[v1.1 추가] 요청 중인 센서 출력을 모두 중지한다."""
+        for t in list(getattr(self, '_sensorTypes', ())):
+            self.stopSensorData(t)
+        return True
+
+    def requestDeviceInfo(self):
+        """TYPE(8) 디바이스 정보(버전/시리얼/MAC/센서 탑재) 출력 요청."""
+        return self._sendCommand(0xB2, TYPE_DEVINFO)
+
+    # ---- 내장 센서 접근 ---------------------------------------------
+    def getState(self):
+        """[v1.1 추가] 내장 센서의 상태 딕셔너리. sensor=False 면 None."""
+        return None if self.sensor is None else self.sensor.state
+
+    def getBattery(self):
+        """[v1.1 추가] 배터리 잔량(%). 요청 없이도 모든 출력 패킷에 들어 있다."""
+        return 0 if self.sensor is None else self.sensor.state['battery']
+
+    def getAttitude(self):
+        """[v1.1 추가] (roll, pitch, height). startSensor() 이후에만 갱신된다."""
+        if self.sensor is None:
+            return (0, 0, 0)
+        s = self.sensor.state
+        return s['roll'], s['pitch'], s['height']
+
+    def isReady(self):
+        """[v1.1 추가] OPT1 bit1 — 드론 비행 준비 상태."""
+        return False if self.sensor is None else self.sensor.state['ready']
+
+    def waitReady(self, timeout=5.0):
+        """[v1.1 추가] 비행 준비 상태가 될 때까지 기다린다."""
+        if self.sensor is None:
+            return False
+        deadline = time() + timeout
+        while time() < deadline:
+            if self.sensor.state['ready']:
+                return True
+            sleep(0.05)
+        return False
+
+    # ---- 보정 / 트림 / 기타 설정 ------------------------------------
+    def calibration(self):
+        """TYPE(6) 자이로·가속 센서 보정. 드론을 평평한 곳에 놓고 실행할 것."""
+        return self._sendCommand(0xB1, TYPE_CALIBRATION)
+
+    def setTrim(self, roll=READ_TRIM, pitch=READ_TRIM):
+        """TYPE(5) TRIM 설정. 인자 없이 호출하면 현재 설정값 읽기 요청."""
+        payload = int(roll).to_bytes(2, "little", signed=True) + \
+                  int(pitch).to_bytes(2, "little", signed=True)
+        return self._sendCommand(0xB1, TYPE_TRIM, payload)
+
+    def setMisc(self, rst=0, wc=READ_MISC, af=READ_MISC, pd=READ_MISC):
+        """TYPE(7) 기타 설정.
+
+        rst : 0x94 이면 설정값 공장 초기화 (펌웨어는 변화 없음)
+        wc  : Weight Coefficient. 기체가 무거울수록 크게. 255이면 현재값 읽기
+        af  : AltFree. 0=고도 제한(0~150cm), 1=제한 없음, 255=읽기
+        pd  : Propeller Direction. 255=읽기
+        """
+        payload = bytes([int(rst) & 0xFF, int(wc) & 0xFF, int(af) & 0xFF, int(pd) & 0xFF])
+        return self._sendCommand(0xB1, TYPE_MISC, payload)
+
+    def setWeightCoefficient(self, wc):
+        """ALTHOLD=1에서 기체 무게가 바뀌어 고도가 불안정할 때 조정한다."""
+        return self.setMisc(rst=0, wc=wc, af=READ_MISC, pd=READ_MISC)
+
+    def factoryReset(self):
+        """설정값을 공장 초기화한다."""
+        return self.setMisc(rst=FACTORY_RESET)
+
+    # ---- PID 설정 ---------------------------------------------------
+    def _setPID(self, type_no, p, i, d):
+        payload = int(p).to_bytes(2, "little", signed=True) + \
+                  int(i).to_bytes(2, "little", signed=True) + \
+                  int(d).to_bytes(2, "little", signed=True)
+        return self._sendCommand(0xB1, type_no, payload)
+
+    def setFlightPID(self, p=READ_PID, i=READ_PID, d=READ_PID):
+        """TYPE(2) 비행 PID. 인자 없이 호출하면 현재값 읽기 요청."""
+        return self._setPID(TYPE_PID_FLIGHT, p, i, d)
+
+    def setAltPID(self, p=READ_PID, i=READ_PID, d=READ_PID):
+        """TYPE(3) 높이 PID."""
+        return self._setPID(TYPE_PID_ALT, p, i, d)
+
+    def setPosPID(self, p=READ_PID, i=READ_PID, d=READ_PID):
+        """TYPE(4) 위치 PID."""
+        return self._setPID(TYPE_PID_POS, p, i, d)
+
+    # ==================================================================
+    # 영상 스트리밍
+    # ==================================================================
+    def setStreamAddress(self, host, port=80, path="/?action=stream"):
+        if not isinstance(host, str) or len(host.strip()) == 0:
+            raise ValueError("host가 올바르지 않습니다.")
+        self.stream_host = host.strip()
+        self.stream_port = int(port)
+        if not path.startswith("/"):
+            path = "/" + path
+        self.stream_path = path
+        return self._build_stream_url()
+
+    def _build_stream_url(self):
+        if self.stream_port in (80, None):
+            return f"http://{self.stream_host}{self.stream_path}"
+        return f"http://{self.stream_host}:{self.stream_port}{self.stream_path}"
+
+    def streamon(self, host=None, port=None, path=None, return_url=False):
+        """MJPG-Streamer 스트림을 열고 cv2.VideoCapture 객체를 반환한다."""
+        if host is not None or port is not None or path is not None:
+            self.setStreamAddress(host or self.stream_host,
+                                  self.stream_port if port is None else port,
+                                  self.stream_path if path is None else path)
+        url = self._build_stream_url()
+        if return_url:
+            return url
+
+        try:
+            import cv2 as cv
+        except Exception as e:
+            raise RuntimeError(f"OpenCV(cv2) 임포트 실패: {e}")
+
+        self.streamoff()
+        self._cap = cv.VideoCapture(url)
+        if not self._cap.isOpened():
+            self._cap.release()
+            self._cap = None
+            raise RuntimeError(f"스트림 열기 실패: {url}")
+        return self._cap
+
+    def streamoff(self):
+        if self._cap is not None:
+            try:
+                self._cap.release()
+            except Exception:
+                pass
+            self._cap = None
+
+    def getFrame(self):
+        """열려 있는 스트림에서 프레임 1장을 읽어 반환한다. 실패 시 None."""
+        if self._cap is None:
+            return None
+        ret, frame = self._cap.read()
+        if not ret:
+            return None
+        return frame
+
+    # ==================================================================
+    # with 문 지원
+    # ==================================================================
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.Close()
+        return False

pyaidrone-2.9/pyaidrone/drone.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+"""
+pyaidrone.drone — 쉬운 고수준 드론 제어 클래스 (Tello 스타일 API)
+
+djitellopy(Tello) 예제를 거의 그대로 쓸 수 있게, 같은 이름의 메서드를 제공한다.
+학생이 인터넷의 수많은 Tello 코드를 pyaidrone 으로 바로 가져다 쓸 수 있다.
+
+  Tello 코드:
+      from djitellopy import Tello
+      aidrone = Tello()   # (참고: 실제로는 Drone 을 씀)
+      aidrone.connect()
+      aidrone.takeoff()
+      aidrone.move_forward(100)
+      aidrone.rotate_clockwise(90)
+      aidrone.land()
+
+  같은 동작 (pyaidrone):
+      from pyaidrone.drone import Drone
+      aidrone = Drone("COM3")
+      aidrone.connect()
+      aidrone.takeoff()
+      aidrone.move_forward(100)
+      aidrone.rotate_clockwise(90)
+      aidrone.land()
+
+핵심 차이(내부적으로 흡수함):
+  - Tello 의 move_xxx(cm) 는 '거리를 다 갈 때까지 기다렸다가' 리턴한다(블로킹).
+    이 드론은 속도 제어 기반이므로, 거리/속도로 이동 시간을 계산해 그만큼 이동 후
+    자동 정지한다. 학생은 Tello 와 똑같이 거리만 지정하면 된다.
+  - 이 드론 펌웨어는 '준비 비트'를 쓰지 않으므로, connect() 는 통신 여부로 판단한다.
+
+주의: 실제 비행 거리 정확도는 기체 상태(광학흐름/바닥 무늬/배터리)에 따라 달라진다.
+      DEFAULT_SPEED 를 조정해 교실 환경에 맞게 보정할 수 있다.
+"""
+
+import time
+from pyaidrone.aiDrone import AIDrone
+from pyaidrone.deflib import FRONT, BACK, LEFT, RIGHT
+
+
+class Drone:
+    """pyaidrone 을 Tello(djitellopy) 처럼 쓰게 해주는 래퍼."""
+
+    DEFAULT_SPEED = 30      # 이동 속도(cm/s). move_xxx 의 이동 시간 계산 기준
+    DEFAULT_HEIGHT = 80     # 이륙 목표 고도(cm)
+    TAKEOFF_WAIT = 5        # 이륙 안정화 대기(초)
+    ROTATE_WAIT = 3         # 회전 대기(초)
+
+    def __init__(self, port="COM3"):
+        self.port = port
+        self.drone = AIDrone(sensor=True)
+        self._flying = False
+        self._cap = None
+        self.speed = self.DEFAULT_SPEED
+
+    # ==================================================================
+    # 연결
+    # ==================================================================
+    def connect(self, wait=0.5):
+        """드론에 연결하고 센서 출력을 시작한다. (Tello.connect 대응)"""
+        self.drone.Open(self.port)
+        time.sleep(wait)
+        self.drone.startSensor(flight=True)
+        if self.drone.sensor.count == 0:
+            raise ConnectionError("드론에서 신호가 오지 않습니다. 전원/페어링을 확인하세요.")
+        return True
+
+    def end(self):
+        """연결을 종료한다. (Tello.end 대응)"""
+        try:
+            if self._flying:
+                self.land()
+        finally:
+            self.streamoff()
+            self.drone.Close()
+
+    # ==================================================================
+    # 상태 조회 (Tello get_xxx 대응)
+    # ==================================================================
+    def get_battery(self):
+        """배터리 잔량(%)."""
+        return self.drone.getBattery()
+
+    def get_height(self):
+        """현재 높이(cm)."""
+        return self.drone.getAttitude()[2]
+
+    def get_roll(self):
+        return self.drone.getAttitude()[0]
+
+    def get_pitch(self):
+        return self.drone.getAttitude()[1]
+
+    def get_state(self):
+        """전체 센서 상태(딕셔너리)."""
+        return self.drone.getState()
+
+    def set_speed(self, cm_s):
+        """이동 속도(cm/s)를 설정한다. move_xxx 의 이동 시간에 반영된다."""
+        self.speed = max(10, min(100, int(cm_s)))
+
+    # ==================================================================
+    # 이·착륙 (Tello 대응)
+    # ==================================================================
+    def takeoff(self):
+        """이륙 후 안정될 때까지 기다린다. (블로킹)"""
+        self.drone.takeoff(self.DEFAULT_HEIGHT)
+        self._flying = True
+        time.sleep(self.TAKEOFF_WAIT)
+
+    def land(self):
+        """착륙 후 모터를 정지한다. (블로킹)"""
+        self.drone.landing()
+        time.sleep(3)
+        self.drone.disarm()
+        self._flying = False
+
+    # ==================================================================
+    # 거리 이동 — Tello move_xxx(cm) 대응 (블로킹)
+    # ==================================================================
+    def _move(self, direction, cm):
+        """지정 방향으로 cm 만큼 이동 후 정지. 거리/속도로 시간을 계산한다."""
+        cm = abs(int(cm))
+        duration = cm / float(self.speed)
+        self.drone.velocity(direction, self.speed)
+        time.sleep(duration)
+        self.drone.velocity(direction, 0)      # 정지
+        time.sleep(0.5)                         # 정지 안정화
+
+    def move_forward(self, cm):
+        self._move(FRONT, cm)
+
+    def move_back(self, cm):
+        self._move(BACK, cm)
+
+    def move_left(self, cm):
+        self._move(LEFT, cm)
+
+    def move_right(self, cm):
+        self._move(RIGHT, cm)
+
+    def move_up(self, cm):
+        """위로 cm 만큼 상승 (절대 고도 기준으로 목표를 올림)."""
+        h = self.get_height()
+        target = min(150, h + abs(int(cm)))
+        self.drone.altitude(target)
+        time.sleep(2)
+
+    def move_down(self, cm):
+        h = self.get_height()
+        target = max(0, h - abs(int(cm)))
+        self.drone.altitude(target)
+        time.sleep(2)
+
+    # ==================================================================
+    # 회전 — Tello rotate_xxx(deg) 대응 (블로킹)
+    # ==================================================================
+    def rotate_clockwise(self, deg):
+        """시계 방향(오른쪽) 회전."""
+        self.drone.rotation(abs(int(deg)))
+        time.sleep(self.ROTATE_WAIT)
+
+    def rotate_counter_clockwise(self, deg):
+        """반시계 방향(왼쪽) 회전."""
+        self.drone.rotation(-abs(int(deg)))
+        time.sleep(self.ROTATE_WAIT)
+
+    # ==================================================================
+    # 실시간 속도 제어 — Tello send_rc_control 대응
+    # ==================================================================
+    def send_rc_control(self, lr, fb, ud, yaw):
+        """네 방향 속도를 한 번에 준다. (-100~100)
+           lr: 좌우, fb: 전후, ud: 상하, yaw: 회전. Tello 와 동일한 순서.
+
+           좌우(roll)와 전후(pitch)를 동시에 보내므로 대각선 이동도 된다."""
+        self.drone.rc_control(roll=lr, pitch=fb, yaw=yaw)
+        if ud:
+            # 상하는 목표 고도를 조금씩 올리고 내린다
+            h = self.get_height()
+            self.drone.altitude(max(0, min(150, h + int(ud) // 10)))
+
+    # ==================================================================
+    # 영상 — Tello streamon / get_frame_read 대응
+    # ==================================================================
+    def streamon(self, url="http://192.168.4.1/?action=stream"):
+        """영상 스트림을 켠다."""
+        import cv2
+        self._cap = cv2.VideoCapture(url)
+        return self._cap.isOpened()
+
+    def streamoff(self):
+        if self._cap is not None:
+            self._cap.release()
+            self._cap = None
+
+    def get_frame(self):
+        """현재 프레임 1장을 반환한다. 실패 시 None."""
+        if self._cap is None:
+            return None
+        ok, frame = self._cap.read()
+        return frame if ok else None

{pyaidrone-2.8 → pyaidrone-2.9}/pyaidrone.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyaidrone
-Version: 2.8
+Version: 2.9
 Summary: Library for AIDrone Products
 Home-page: http://www.ir-brain.com
 Author: IR-Brain

{pyaidrone-2.8 → pyaidrone-2.9}/pyaidrone.egg-info/SOURCES.txt

@@ -2,8 +2,10 @@ README.md
 setup.cfg
 setup.py
 pyaidrone/__init__.py
+pyaidrone/aiDrone.py
 pyaidrone/aidrone_mavlink_bridge.py
 pyaidrone/deflib.py
+pyaidrone/drone.py
 pyaidrone/edu.py
 pyaidrone/ikeyevent.py
 pyaidrone/packet.py

{pyaidrone-2.8 → pyaidrone-2.9}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="pyaidrone",
-    version="2.8",
+    version="2.9",
     description="Library for AIDrone Products",
     long_description=open("README.md").read(),  # README.md 내용을 long_description으로 사용
     long_description_content_type="text/markdown",  # README 파일이 markdown 형식임을 지정