easylink-mavlink 0.1.0__tar.gz

easylink_mavlink-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: easylink-mavlink
+Version: 0.1.0
+Summary: Lightweight, zero-friction Python library for MAVLink drone control (ArduPilot & PX4)
+Author: EASYLink Contributors
+Project-URL: Homepage, https://github.com/easylink/easylink
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pymavlink>=2.4.41
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# PY-EASYLink (`easylink-mavlink`)
+
+Lightweight, zero-friction Python library for MAVLink drone control (supporting both ArduPilot and PX4).
+
+## Installation
+
+```bash
+pip install easylink-mavlink
+```
+
+## Quickstart
+
+```python
+from easylink import Drone
+
+# Auto-discovers SITL simulator or hardware serial port
+drone = Drone()
+drone.connect()
+
+drone.arm()
+drone.takeoff(10.0)
+
+pos = drone.position
+print(f"Current Position: Lat={pos.lat}, Lon={pos.lon}, Alt={pos.alt}m")
+
+drone.hover(5.0)
+drone.home()
+drone.disconnect()
+```
+
+## Features
+
+- **Auto-Discovery**: Probes local SITL ports (`udp:127.0.0.1:14550`, etc.) and serial ports (`/dev/ttyAMA0`, `COM3`, etc.).
+- **Dual Firmware Support**: Auto-detects ArduPilot vs PX4 from heartbeats.
+- **Packet Dispatcher**: Solves packet-stealing and threading collisions cleanly.
+- **Fluent Mission Builder**: `drone.mission.clear().add_takeoff(15).add_waypoint(lat, lon, alt).add_land().upload()`
+
+## License
+
+MIT

easylink_mavlink-0.1.0/README.md

@@ -0,0 +1,40 @@
+# PY-EASYLink (`easylink-mavlink`)
+
+Lightweight, zero-friction Python library for MAVLink drone control (supporting both ArduPilot and PX4).
+
+## Installation
+
+```bash
+pip install easylink-mavlink
+```
+
+## Quickstart
+
+```python
+from easylink import Drone
+
+# Auto-discovers SITL simulator or hardware serial port
+drone = Drone()
+drone.connect()
+
+drone.arm()
+drone.takeoff(10.0)
+
+pos = drone.position
+print(f"Current Position: Lat={pos.lat}, Lon={pos.lon}, Alt={pos.alt}m")
+
+drone.hover(5.0)
+drone.home()
+drone.disconnect()
+```
+
+## Features
+
+- **Auto-Discovery**: Probes local SITL ports (`udp:127.0.0.1:14550`, etc.) and serial ports (`/dev/ttyAMA0`, `COM3`, etc.).
+- **Dual Firmware Support**: Auto-detects ArduPilot vs PX4 from heartbeats.
+- **Packet Dispatcher**: Solves packet-stealing and threading collisions cleanly.
+- **Fluent Mission Builder**: `drone.mission.clear().add_takeoff(15).add_waypoint(lat, lon, alt).add_land().upload()`
+
+## License
+
+MIT

easylink_mavlink-0.1.0/easylink/__init__.py

@@ -0,0 +1,26 @@
+from .drone import Drone
+from .mission import MissionManager
+from .telemetry import Position, Attitude, Battery, GPSInfo
+from .exceptions import (
+    EASYLinkError,
+    ConnectionError,
+    ArmingError,
+    CommandTimeoutError,
+    ModeError,
+    PreFlightCheckError
+)
+
+__all__ = [
+    'Drone',
+    'MissionManager',
+    'Position',
+    'Attitude',
+    'Battery',
+    'GPSInfo',
+    'EASYLinkError',
+    'ConnectionError',
+    'ArmingError',
+    'CommandTimeoutError',
+    'ModeError',
+    'PreFlightCheckError'
+]

easylink_mavlink-0.1.0/easylink/actions.py

