rabo-robocap 2.0.0__py3-none-any.whl

rabo_robocap/__init__.py

@@ -0,0 +1,77 @@
+"""
+rabo_robocap: ROS2 机器人能力封装
+
+PyPI 发布的 loader shell — 核心代码从阿里云 OSS 自动拉取。
+设置环境变量 RABO_DEV=1 可跳过 loader，直接从源码导入（开发/测试用）。
+
+Usage:
+    from rabo_robocap import UR5
+
+    # 仿真模式
+    arm = UR5(robot_id='ur5_model', mode='sim')
+
+    # 真实硬件
+    arm = UR5(robot_id='ur5', mode='real')
+
+    arm.move_to(0.3, 0.2, 0.4)
+"""
+
+import os
+import sys
+
+if os.environ.get("RABO_DEV"):
+    # ---- 开发模式：直接从源码导入 ----
+    from .exceptions import (
+        RobocapError, IKSolutionError, JointLimitError,
+        CommunicationError, TrajectoryError,
+    )
+    from .arms import UR5, UR10, GalaxeaA1X
+    from .mobile import AgilexScoutMini, GalaxeaR1LiteChassis
+    from .clients import MobileClient, ArmClient, TorsoClient, GripperClient
+    from .torso import GalaxeaR1LiteTorso
+    from .grippers import GalaxeaG1Gripper
+    from .base import ArmBase, MobileBase, TorsoBase, GripperBase
+
+    __version__ = "2.0.0-dev"
+
+    def check_update():
+        print("rabo_robocap: dev mode (RABO_DEV=1), hot-update disabled")
+else:
+    # ---- 生产模式：从 OSS 缓存的 zip 加载 ----
+    from ._updater import ensure_updated, get_core_zip_path, install_redirector, check_update
+
+    # 1. 确保核心包是最新的（检查缓存/下载）
+    ensure_updated()
+
+    # 2. 将 zip 加入 sys.path（zipimport）
+    _zip_path = get_core_zip_path()
+    if _zip_path not in sys.path:
+        sys.path.insert(0, _zip_path)
+
+    # 3. 安装 import 重定向（支持 from rabo_robocap.arms import UR5）
+    install_redirector()
+
+    # 4. 从 _rabo_core 导入并重新导出
+    from _rabo_core import __version__  # noqa: E402
+    from _rabo_core.arms import UR5, UR10, GalaxeaA1X  # noqa: E402
+    from _rabo_core.mobile import AgilexScoutMini, GalaxeaR1LiteChassis  # noqa: E402
+    from _rabo_core.clients import MobileClient, ArmClient, TorsoClient, GripperClient  # noqa: E402
+    from _rabo_core.torso import GalaxeaR1LiteTorso  # noqa: E402
+    from _rabo_core.grippers import GalaxeaG1Gripper  # noqa: E402
+    from _rabo_core.exceptions import (  # noqa: E402
+        RobocapError, IKSolutionError, JointLimitError,
+        CommunicationError, TrajectoryError,
+    )
+    from _rabo_core.base import ArmBase, MobileBase, TorsoBase, GripperBase  # noqa: E402
+
+__all__ = [
+    '__version__',
+    'UR5', 'UR10', 'GalaxeaA1X',
+    'AgilexScoutMini', 'GalaxeaR1LiteChassis',
+    'MobileClient', 'ArmClient', 'TorsoClient', 'GripperClient',
+    'GalaxeaR1LiteTorso',
+    'GalaxeaG1Gripper',
+    'ArmBase', 'MobileBase', 'TorsoBase', 'GripperBase',
+    'RobocapError', 'IKSolutionError', 'JointLimitError',
+    'CommunicationError', 'TrajectoryError',
+]

rabo_robocap/_updater.py

