device-protocol-sdk 1.2.6__tar.gz

device_protocol_sdk-1.2.6/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.1
+Name: device_protocol_sdk
+Version: 1.2.6
+Summary: 无人设备协议开发SDK
+Author: fuhl
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.48.2
+Requires-Dist: grpcio-tools>=1.48.2
+Requires-Dist: paho-mqtt>=1.6.1
+Requires-Dist: pydantic>=1.9.0
+Requires-Dist: websockets>=10.0
+Requires-Dist: shapely>=2.1.2
+
+# Device Protocol SDK
+
+无人机设备协议开发工具包，提供标准化接口实现多类型无人机设备的快速接入。
+
+[![PyPI Version](https://img.shields.io/pypi/v/device-protocol-sdk)](https://pypi.org/project/device-protocol-sdk/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/device-protocol-sdk)](https://pypi.org/project/device-protocol-sdk/)
+
+## 功能特性
+
+- 🛠️ **协议无关抽象**：统一各类无人机设备的控制接口
+- 🔌 **连接池管理**：自动维护设备连接，支持多设备并行控制
+- 🚀 **实时状态推送**：内置WebSocket状态推送工具
+- 🔍 **动态协议发现**：运行时自动加载用户协议实现
+
+## 安装
+
+```bash
+pip install device-protocol-sdk

device_protocol_sdk-1.2.6/README.md

@@ -0,0 +1,18 @@
+# Device Protocol SDK
+
+无人机设备协议开发工具包，提供标准化接口实现多类型无人机设备的快速接入。
+
+[![PyPI Version](https://img.shields.io/pypi/v/device-protocol-sdk)](https://pypi.org/project/device-protocol-sdk/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/device-protocol-sdk)](https://pypi.org/project/device-protocol-sdk/)
+
+## 功能特性
+
+- 🛠️ **协议无关抽象**：统一各类无人机设备的控制接口
+- 🔌 **连接池管理**：自动维护设备连接，支持多设备并行控制
+- 🚀 **实时状态推送**：内置WebSocket状态推送工具
+- 🔍 **动态协议发现**：运行时自动加载用户协议实现
+
+## 安装
+
+```bash
+pip install device-protocol-sdk

device_protocol_sdk-1.2.6/device_protocol_sdk/abstract_device.py

@@ -0,0 +1,222 @@
+from abc import ABC, abstractmethod
+import threading
+import json,uuid,time
+from typing import List
+from collections import defaultdict
+from .model.device_key import DeviceKey
+from .model.action_item import ActionItem
+from .model.device_status import DeviceStatus,MessageType,MessageLevel
+from typing import Dict, Any, Optional
+import grpc
+from . import device_pb2
+
+from contextlib import contextmanager
+from typing import Generator
+import logging
+logger = logging.getLogger(__name__)
+
+
+
+
+
+class AbstractDevice(ABC):
+    _status_cache: Dict[DeviceKey, dict] = {}
+    _connection_pool: Dict[DeviceKey, Any] = {}  # 类级连接池
+    _lock = threading.RLock()
+
+    _monitor_flags = defaultdict(bool)  # 状态监控标志
+    _monitor_futures = {}
+    _lock = threading.Lock()  # 线程安全锁
+    _status_lock = threading.RLock()  # 新增：状态读取可重入锁
+
+    def __init__(self):
+        self._grpc_stub = None
+        self._current_mission_id = None
+
+    def set_grpc_stub(self, grpc_stub):
+        """设置gRPC stub用于发送消息"""
+        self._grpc_stub = grpc_stub
+
+    def set_current_mission_id(self, mission_id: str):
+        """设置当前任务的mission_id"""
+        self._current_mission_id = mission_id
+
+    @contextmanager
+    def mission_context(self, mission_id: str) -> Generator[None, None, None]:
+        """为任务提供独立的上下文"""
+        original_mission_id = getattr(self, '_current_mission_id', None)
+        try:
+            self._current_mission_id = mission_id
+            yield
+        finally:
+            self._current_mission_id = original_mission_id
+    def send_message(self, device_id: int, message_type: MessageType, content: str,level:MessageLevel,
+                    metadata: Optional[Dict[str, Any]] = None,
+                    mission_id: Optional[str] = None) -> bool:
+        """
+        通过gRPC向服务端发送消息
+
+        Args:
+            message_type: 消息类型
+            content: 消息内容
+            metadata: 附加元数据
+            mission_id: 任务ID，如果为None则使用当前任务ID
+
+        Returns:
+            bool: 发送是否成功
+        """
+        target_mission_id = mission_id or self._current_mission_id
+        if not target_mission_id:
+            logger.warning("未提供mission_id且当前无任务上下文")
+            return False
+
+        if not self._grpc_stub:
+            logger.warning("gRPC stub未设置，无法发送消息")
+            return False
+
+        # 确定mission_id
+        target_mission_id = mission_id or self._current_mission_id
+        if not target_mission_id:
+            logger.warning("未提供mission_id且当前无任务ID，无法发送消息")
+            return False
+
+        try:
+            # 构建gRPC消息
+            device_message = device_pb2.DeviceMessage(
+                mission_id=target_mission_id,
+                message_type=message_type.value,
+                message_level=level.value,
+                content=content,
+                timestamp=int(time.time()),
+                metadata=json.dumps(metadata) if metadata else "",
+                device_id=int(device_id)
+            )
+
+            # 发送消息（假设服务端有ReceiveDeviceMessage方法）
+            self._grpc_stub.ReceiveDeviceMessage(device_message)
+
+        except grpc.RpcError as e:
+            logger.error(f"gRPC消息发送失败: {e}")
+            return False
+        except Exception as e:
+            logger.error(f"发送消息时发生异常: {e}")
+            return False
+
+    def send_text_message(self, device_id: int, text: str,level:MessageLevel, **kwargs) -> bool:
+        """发送纯文本消息的快捷方法"""
+        return self.send_message(device_id,MessageType.TEXT, text,level, **kwargs)
+
+    def send_image_message(self, device_id: int, image_data_or_url: str,level:MessageLevel, **kwargs) -> bool:
+        """发送图像消息的快捷方法"""
+        metadata = kwargs.pop('metadata', {})
+        if 'description' not in metadata:
+            metadata['description'] = '设备上传的图像'
+        return self.send_message(device_id,MessageType.IMAGE, image_data_or_url,level, metadata, **kwargs)
+
+    def send_video_url_message(self, device_id: int, video_url: str,level:MessageLevel, **kwargs) -> bool:
+        """发送视频URL消息的快捷方法"""
+        metadata = kwargs.pop('metadata', {})
+        if 'description' not in metadata:
+            metadata['description'] = '设备视频流地址'
+        return self.send_message(device_id,MessageType.VIDEO_URL, video_url,level, metadata, **kwargs)
+
+    @property
+    @abstractmethod
+    def protocol_name(self) -> str:
+        pass
+    
+    def is_cluster(self):
+        return 0
+    
+    @abstractmethod
+    def get_action_list(self) -> List[ActionItem]:
+        pass
+    def connect(self, device_key: DeviceKey) -> Any:
+        """带设备ID的连接池实现"""
+        with self._lock:
+            if device_key not in self._connection_pool:
+                is_connect,client = self._create_client(device_key.device_id,device_key.connection_str)
+                if is_connect:
+                    self._connection_pool[device_key] = client
+                return is_connect,client
+            else:
+                client = self._connection_pool[device_key]
+                return True,client
+
+
+    def disconnect(self, device_key: DeviceKey):
+        with self._lock:
+            if device_key in self._connection_pool:
+                self._close_client(self._connection_pool[device_key],device_key.device_id,device_key.connection_str)
+                # 清空连接池中对应device_key的数据
+                del self._connection_pool[device_key]
+                logger.info(f"已从连接池中移除设备 {device_key}")
+
+
+    def is_connected(self, device_key: DeviceKey) -> bool:
+        with self._lock:
+            if conn := self._connection_pool.get(device_key):
+                return True
+        return False
+
+    @abstractmethod
+    def _create_client(self,device_id:int, connection_str: str) -> tuple[bool, Any]:
+        pass
+
+    @abstractmethod
+    def _close_client(self,client, device_id: int, connection_str: str) -> Any:
+        pass
+
+    def get_device_status(self,client,device_id:str,connection_str:str) -> DeviceStatus:
+        pass
+    
+    def get_device_status_list(self,client,device_id:str,connection_str:str) -> List[DeviceStatus]:
+        pass
+
+    def _ensure_connection(self, device_key: DeviceKey) -> Any:
+        """确保设备连接存在，如果不存在则创建"""
+        client = self._connection_pool.get(device_key)
+        if client is not None:
+            return client
+
+        # 尝试连接
+        success, result = self.connect(device_key)
+        if not success:
+            raise ConnectionError(f"无法连接设备 {device_key.device_id}: {result}")
+
+        client = self._connection_pool.get(device_key)
+        if client is None:
+            raise ConnectionError(f"连接已建立但客户端对象缺失: {device_key.device_id}")
+
+        return client
+
+    def get_status(self, device_id: str, connection_str: str) -> DeviceStatus:
+        my_device = DeviceKey(device_id=device_id, connection_str=connection_str)
+
+        # 确保连接存在
+        client = self._ensure_connection(my_device)
+        is_cluster = self.is_cluster()
+        if is_cluster == 0:
+            return [self.get_device_status(client, device_id, connection_str)]
+        else:
+            return self.get_device_status_list(client, device_id, connection_str)
+
+    def excute_command(self,device_id:str,connection_str:str, command: str, params: Dict[str, Any],
+                      mission_id: str):
+        my_device = DeviceKey(device_id=device_id, connection_str=connection_str)
+        this_client = self._ensure_connection(my_device)
+        with self.mission_context(mission_id):
+            self.execute(this_client,device_id,connection_str,command,params)
+
+    @abstractmethod
+    def execute(self,client,device_id:int,connection_str:str, command: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """执行控制指令"""
+
+    def to_json(self):
+        """序列化设备信息"""
+        actions = [item.dict() for item in self.get_action_list()]
+        return json.dumps({
+            "protocol": self.protocol_name,
+            "action_list": actions,
+            "is_cluster": self.is_cluster()
+        }, ensure_ascii=False)

device_protocol_sdk-1.2.6/device_protocol_sdk/device_pb2.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: device.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'device.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0c\x64\x65vice.proto\x12\x06\x64\x65vice\"l\n\x0fRegisterRequest\x12\x15\n\rprotocol_name\x18\x01 \x01(\t\x12\x12\n\nauth_token\x18\x02 \x01(\t\x12\x14\n\x0c\x63\x61pabilities\x18\x03 \x01(\t\x12\x18\n\x10type_description\x18\x04 \x01(\t\"\x95\x01\n\x10RegisterResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x0f\n\x07message\x18\x02 \x01(\t\x12\x17\n\x0fmqtt_broker_url\x18\x03 \x01(\t\x12\x18\n\x10mqtt_broker_port\x18\x04 \x01(\t\x12\x15\n\rmqtt_username\x18\x05 \x01(\t\x12\x15\n\rmqtt_password\x18\x06 \x01(\t\"r\n\x0e\x43ommandRequest\x12\x12\n\ncommand_id\x18\x01 \x01(\t\x12\x12\n\nmission_id\x18\x02 \x01(\t\x12\x10\n\x08\x64rone_id\x18\x03 \x01(\t\x12\x16\n\x0e\x63onnection_str\x18\x04 \x01(\t\x12\x0e\n\x06params\x18\x05 \x01(\t\"d\n\nCommandAck\x12\x12\n\ncommand_id\x18\x01 \x01(\t\x12\x12\n\nmission_id\x18\x02 \x01(\t\x12\x0f\n\x07success\x18\x03 \x01(\x08\x12\x0f\n\x07message\x18\x04 \x01(\t\x12\x0c\n\x04\x64\x61ta\x18\x05 \x01(\t\"\x99\x01\n\rDeviceMessage\x12\x12\n\nmission_id\x18\x01 \x01(\t\x12\x14\n\x0cmessage_type\x18\x02 \x01(\t\x12\x15\n\rmessage_level\x18\x03 \x01(\t\x12\x0f\n\x07\x63ontent\x18\x04 \x01(\t\x12\x11\n\ttimestamp\x18\x05 \x01(\x03\x12\x10\n\x08metadata\x18\x06 \x01(\t\x12\x11\n\tdevice_id\x18\x07 \x01(\x03\"9\n\x15\x44\x65viceMessageResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x0f\n\x07message\x18\x02 \x01(\t2\xdd\x01\n\rDeviceService\x12=\n\x08Register\x12\x17.device.RegisterRequest\x1a\x18.device.RegisterResponse\x12?\n\rCommandStream\x12\x12.device.CommandAck\x1a\x16.device.CommandRequest(\x01\x30\x01\x12L\n\x14ReceiveDeviceMessage\x12\x15.device.DeviceMessage\x1a\x1d.device.DeviceMessageResponseb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'device_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_REGISTERREQUEST']._serialized_start=24
+  _globals['_REGISTERREQUEST']._serialized_end=132
+  _globals['_REGISTERRESPONSE']._serialized_start=135
+  _globals['_REGISTERRESPONSE']._serialized_end=284
+  _globals['_COMMANDREQUEST']._serialized_start=286
+  _globals['_COMMANDREQUEST']._serialized_end=400
+  _globals['_COMMANDACK']._serialized_start=402
+  _globals['_COMMANDACK']._serialized_end=502
+  _globals['_DEVICEMESSAGE']._serialized_start=505
+  _globals['_DEVICEMESSAGE']._serialized_end=658
+  _globals['_DEVICEMESSAGERESPONSE']._serialized_start=660
+  _globals['_DEVICEMESSAGERESPONSE']._serialized_end=717
+  _globals['_DEVICESERVICE']._serialized_start=720
+  _globals['_DEVICESERVICE']._serialized_end=941
+# @@protoc_insertion_point(module_scope)

device_protocol_sdk-1.2.6/device_protocol_sdk/device_pb2_grpc.py

@@ -0,0 +1,183 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from . import device_pb2 as device__pb2
+
+GRPC_GENERATED_VERSION = '1.74.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + f' but the generated code in device_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class DeviceServiceStub(object):
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Register = channel.unary_unary(
+                '/device.DeviceService/Register',
+                request_serializer=device__pb2.RegisterRequest.SerializeToString,
+                response_deserializer=device__pb2.RegisterResponse.FromString,
+                _registered_method=True)
+        self.CommandStream = channel.stream_stream(
+                '/device.DeviceService/CommandStream',
+                request_serializer=device__pb2.CommandAck.SerializeToString,
+                response_deserializer=device__pb2.CommandRequest.FromString,
+                _registered_method=True)
+        self.ReceiveDeviceMessage = channel.unary_unary(
+                '/device.DeviceService/ReceiveDeviceMessage',
+                request_serializer=device__pb2.DeviceMessage.SerializeToString,
+                response_deserializer=device__pb2.DeviceMessageResponse.FromString,
+                _registered_method=True)
+
+
+class DeviceServiceServicer(object):
+    """Missing associated documentation comment in .proto file."""
+
+    def Register(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def CommandStream(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def ReceiveDeviceMessage(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_DeviceServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Register': grpc.unary_unary_rpc_method_handler(
+                    servicer.Register,
+                    request_deserializer=device__pb2.RegisterRequest.FromString,
+                    response_serializer=device__pb2.RegisterResponse.SerializeToString,
+            ),
+            'CommandStream': grpc.stream_stream_rpc_method_handler(
+                    servicer.CommandStream,
+                    request_deserializer=device__pb2.CommandAck.FromString,
+                    response_serializer=device__pb2.CommandRequest.SerializeToString,
+            ),
+            'ReceiveDeviceMessage': grpc.unary_unary_rpc_method_handler(
+                    servicer.ReceiveDeviceMessage,
+                    request_deserializer=device__pb2.DeviceMessage.FromString,
+                    response_serializer=device__pb2.DeviceMessageResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'device.DeviceService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('device.DeviceService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class DeviceService(object):
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Register(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/device.DeviceService/Register',
+            device__pb2.RegisterRequest.SerializeToString,
+            device__pb2.RegisterResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def CommandStream(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/device.DeviceService/CommandStream',
+            device__pb2.CommandAck.SerializeToString,
+            device__pb2.CommandRequest.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def ReceiveDeviceMessage(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/device.DeviceService/ReceiveDeviceMessage',
+            device__pb2.DeviceMessage.SerializeToString,
+            device__pb2.DeviceMessageResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

device_protocol_sdk-1.2.6/device_protocol_sdk/model/action_item.py

@@ -0,0 +1,12 @@
+# action_item.py
+from dataclasses import dataclass, asdict
+from typing import Dict, Any
+@dataclass
+class ActionItem:
+    name: str  # 动作名称
+    command_type: str  # 动作唯一标识
+    description: str  # 描述
+    params: Dict[str, Any]  # JSON Schema 或简单 dict 描述
+
+    def dict(self) -> Dict[str, Any]:
+        return asdict(self)

device_protocol_sdk-1.2.6/device_protocol_sdk/model/device_key.py

@@ -0,0 +1,8 @@
+# device_key.py
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class DeviceKey:
+    """不可变的设备唯一标识"""
+    device_id: str  # 业务唯一字符串
+    connection_str: str  # 连接参数（如IP/串口号）

device_protocol_sdk-1.2.6/device_protocol_sdk/model/device_status.py

@@ -0,0 +1,35 @@
+# device_status.py
+from typing import TypedDict, Optional
+from enum import Enum
+
+class DeviceStatus(TypedDict, total=False):
+    """设备状态固定格式"""
+    is_lock: Optional[int]  # 必填
+    heartbeat: Optional[int]  # 必填
+    battery: Optional[float]  # 必填
+    airspeed: Optional[float]  # 必填
+    groundspeed: Optional[float]  # 必填
+    yaw_degrees: Optional[float]  # 必填
+    roll: Optional[float]  # 必填
+    pitch: Optional[float]  # 必填
+    yaw: Optional[float]  # 必填
+    lat: Optional[float]  # 必填
+    lon: Optional[float]  # 必填
+    alt: Optional[float]  # 必填
+    vzspeed: Optional[float]  # 必填
+    height: Optional[float]  # 必填
+
+
+class MessageType(Enum):
+    TEXT = "text"  # 纯文本消息
+    IMAGE = "image"  # 图像消息
+    VIDEO_URL = "video_url"  # 视频流URL
+    PROGRESS = "progress"  # 进度更新
+    STATUS = "status"  # 状态更新
+
+#消息级别: failed, warning, info, success
+class MessageLevel(Enum):
+    FAILED = "failed"
+    WARNING = "warning"
+    INFO = "info"
+    SUCCESS = "success"