@@ -0,0 +1,219 @@
+import time
+from pymavlink import mavutil
+from .exceptions import CommandTimeoutError, ArmingError
+
+class ActionManager:
+    """Handles vehicle actions such as arming, disarming, takeoff, landing, RTL, and kill."""
+    
+    def __init__(self, connection_mgr, adapter_mgr):
+        self.conn_mgr = connection_mgr
+        self.adapter_mgr = adapter_mgr
+        
+    @property
+    def master(self):
+        return self.conn_mgr.master
+
+    @property
+    def dispatcher(self):
+        drone_inst = getattr(self.conn_mgr, 'drone', None)
+        return drone_inst._telemetry if drone_inst else None
+
+    def arm(self, timeout: float = 15.0):
+        """Arms vehicle motors. Swaps to STABILIZE mode first for pre-arm integrity checks, then guided mode."""
+        master = self.master
+        is_px4 = self.conn_mgr.autopilot_type == mavutil.mavlink.MAV_AUTOPILOT_PX4
+        
+        # 1. Switch to initial arm-friendly mode
+        stabilize_mode = 'ALT_HOLD' if is_px4 else 'STABILIZE'
+        if master.mode_mapping() and stabilize_mode in master.mode_mapping():
+            mode_id = master.mode_mapping()[stabilize_mode]
+            master.mav.command_long_send(
+                self.conn_mgr.target_system,
+                self.conn_mgr.target_component,
+                mavutil.mavlink.MAV_CMD_DO_SET_MODE,
+                0,
+                mavutil.mavlink.MAV_MODE_FLAG_CUSTOM_MODE_ENABLED,
+                mode_id, 0, 0, 0, 0, 0
+            )
+            time.sleep(0.3)
+
+        # 2. Send Arm command
+        master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_COMPONENT_ARM_DISARM,
+            0,
+            1, # 1 to arm
+            0, 0, 0, 0, 0, 0
+        )
+        
+        # 3. Await armed HEARTBEAT via dispatcher queue
+        disp = self.dispatcher
+        armed_ok = False
+        if disp:
+            msg = disp.wait_for_message(
+                'HEARTBEAT',
+                timeout=timeout,
+                filter_fn=lambda m: bool(m.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED)
+            )
+            if msg:
+                armed_ok = True
+        else:
+            start_time = time.time()
+            while time.time() - start_time < timeout:
+                msg = master.recv_match(type='HEARTBEAT', blocking=True, timeout=0.5)
+                if msg and (msg.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED):
+                    armed_ok = True
+                    break
+
+        if not armed_ok:
+            raise ArmingError("Arming request timed out or was rejected by the flight controller.")
+
+        # 4. Transition to GUIDED/OFFBOARD for navigation commands
+        time.sleep(0.3)
+        self.adapter_mgr.set_guided_mode(master)
+        return True
+
+    def disarm(self, timeout: float = 15.0):
+        """Disarms vehicle motors safely."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_COMPONENT_ARM_DISARM,
+            0,
+            0, # 0 to disarm
+            0, 0, 0, 0, 0, 0
+        )
+        
+        disp = self.dispatcher
+        if disp:
+            msg = disp.wait_for_message(
+                'HEARTBEAT',
+                timeout=timeout,
+                filter_fn=lambda m: not bool(m.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED)
+            )
+            if msg:
+                return True
+        else:
+            start_time = time.time()
+            while time.time() - start_time < timeout:
+                msg = self.master.recv_match(type='HEARTBEAT', blocking=True, timeout=0.5)
+                if msg and not (msg.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED):
+                    return True
+        raise ArmingError("Disarming request timed out or was rejected by the flight controller.")
+
+    def takeoff(self, altitude: float, timeout: float = 30.0):
+        """Commands drone takeoff to specified relative altitude in meters."""
+        self.adapter_mgr.set_guided_mode(self.master)
+        time.sleep(0.2)
+
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_NAV_TAKEOFF,
+            0,
+            0, 0, 0, 0, 0, 0,
+            altitude
+        )
+        
+        disp = self.dispatcher
+        if disp:
+            ack = disp.wait_for_message(
+                'COMMAND_ACK',
+                timeout=3.0,
+                filter_fn=lambda m: getattr(m, 'command', None) == mavutil.mavlink.MAV_CMD_NAV_TAKEOFF
+            )
+            if ack and ack.result in [mavutil.mavlink.MAV_RESULT_TEMPORARILY_REJECTED, mavutil.mavlink.MAV_RESULT_DENIED]:
+                raise CommandTimeoutError(f"Takeoff command rejected by vehicle: result {ack.result}")
+
+        # Block until target altitude is reached (within 90% threshold)
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if disp:
+                current_alt = disp.position.alt
+                if current_alt >= altitude * 0.90:
+                    return True
+                time.sleep(0.2)
+            else:
+                msg = self.master.recv_match(type='GLOBAL_POSITION_INT', blocking=True, timeout=0.5)
+                if msg and (msg.relative_alt / 1000.0) >= altitude * 0.90:
+                    return True
+        raise CommandTimeoutError("Takeoff command issued, but target altitude was not reached within timeout.")
+
+    def land(self, blocking: bool = True, timeout: float = 60.0):
+        """Commands landing at current position. If blocking=True, waits until motors disarm on ground."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_NAV_LAND,
+            0,
+            0, 0, 0, 0, 0, 0, 0
+        )
+        
+        if not blocking:
+            return True
+
+        # Blocking wait: Watch for armed state to drop (disarm on ground)
+        disp = self.dispatcher
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if disp:
+                if not disp.is_armed:
+                    return True
+                time.sleep(0.5)
+            else:
+                msg = self.master.recv_match(type='HEARTBEAT', blocking=True, timeout=0.5)
+                if msg and not bool(msg.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED):
+                    return True
+        return True
+
+    def rtl(self, blocking: bool = True, timeout: float = 90.0):
+        """Triggers Return-To-Launch (RTL). If blocking=True, waits until vehicle lands & disarms."""
+        if self.master.mode_mapping() and 'RTL' in self.master.mode_mapping():
+            mode_id = self.master.mode_mapping()['RTL']
+            self.master.mav.command_long_send(
+                self.conn_mgr.target_system,
+                self.conn_mgr.target_component,
+                mavutil.mavlink.MAV_CMD_DO_SET_MODE,
+                0,
+                mavutil.mavlink.MAV_MODE_FLAG_CUSTOM_MODE_ENABLED,
+                mode_id, 0, 0, 0, 0, 0
+            )
+        else:
+            self.master.mav.command_long_send(
+                self.conn_mgr.target_system,
+                self.conn_mgr.target_component,
+                mavutil.mavlink.MAV_CMD_NAV_RETURN_TO_LAUNCH,
+                0,
+                0, 0, 0, 0, 0, 0, 0
+            )
+
+        if not blocking:
+            return True
+
+        # Blocking wait: Watch for armed state to drop (vehicle returned, landed, and disarmed)
+        disp = self.dispatcher
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if disp:
+                if not disp.is_armed:
+                    return True
+                time.sleep(0.5)
+            else:
+                msg = self.master.recv_match(type='HEARTBEAT', blocking=True, timeout=0.5)
+                if msg and not bool(msg.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED):
+                    return True
+        return True
+
+    def kill(self):
+        """Emergency motor kill (disarms immediately regardless of flight state)."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_COMPONENT_ARM_DISARM,
+            0,
+            0, # Disarm
+            21196, # Magic number to force kill
+            0, 0, 0, 0, 0
+        )
+        return True

easylink_mavlink-0.1.0/easylink/camera.py

@@ -0,0 +1,71 @@
+from pymavlink import mavutil
+
+class CameraManager:
+    """Manages simple camera commands via MAVLink."""
+    
+    def __init__(self, connection_mgr):
+        self.conn_mgr = connection_mgr
+
+    @property
+    def master(self):
+        return self.conn_mgr.master
+
+    def take_photo(self):
+        """Sends command to trigger single camera photo capture."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_IMAGE_START_CAPTURE,
+            0,
+            0, # Reserved (0)
+            0, # Interval (0 for single image)
+            1, # Total number of images to capture (1)
+            0, 0, 0, 0
+        )
+
+    def start_video(self):
+        """Sends command to start video capture."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_VIDEO_START_CAPTURE,
+            0,
+            0, # Camera ID
+            0, 0, 0, 0, 0, 0
+        )
+
+    def stop_video(self):
+        """Sends command to stop video capture."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_VIDEO_STOP_CAPTURE,
+            0,
+            0, # Camera ID
+            0, 0, 0, 0, 0, 0
+        )
+
+
+class GimbalManager:
+    """Manages camera gimbal angle controls."""
+    
+    def __init__(self, connection_mgr):
+        self.conn_mgr = connection_mgr
+
+    @property
+    def master(self):
+        return self.conn_mgr.master
+
+    def set_pitch_yaw(self, pitch: float, yaw: float):
+        """Sets pitch and yaw angles of camera gimbal mount."""
+        self.master.mav.command_long_send(
+            self.conn_mgr.target_system,
+            self.conn_mgr.target_component,
+            mavutil.mavlink.MAV_CMD_DO_MOUNT_CONTROL,
+            0,
+            pitch, # Pitch angle in degrees
+            0,     # Roll (0)
+            yaw,   # Yaw angle in degrees
+            0, 0, 0,
+            mavutil.mavlink.MAV_MOUNT_MODE_MAVLINK_TARGETING # Mount mode
+        )