@@ -0,0 +1,250 @@
+"""
+Hot-update loader: 从阿里云 OSS 拉取最新核心代码 zip，本地缓存后 zipimport。
+
+流程:
+  1. import rabo_robocap 时调用 ensure_updated()
+  2. 检查本地 meta.json 的 last_check 时间戳，TTL 内跳过
+  3. TTL 过期 → GET version.json，比较版本
+  4. 远端更新 → 下载 core-cp3{minor}.zip
+  5. 网络异常 → 静默使用本地缓存
+  6. 无缓存 + 无网络 → 抛出明确错误
+"""
+
+import importlib
+import importlib.abc
+import importlib.machinery
+import importlib.util
+import json
+import logging
+import os
+import sys
+import time
+import types
+import urllib.request
+import urllib.error
+
+logger = logging.getLogger("rabo_robocap._updater")
+
+# ---------------------------------------------------------------------------
+# 配置
+# ---------------------------------------------------------------------------
+OSS_BASE_URL = (
+    "https://rabo-apt-repo.oss-cn-hangzhou.aliyuncs.com/rabo_robocap/"
+)
+CACHE_DIR = os.path.join(os.path.expanduser("~"), ".rabo_robocap")
+_HTTP_TIMEOUT = 10  # 秒
+
+# Python 版本标识
+_PY_TAG = f"cp3{sys.version_info.minor}"
+_ZIP_NAME = f"core-{_PY_TAG}.zip"
+
+# 本地文件路径
+_META_PATH = os.path.join(CACHE_DIR, "meta.json")
+_ZIP_PATH = os.path.join(CACHE_DIR, _ZIP_NAME)
+
+# 内部核心包名（zip 内的顶层目录）
+_CORE_PACKAGE = "_rabo_core"
+
+
+# ---------------------------------------------------------------------------
+# 内部工具
+# ---------------------------------------------------------------------------
+
+def _read_meta():
+    """读取本地 meta.json，不存在或损坏返回空 dict。"""
+    try:
+        with open(_META_PATH, "r") as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+
+
+def _write_meta(meta):
+    """写入本地 meta.json。"""
+    os.makedirs(CACHE_DIR, exist_ok=True)
+    with open(_META_PATH, "w") as f:
+        json.dump(meta, f)
+
+
+def _fetch_json(url):
+    """GET 请求并解析 JSON，失败返回 None。"""
+    try:
+        req = urllib.request.Request(url)
+        with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError, json.JSONDecodeError, ValueError) as e:
+        logger.debug("fetch %s failed: %s", url, e)
+        return None
+
+
+def _download_file(url, dest):
+    """下载文件到 dest，成功返回 True。"""
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    tmp = dest + ".tmp"
+    try:
+        req = urllib.request.Request(url)
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            with open(tmp, "wb") as f:
+                while True:
+                    chunk = resp.read(65536)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+        # 原子替换
+        if os.path.exists(dest):
+            os.remove(dest)
+        os.rename(tmp, dest)
+        return True
+    except (urllib.error.URLError, OSError) as e:
+        logger.debug("download %s failed: %s", url, e)
+        # 清理临时文件
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        return False
+
+
+def _version_tuple(version_str):
+    """将 '1.2.3' 转成 (1, 2, 3) 用于比较。"""
+    try:
+        return tuple(int(x) for x in version_str.split("."))
+    except (ValueError, AttributeError):
+        return (0,)
+
+
+# ---------------------------------------------------------------------------
+# 公开 API
+# ---------------------------------------------------------------------------
+
+def ensure_updated():
+    """检查并更新核心包。每次 import 时调用。
+
+    - 每次都检查远端版本，有更新就下载
+    - 网络异常 → 静默使用本地缓存
+    - 无缓存 + 无网络 → RuntimeError
+    """
+    meta = _read_meta()
+
+    # 尝试获取远端版本信息
+    remote = _fetch_json(OSS_BASE_URL + "version.json")
+
+    if remote is not None:
+        remote_ver = remote.get("version", "0.0.0")
+        local_ver = meta.get("version", "0.0.0")
+
+        if remote_ver != local_ver or not os.path.isfile(_ZIP_PATH):
+            # 需要下载
+            zip_url = OSS_BASE_URL + _ZIP_NAME
+            logger.info("rabo_robocap: downloading %s (v%s)...", _ZIP_NAME, remote_ver)
+            if _download_file(zip_url, _ZIP_PATH):
+                meta["version"] = remote_ver
+                logger.info("rabo_robocap: updated to v%s", remote_ver)
+                _write_meta(meta)
+            else:
+                logger.warning("rabo_robocap: download failed, using cache if available")
+    else:
+        # 网络不可用
+        if os.path.isfile(_ZIP_PATH):
+            logger.debug("rabo_robocap: offline, using cached core")
+        else:
+            raise RuntimeError("rabo_robocap 初始化失败，请检查网络连接")
+
+
+def check_update():
+    """打印当前版本信息并检查远端是否有更新。
+
+    Usage:
+        import rabo_robocap
+        rabo_robocap.check_update()
+    """
+    meta = _read_meta()
+    local_ver = meta.get("version", "unknown")
+    has_cache = os.path.isfile(_ZIP_PATH)
+
+    print(f"rabo_robocap hot-update status:")
+    print(f"  local core version : {local_ver}")
+    print(f"  cache file         : {_ZIP_PATH} ({'exists' if has_cache else 'MISSING'})")
+
+    # 查询远端
+    print(f"  checking remote    : {OSS_BASE_URL}version.json ...")
+    remote = _fetch_json(OSS_BASE_URL + "version.json")
+    if remote is None:
+        print(f"  remote version     : unavailable (network error)")
+    else:
+        remote_ver = remote.get("version", "unknown")
+        print(f"  remote version     : {remote_ver}")
+        if remote_ver != local_ver:
+            print(f"  status             : VERSION CHANGED ({local_ver} → {remote_ver})")
+            print(f"  restart Python to load the new version")
+        else:
+            print(f"  status             : up to date")
+
+
+def get_core_zip_path():
+    """返回核心 zip 路径，不存在则抛错。"""
+    if os.path.isfile(_ZIP_PATH):
+        return _ZIP_PATH
+    raise RuntimeError(
+        f"rabo_robocap: core zip not found at '{_ZIP_PATH}'. "
+        "Run ensure_updated() first."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Import 重定向器（使用 find_spec API，兼容 Python 3.4+）
+# ---------------------------------------------------------------------------
+
+class _CoreRedirector(importlib.abc.MetaPathFinder):
+    """将 rabo_robocap.* 的子包导入重定向到 _rabo_core.*
+
+    例如:
+      from rabo_robocap.arms import UR5
+      → 实际导入 _rabo_core.arms.UR5
+
+    仅拦截 rabo_robocap 的子模块，不拦截 rabo_robocap 本身。
+    """
+
+    _PREFIX = "rabo_robocap."
+
+    def find_spec(self, fullname, path, target=None):
+        if not fullname.startswith(self._PREFIX):
+            return None
+
+        # rabo_robocap.arms.ur5 → _rabo_core.arms.ur5
+        core_name = _CORE_PACKAGE + fullname[len("rabo_robocap"):]
+
+        return importlib.machinery.ModuleSpec(
+            fullname,
+            _CoreLoader(core_name),
+        )
+
+
+class _CoreLoader(importlib.abc.Loader):
+    """将 rabo_robocap.xxx 加载为 _rabo_core.xxx 的代理。"""
+
+    def __init__(self, core_name):
+        self._core_name = core_name
+
+    def create_module(self, spec):
+        # 加载真实模块
+        real_mod = importlib.import_module(self._core_name)
+        # 注册到 sys.modules 供后续直接命中
+        sys.modules[spec.name] = real_mod
+        return real_mod
+
+    def exec_module(self, module):
+        # create_module 已完成所有工作，无需额外执行
+        pass
+
+
+_redirector_installed = False
+
+
+def install_redirector():
+    """在 sys.meta_path 中安装重定向器（幂等）。"""
+    global _redirector_installed
+    if _redirector_installed:
+        return
+    sys.meta_path.insert(0, _CoreRedirector())
+    _redirector_installed = True

rabo_robocap/exceptions.py

@@ -0,0 +1,57 @@
+"""rabo_robocap 异常定义"""
+
+
+class RobocapError(Exception):
+    """rabo_robocap 基础异常类"""
+    pass
+
+
+class IKSolutionError(RobocapError):
+    """逆运动学无解异常"""
+
+    def __init__(self, target_pose=None, message=None):
+        self.target_pose = target_pose
+        if message is None:
+            message = "无法找到逆运动学解"
+            if target_pose is not None:
+                message += f": target={target_pose}"
+        super().__init__(message)
+
+
+class JointLimitError(RobocapError):
+    """关节超限异常"""
+
+    def __init__(self, joint_index=None, value=None, limits=None, message=None):
+        self.joint_index = joint_index
+        self.value = value
+        self.limits = limits
+        if message is None:
+            message = "关节角度超出限位"
+            if joint_index is not None:
+                message += f": joint[{joint_index}]={value}, limits={limits}"
+        super().__init__(message)
+
+
+class CommunicationError(RobocapError):
+    """通信超时异常"""
+
+    def __init__(self, topic=None, timeout=None, message=None):
+        self.topic = topic
+        self.timeout = timeout
+        if message is None:
+            message = "通信超时"
+            if topic is not None:
+                message += f": topic={topic}, timeout={timeout}s"
+        super().__init__(message)
+
+
+class TrajectoryError(RobocapError):
+    """轨迹规划/执行异常"""
+
+    def __init__(self, reason=None, message=None):
+        self.reason = reason
+        if message is None:
+            message = "轨迹执行失败"
+            if reason is not None:
+                message += f": {reason}"
+        super().__init__(message)

rabo_robocap-2.0.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: rabo_robocap
+Version: 2.0.0
+Summary: rabo_robocap: ROS2 机器人能力封装
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: build
+Requires-Dist: oss2; extra == "build"
+
+# rabo_robocap
+
+ROS2 机器人能力封装 SDK，为 Gazebo 仿真中的机器人提供高级控制接口。
+
+支持热更新：`pip install` 一次后，每次 `import` 自动获取最新版本。
+
+## 安装
+
+```bash
+# 1. 安装 Python 包（仅需一次）
+pip install rabo_robocap
+
+# 2. 构建 ROS2 消息包（需要 ROS2 环境）
+cd ~/ros2_ws/src/rabo-lib
+colcon build --paths rabo_robocap_msgs
+source install/setup.bash
+```
+
+详细构建说明请参考 [构建指南](docs/build.md)。
+
+## 使用
+
+### 移动底盘
+
+```python
+from rabo_robocap import AgilexScoutMini
+
+# 仿真模式（自动从 API 获取配置，rclpy 自动初始化）
+base = AgilexScoutMini(robot_id='scout_model', mode='sim')
+
+# 或 真实硬件模式
+# base = AgilexScoutMini(robot_id='scout', mode='real')
+
+base.set_velocity(linear_x=0.5, angular_z=0.0)
+base.move_distance(1.0)
+x, y, theta = base.get_odometry()
+print(f"Position: ({x:.2f}, {y:.2f}), Heading: {theta:.2f}")
+
+base.shutdown()
+```
+
+### 机械臂
+
+```python
+import numpy as np
+from rabo_robocap import UR5
+
+# 仿真模式
+arm = UR5(robot_id='ur5_model', mode='sim')
+
+# 或 真实硬件
+# arm = UR5(robot_id='ur5', mode='real')
+
+# 移动到 ready 位置
+arm.move_joints([0, -np.pi/2, np.pi/2, -np.pi/2, -np.pi/2, 0])
+
+# 移动到目标位置
+arm.move_to(0.3, 0.2, 0.4)
+
+# 获取当前位姿
+pos, ori = arm.get_pose()
+print(f"Position: {pos}")
+
+arm.shutdown()
+```
+
+### 版本管理
+
+```python
+import rabo_robocap
+
+# 查看当前版本
+print(rabo_robocap.__version__)
+
+# 查看更新状态
+rabo_robocap.check_update()
+```
+
+**注意**：
+- rclpy 自动初始化，无需手动调用 `rclpy.init()`
+- 节点内部自动管理 ROS2 回调，**不要**将节点添加到外部 executor
+
+## 文档
+
+- [构建指南](docs/build.md)
+- [整体架构](docs/architecture.md)
+- [AgilexScoutMini 移动底盘](docs/robots/mobile_agilex_scout_mini.md)
+- [GalaxeaR1LiteChassis 移动底盘](docs/robots/mobile_galaxea_r1_lite_chassis.md)
+- [UR 系列机械臂](docs/robots/arm_ur_series.md)
+- [设计规则](CLAUDE.md)

rabo_robocap-2.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rabo_robocap/__init__.py,sha256=I1pqcyTQ_mh5P9oxpzI3xMpFajsoDZjwsZQ_Er8ScIM,2769
+rabo_robocap/_updater.py,sha256=z3tS-z306jeuFvL9ftsPNhq6QRW3TFoV0G0aZ0DKrtQ,7987
+rabo_robocap/exceptions.py,sha256=nLk906wmoVyuZpZuE0iYqNY8FHq3qAxnZCQbq8UPIzQ,1694
+rabo_robocap-2.0.0.dist-info/METADATA,sha256=ojImKFkj6xOtHw9aB-ZGg0niCrGu0m56e5CLNf7HIbM,2404
+rabo_robocap-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rabo_robocap-2.0.0.dist-info/top_level.txt,sha256=XsAkBJVF6ZfyM071uWwDZbNcns-MJ7kPRoEzkLXzltI,13
+rabo_robocap-2.0.0.dist-info/RECORD,,

rabo_robocap-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rabo_robocap-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rabo_robocap