easylink_mavlink-0.1.0/easylink/connection.py

@@ -0,0 +1,91 @@
+import sys
+import time
+import logging
+from pymavlink import mavutil
+from .exceptions import ConnectionError
+
+logger = logging.getLogger(__name__)
+
+class ConnectionManager:
+    """Manages connection establishment, port scanning/auto-discovery, and heartbeat listening."""
+    
+    def __init__(self, target: str = None):
+        self.target = target
+        self.drone = None
+        self.master = None
+        self.target_system = 1
+        self.target_component = 1
+        self.autopilot_type = None
+        self.is_connected = False
+        
+    def _get_candidates(self):
+        """Generates list of possible connection targets when no target is specified."""
+        if self.target:
+            return [self.target]
+            
+        candidates = []
+        
+        # 1. Simulators (SITL) defaults - high priority
+        candidates.append("udp:127.0.0.1:14550")
+        candidates.append("udp:127.0.0.1:14551")
+        candidates.append("tcp:127.0.0.1:5760")
+        candidates.append("tcp:127.0.0.1:5762")
+        
+        # 2. Hardware Serial Port scanning
+        if sys.platform.startswith("win"):
+            # Scan common active Windows COM ports (prioritize COM3-COM8, COM1, COM2)
+            for i in [3, 4, 5, 6, 7, 8, 1, 2, 9, 10, 11, 12]:
+                candidates.append(f"COM{i}:57600")
+                candidates.append(f"COM{i}:115200")
+        else:
+            # Linux / macOS / Raspberry Pi
+            serial_devs = [
+                "/dev/ttyUSB0", "/dev/ttyUSB1",
+                "/dev/ttyACM0", "/dev/ttyACM1",
+                "/dev/ttyAMA0", "/dev/ttyAMA1",
+                "/dev/ttyS0"
+            ]
+            for dev in serial_devs:
+                candidates.append(f"{dev}:57600")
+                candidates.append(f"{dev}:115200")
+                
+        return candidates
+
+    def connect(self, timeout: float = 15.0):
+        candidates = self._get_candidates()
+        
+        for candidate in candidates:
+            try:
+                # Attempt to open connection
+                self.master = mavutil.mavlink_connection(candidate, timeout=0.5)
+                
+                # Check for heartbeat to confirm active vehicle
+                start_time = time.time()
+                probe_timeout = timeout if self.target else 0.5
+                
+                while time.time() - start_time < probe_timeout:
+                    msg = self.master.recv_match(type='HEARTBEAT', blocking=True, timeout=0.3)
+                    if msg:
+                        self.target_system = self.master.target_system
+                        self.target_component = self.master.target_component
+                        self.autopilot_type = msg.autopilot
+                        self.is_connected = True
+                        return
+            except Exception:
+                if self.master:
+                    try:
+                        self.master.close()
+                    except Exception:
+                        pass
+                self.master = None
+                
+        raise ConnectionError("Failed to establish MAVLink connection. No active vehicle responded to probes.")
+
+    def disconnect(self):
+        if self.master:
+            try:
+                self.master.close()
+            except Exception:
+                pass
+        self.is_connected = False
+        self.master = None