zeroArm-sdk 0.1.2__tar.gz

zeroarm_sdk-0.1.2/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) ForceEase Co.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zeroarm_sdk-0.1.2/MANIFEST.in

@@ -0,0 +1,9 @@
+# MANIFEST.in
+include LICENSE.txt
+include README.md
+include zeroArm_sdk/_core.pyx
+recursive-include zeroArm_sdk/locale *.mo
+exclude zeroArm_sdk/**/*.c
+exclude zeroArm_sdk/**/*.html
+global-exclude *.so
+global-exclude *.pyd

zeroarm_sdk-0.1.2/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: zeroArm_sdk
+Version: 0.1.2
+Summary: Official SDK for ZeroArm robotic arm (proprietary)
+Home-page: https://github.com/HANCKH/zeroArm_python_sdk
+Author: ForceEase Co.
+Author-email: "ForceEase Co." <support@forceease.tech>
+License: MIT
+Project-URL: Source, https://github.com/HANCKH/zeroArm_python_sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Cython
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyzmq>=25.0
+Requires-Dist: websockets
+Requires-Dist: zeroconf
+Requires-Dist: tqdm
+Dynamic: author
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+
+# ZeroArm Python SDK
+
+Official Python SDK for ForceEase ZeroArm robotic arms.
+
+## Connection Notes
+
+- Use `RobotArm().auto_discover_and_connect()` for the default LAN workflow.
+- Use `connect_with_short_sn()` with at least the first 8 serial-number characters in multi-arm environments.
+- mDNS discovery only accepts connectable IPv4 addresses and ignores loopback or unspecified addresses such as `127.0.0.1` and `0.0.0.0`.
+- The controller advertises WebSocket control port `8888` and bridge port `8889`; SDK mode uses the fixed ZMQ command/state ports `6666/6667`.
+
+## Current Protocol Coverage
+
+- `set_tf(..., plan_mode=0)` uses joint-space planning; `plan_mode=1` uses Cartesian planning.
+- `enable_hold_current()` asks the controller to hold all configured joints at their current feedback positions.
+- `set_joints_batch()` sends a single `raw_msg` command through the normal `commands_<serial>` topic.
+
+## Build Notes
+
+- `pyproject.toml` declares Cython as a build-system dependency for isolated builds.
+- For direct `setup.py` builds, install `requirements-build.txt` first.
+- `setuptools` is capped below 80 to stay compatible with ROS `colcon-core` in the shared development environment.
+
+## Release
+
+- Publish Python SDK releases through `.github/workflows/build-wheels.yml`.
+- A GitHub Release with action `published` builds the sdist plus Linux, Windows, and macOS wheels, then uploads all distributions to PyPI in one publish job.
+- The workflow expects `PYPI_API_TOKEN` to be configured as a GitHub Actions secret.
+
+## Version
+
+Current SDK source version: `0.1.2`.

zeroarm_sdk-0.1.2/README.md

@@ -0,0 +1,32 @@
+# ZeroArm Python SDK
+
+Official Python SDK for ForceEase ZeroArm robotic arms.
+
+## Connection Notes
+
+- Use `RobotArm().auto_discover_and_connect()` for the default LAN workflow.
+- Use `connect_with_short_sn()` with at least the first 8 serial-number characters in multi-arm environments.
+- mDNS discovery only accepts connectable IPv4 addresses and ignores loopback or unspecified addresses such as `127.0.0.1` and `0.0.0.0`.
+- The controller advertises WebSocket control port `8888` and bridge port `8889`; SDK mode uses the fixed ZMQ command/state ports `6666/6667`.
+
+## Current Protocol Coverage
+
+- `set_tf(..., plan_mode=0)` uses joint-space planning; `plan_mode=1` uses Cartesian planning.
+- `enable_hold_current()` asks the controller to hold all configured joints at their current feedback positions.
+- `set_joints_batch()` sends a single `raw_msg` command through the normal `commands_<serial>` topic.
+
+## Build Notes
+
+- `pyproject.toml` declares Cython as a build-system dependency for isolated builds.
+- For direct `setup.py` builds, install `requirements-build.txt` first.
+- `setuptools` is capped below 80 to stay compatible with ROS `colcon-core` in the shared development environment.
+
+## Release
+
+- Publish Python SDK releases through `.github/workflows/build-wheels.yml`.
+- A GitHub Release with action `published` builds the sdist plus Linux, Windows, and macOS wheels, then uploads all distributions to PyPI in one publish job.
+- The workflow expects `PYPI_API_TOKEN` to be configured as a GitHub Actions secret.
+
+## Version
+
+Current SDK source version: `0.1.2`.

zeroarm_sdk-0.1.2/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0,<80", "wheel", "Cython>=3.0", "packaging>=24.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zeroArm_sdk"
+version = "0.1.2"
+description = "Official SDK for ZeroArm robotic arm (proprietary)"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    {name = "ForceEase Co.", email = "support@forceease.tech"},
+]
+dynamic = ["license"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Cython",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pyzmq >= 25.0",
+    "websockets",
+    "zeroconf",
+    "tqdm",
+]
+
+[project.urls]
+Source = "https://github.com/HANCKH/zeroArm_python_sdk"
+
+[tool.cibuildwheel]
+build = "cp39-* cp310-* cp311-* cp312-*"
+
+manylinux-x86_64-image = "quay.io/pypa/manylinux2014_x86_64:latest"
+manylinux-aarch64-image = "quay.io/pypa/manylinux2014_aarch64:latest"
+
+archs = ["x86_64", "aarch64"]

zeroarm_sdk-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zeroarm_sdk-0.1.2/setup.py

@@ -0,0 +1,76 @@
+# setup.py（完整版 - 推荐使用此版本）
+
+from setuptools import setup, Extension, Command
+from Cython.Build import cythonize
+import os
+import shutil
+
+class CleanCython(Command):
+    """自定义命令：清理 Cython 生成的 .c 和 .html 文件"""
+    user_options = []
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        for root, dirs, files in os.walk("zeroArm_sdk"):
+            for file in files:
+                if file.endswith((".c", ".html", ".so", ".pyd")):
+                    file_path = os.path.join(root, file)
+                    print(f"Removing {file_path}")
+                    os.remove(file_path)
+
+setup(
+    name="zeroArm_sdk",
+    version="0.1.2",
+    author="ForceEase Co.",
+    author_email="support@forceease.tech",
+    url="https://github.com/HANCKH/zeroArm_python_sdk",
+    description="Python SDK for ZeroArm robotic arms",
+    license="MIT",
+    license_files=[],
+    long_description=open("README.md", encoding="utf-8").read() if os.path.exists("README.md") else "",
+    long_description_content_type="text/markdown",
+    packages=["zeroArm_sdk"],
+    package_dir={"zeroArm_sdk": "zeroArm_sdk"},
+    ext_modules=cythonize([
+        Extension(
+            "zeroArm_sdk._core",
+            sources=["zeroArm_sdk/_core.pyx"],
+        )
+    ], compiler_directives={"language_level": "3"}),
+    package_data={
+        "zeroArm_sdk": [
+            "locale/*/LC_MESSAGES/*.mo",
+        ]
+    },
+    include_package_data=False,
+    exclude_package_data={
+        "zeroArm_sdk": [
+            "*.pyx",
+            "*.c",
+            "*.html",
+            "**/*.pyx",
+            "**/*.c",
+            "**/*.html",
+        ]
+    },
+    install_requires=[
+        "pyzmq>=25.0",
+        "websockets",
+        "zeroconf",
+        "tqdm",
+    ],
+    python_requires=">=3.8",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Cython",
+        "Operating System :: OS Independent",
+    ],
+    cmdclass={
+        'clean_cython': CleanCython, 
+    },
+)

zeroarm_sdk-0.1.2/zeroArm_sdk/__init__.py

@@ -0,0 +1,9 @@
+# zeroArm_sdk/__init__.py
+# Copyright (c) 2026 ForceEase Co. All Rights Reserved.
+
+from .arm import RobotArm
+from .arm_types import JointState, GripperState, Pose, FullArmState
+from .exceptions import ArmNotFoundError, ArmConnectionError, ArmCommandError
+
+__version__ = "0.1.2"
+__author__ = "ForceEase Co."

zeroarm_sdk-0.1.2/zeroArm_sdk/_core.pyx

@@ -0,0 +1,569 @@
+# zeroArm_sdk/_core.pyx
+# Copyright (c) 2026 Han / ForceEase Co. All Rights Reserved.
+# Core implementation module - to be compiled into .so
+
+import asyncio
+import json
+import ipaddress
+import socket
+import time
+from typing import Dict, List, Optional, Callable
+from tqdm import tqdm
+import os
+import gettext
+import zmq
+import zmq.asyncio
+import websockets
+from zeroconf import Zeroconf, ServiceBrowser, ServiceListener
+from .arm_types import JointState, GripperState, Pose, FullArmState
+from .exceptions import ArmNotFoundError, ArmConnectionError, ArmCommandError
+
+cdef str localedir = os.path.join(os.path.dirname(__file__), "locale")
+cdef object translation = gettext.translation(
+    "zeroArm_sdk",
+    localedir,
+    fallback=True
+)
+cdef str _(str message):
+    return translation.gettext(message)
+
+# =============================================================================
+# Discovery Logic
+# =============================================================================
+def _decode_property(value):
+    if isinstance(value, bytes):
+        return value.decode(errors="ignore")
+    return str(value)
+
+
+def _is_connectable_ip(raw_ip) -> bool:
+    ip_text = str(raw_ip or "").strip()
+    if not ip_text:
+        return False
+    try:
+        parsed_ip = ipaddress.ip_address(ip_text)
+    except ValueError:
+        return False
+    return (
+        parsed_ip.version == 4
+        and not parsed_ip.is_loopback
+        and not parsed_ip.is_unspecified
+    )
+
+
+def _append_connectable_ip(ips: List[str], raw_ip):
+    ip_text = str(raw_ip or "").strip()
+    if _is_connectable_ip(ip_text) and ip_text not in ips:
+        ips.append(ip_text)
+
+
+def _extract_connectable_ips(info, props: Dict) -> List[str]:
+    ips: List[str] = []
+    for advertised_ip in str(props.get("ip", "")).split(","):
+        _append_connectable_ip(ips, advertised_ip)
+
+    for addr in getattr(info, "addresses", []) or []:
+        try:
+            if len(addr) == 4:
+                _append_connectable_ip(ips, socket.inet_ntoa(addr))
+            elif hasattr(socket, "inet_ntop"):
+                _append_connectable_ip(ips, socket.inet_ntop(socket.AF_INET6, addr))
+        except Exception:
+            continue
+    return ips
+
+
+def _int_property(props: Dict, key: str, default: int) -> int:
+    try:
+        return int(props.get(key, default))
+    except (TypeError, ValueError):
+        return default
+
+
+class ArmListener(ServiceListener):
+    def __init__(self):
+        self.arms = []
+
+    def add_service(self, zeroconf, type_str, name):
+        info = zeroconf.get_service_info(type_str, name)
+        if not info:
+            return
+        props = {_decode_property(k): _decode_property(v)
+                 for k, v in info.properties.items()}
+        ips = _extract_connectable_ips(info, props)
+        try:
+            sns = json.loads(props.get("available_sns", "[]"))
+        except json.JSONDecodeError:
+            sns = []
+        if sns and ips:
+            self.arms = [arm for arm in self.arms if arm.get("name") != name]
+            self.arms.append({
+                "name": name,
+                "ips": ips,
+                "sns": sns,
+                "control_port": _int_property(props, "control_ws_port", 8888),
+                "zmq_cmd_port": _int_property(props, "zmq_cmd_port", 6666),
+            })
+
+    def remove_service(self, zeroconf, type_str, name):
+        pass
+
+    def update_service(self, zeroconf, type_str, name):
+        self.add_service(zeroconf, type_str, name)
+
+
+async def discover_arms(timeout: float = 1.0) -> List[Dict]:
+    """Discover all available ZeroArm devices via mDNS."""
+    zeroconf = Zeroconf()
+    listener = ArmListener()
+    ServiceBrowser(zeroconf, "_armcontrol._tcp.local.", listener)
+    await asyncio.sleep(timeout)
+    zeroconf.close()
+    return listener.arms
+
+
+# =============================================================================
+# Communicator Class
+# =============================================================================
+cdef class ArmCommunicator:
+    cdef str ip
+    cdef str sn
+    cdef int control_port
+    cdef int zmq_cmd_port
+    cdef public object last_state
+    cdef public object state_callback
+    cdef object ctx
+    cdef object cmd_pub
+    cdef object state_sub
+    cdef public bint running
+    cdef object _recv_task
+
+    def __init__(self, str ip, str sn, int control_port=8888, int zmq_cmd_port=6666):
+        self.ip = ip
+        self.sn = sn
+        self.control_port = control_port
+        self.zmq_cmd_port = zmq_cmd_port
+        self.last_state = None
+        self.state_callback = None
+        self.ctx = zmq.asyncio.Context()
+        self.cmd_pub = self.ctx.socket(zmq.PUB)
+        self.state_sub = self.ctx.socket(zmq.SUB)
+        self.running = True
+        self._recv_task = None
+
+    async def select_sn(self) -> bool:
+        uri = f"ws://{self.ip}:{self.control_port}"
+        try:
+            async with websockets.connect(uri) as ws:
+                msg = json.dumps({"type": "select_sn", "sn": self.sn, "sdk": True})
+                await ws.send(msg)
+                response = await asyncio.wait_for(ws.recv(), timeout=20.0)
+                data = json.loads(response)
+                return data.get("type") == "select_ack"
+        except Exception:
+            return False
+
+    async def shutdown_control(self) -> bool:
+        uri = f"ws://{self.ip}:{self.control_port}"
+        try:
+            async with websockets.connect(uri) as ws:
+                msg = json.dumps({"type": "shutdown_control", "sn": self.sn})
+                await ws.send(msg)
+                response = await asyncio.wait_for(ws.recv(), timeout=1.0)
+                data = json.loads(response)
+                return data.get("type") == "shutdown_ack"
+        except Exception:
+            return False
+
+    async def connect_zmq(self) -> bool:
+        try:
+            self.cmd_pub.connect(f"tcp://{self.ip}:{self.zmq_cmd_port}")
+            self.state_sub.connect(f"tcp://{self.ip}:{self.zmq_cmd_port + 1}")
+            self.state_sub.setsockopt(zmq.SUBSCRIBE, f"states_{self.sn}".encode())
+            self._recv_task = asyncio.create_task(self._recv_states_loop())
+            return True
+        except Exception:
+            return False
+
+    async def _recv_states_loop(self):
+        poller = zmq.asyncio.Poller()
+        poller.register(self.state_sub, zmq.POLLIN)
+        while self.running:
+            events = await poller.poll(timeout=500)
+            if not events:
+                continue
+            topic, payload = await self.state_sub.recv_multipart()
+            if topic.decode() == f"states_{self.sn}":
+                try:
+                    raw_state = json.loads(payload)
+                    parsed_state = self._parse_state(raw_state)
+                    self.last_state = parsed_state
+                    if self.state_callback:
+                        self.state_callback(parsed_state)
+                except Exception:
+                    pass
+
+    def _parse_state(self, raw: Dict) -> FullArmState:
+        joints = []
+        for j in raw.get("joints", []):
+            joints.append(
+                JointState(
+                    can_id=j.get("can_id", 0),
+                    position=j.get("position", 0.0),
+                    velocity=j.get("velocity", 0.0),
+                    torque=j.get("torque", 0.0),
+                    enable=j.get("enable", False),
+                    mode=j.get("mode", 0),
+                )
+            )
+        gripper = None
+        if "gripper" in raw:
+            g = raw["gripper"]
+            gripper = GripperState(
+                position=g.get("position", 0.0),
+                velocity=g.get("velocity", 0.0),
+                torque=g.get("torque", 0.0),
+                enable=g.get("enable", False),
+                mode=g.get("mode", 0),
+            )
+        eef_pose = None
+        if "eef_pose" in raw:
+            p = raw["eef_pose"]
+            eef_pose = Pose(
+                x=p.get("x", 0.0),
+                y=p.get("y", 0.0),
+                z=p.get("z", 0.0),
+                qw=p.get("qw", 1.0),
+                qx=p.get("qx", 0.0),
+                qy=p.get("qy", 0.0),
+                qz=p.get("qz", 0.0),
+            )
+        return FullArmState(joints=joints, gripper=gripper, eef_pose=eef_pose)
+
+    async def send_command(self, cmd: Dict) -> bool:
+        try:
+            payload = json.dumps(cmd).encode()
+            await self.cmd_pub.send_multipart([f"commands_{self.sn}".encode(), payload])
+            return True
+        except Exception:
+            return False
+
+    async def send_raw(self, bytes topic, bytes payload) -> bool:
+        try:
+            await self.cmd_pub.send_multipart([topic, payload])
+            return True
+        except Exception:
+            return False
+
+    def set_state_callback(self, callback: Callable[[FullArmState], None]):
+        self.state_callback = callback
+
+    def is_connected(self) -> bool:
+        return self.cmd_pub is not None and not self.cmd_pub.closed
+
+    async def close(self):
+        self.running = False
+        if self._recv_task is not None:
+            try:
+                await asyncio.wait_for(self._recv_task, timeout=1.0)
+            except asyncio.TimeoutError:
+                self._recv_task.cancel()
+            except Exception:
+                pass
+        try:
+            self.cmd_pub.close()
+            self.state_sub.close()
+            self.ctx.term()
+        except Exception:
+            pass
+
+
+# =============================================================================
+# RobotArm Class - Main User Interface (compiled)
+# =============================================================================
+cdef class RobotArm:
+    cdef public str sn
+    cdef public str ip
+    cdef public int control_port
+    cdef public int zmq_cmd_port
+    cdef public object communicator
+    cdef public object _state_callback
+
+    def __init__(
+        self,
+        sn: Optional[str] = None,
+        ip: Optional[str] = None,
+        int control_port = 8888,
+        int zmq_cmd_port = 6666,
+    ):
+        self.sn = sn
+        self.ip = ip
+        self.control_port = control_port
+        self.zmq_cmd_port = zmq_cmd_port
+        self.communicator = None
+        self._state_callback = None
+
+    async def find_all_devices(self, timeout: float = 1.0) -> List[Dict]:
+        return await discover_arms(timeout)
+
+    async def auto_discover_and_connect(self, timeout: float = 1.0) -> bool:
+        total_steps = 5
+        progress = tqdm(total=total_steps, desc=_("Connecting to ZeroArm"), unit="step")
+        try:
+            progress.set_description(_("Step 1/5: Finding devices"))
+            arms = await discover_arms(timeout)
+            progress.update(1)
+            if not arms:
+                progress.close()
+                print(_("No ZeroArm found on the network"))
+                return False
+
+            progress.set_description(_("Step 2/5: Choosing first arm"))
+            arm_info = arms[0]
+            self.sn = arm_info["sns"][0]
+            self.ip = arm_info["ips"][0]
+            self.control_port = int(arm_info.get("control_port", 8888))
+            self.zmq_cmd_port = int(arm_info.get("zmq_cmd_port", 6666))
+            short_sn = self.sn[:6] + "..." if len(self.sn) > 6 else self.sn
+            progress.update(1)
+
+            progress.set_description(_("Step 3/5: Selecting arm"))
+            self.communicator = ArmCommunicator(
+                self.ip,
+                self.sn,
+                self.control_port,
+                self.zmq_cmd_port,
+            )
+            success = await self.communicator.select_sn()
+            progress.update(1)
+            if not success:
+                progress.close()
+                print(_("Failed to select arm"))
+                return False
+
+            progress.set_description(_("Step 4/5: Waiting for arm ready (1s)"))
+            await asyncio.sleep(1.0)
+            progress.update(1)
+
+            progress.set_description(_("Step 5/5: Final connection"))
+            await self.communicator.connect_zmq()
+            progress.update(1)
+
+            if self._state_callback:
+                self.communicator.set_state_callback(self._state_callback)
+
+            progress.set_description(_("Connected!"))
+            progress.close()
+            print(_("Connected successfully: Arm {}").format(short_sn))
+            return True
+        except Exception:
+            progress.close()
+            print(_("Connection failed"))
+            return False
+
+    async def connect_with_short_sn(self, short_sn: str, timeout: float = 1.0) -> bool:
+        arms = await discover_arms(timeout)
+        if not arms:
+            print(_("No ZeroArm found on the network"))
+            return False
+
+        for arm_info in arms:
+            for full_sn in arm_info["sns"]:
+                if full_sn.startswith(short_sn):
+                    self.sn = full_sn
+                    self.ip = arm_info["ips"][0]
+                    self.control_port = int(arm_info.get("control_port", 8888))
+                    self.zmq_cmd_port = int(arm_info.get("zmq_cmd_port", 6666))
+                    short_display = short_sn + "..." if len(full_sn) > 6 else short_sn
+                    print(_("Found arm: {}").format(short_display))
+                    return await self.connect()
+
+        print(_("No arm found starting with '{}'").format(short_sn))
+        return False
+
+    async def connect(self) -> bool:
+        if not self.sn or not self.ip:
+            print(_("Serial number and IP must be set first"))
+            return False
+
+        self.communicator = ArmCommunicator(
+            self.ip,
+            self.sn,
+            self.control_port,
+            self.zmq_cmd_port,
+        )
+        success = await self.communicator.select_sn()
+        if not success:
+            print(_("Failed to select arm"))
+            return False
+
+        await asyncio.sleep(1.0)
+        await self.communicator.connect_zmq()
+
+        if self._state_callback:
+            self.communicator.set_state_callback(self._state_callback)
+
+        short_sn = self.sn[:6] + "..." if len(self.sn) > 6 else self.sn
+        print(_("Connected to arm: {}").format(short_sn))
+        return True
+
+    def is_connected(self) -> bool:
+        return self.communicator is not None and self.communicator.is_connected()
+
+    @property
+    def current_state(self) -> Optional[FullArmState]:
+        if self.communicator:
+            return self.communicator.last_state
+        return None
+
+    def on_state_update(self, callback: Callable[[FullArmState], None]):
+        self._state_callback = callback
+        if self.communicator:
+            self.communicator.set_state_callback(callback)
+
+    async def send_command(self, cmd: Dict):
+        if not self.communicator:
+            raise ArmConnectionError("Not connected yet")
+        await self.communicator.send_command(cmd)
+
+    async def send_raw_msg(self, raw_payload: str):
+        if not self.communicator:
+            raise ArmConnectionError("Not connected yet")
+        await self.send_command({"type": "raw_msg", "payload": raw_payload})
+
+    async def set_joint(self, int can_id, float target_pos,
+                        float target_vel = 0.0, float target_tau = 0.0,
+                        int mode = 0, bint enable = True, bint set_zero = False,
+                        max_vel: Optional[float] = None, max_acc: Optional[float] = None,
+                        max_jerk: Optional[float] = None):
+        cmd = {
+            "type": "set_joint",
+            "can_id": can_id,
+            "target_pos": target_pos,
+            "target_vel": target_vel,
+            "target_tau": target_tau,
+            "mode": mode,
+            "enable": enable,
+            "set_zero": set_zero,
+        }
+        if max_vel is not None: cmd["max_vel"] = max_vel
+        if max_acc is not None: cmd["max_acc"] = max_acc
+        if max_jerk is not None: cmd["max_jerk"] = max_jerk
+        await self.send_command(cmd)
+
+    async def set_gripper(self, float target_pos,
+                          float target_vel = 0.0, float target_tau = 0.0,
+                          bint set_zero = False):
+        cmd = {
+            "type": "set_gripper",
+            "target_pos": target_pos,
+            "target_vel": target_vel,
+            "target_tau": target_tau,
+            "set_zero": set_zero,
+        }
+        await self.send_command(cmd)
+
+    async def set_tf(self, float x, float y, float z,
+                     float qw, float qx, float qy, float qz,
+                     int plan_mode = 0):
+        cmd = {
+            "type": "set_tf",
+            "x": x, "y": y, "z": z,
+            "qw": qw, "qx": qx, "qy": qy, "qz": qz,
+            "plan_mode": plan_mode,
+        }
+        await self.send_command(cmd)
+
+    async def enable_hold_current(self, max_vel: Optional[float] = None,
+                                  max_acc: Optional[float] = None,
+                                  max_jerk: Optional[float] = None):
+        cmd = {"type": "enable_hold_current"}
+        if max_vel is not None: cmd["max_vel"] = max_vel
+        if max_acc is not None: cmd["max_acc"] = max_acc
+        if max_jerk is not None: cmd["max_jerk"] = max_jerk
+        await self.send_command(cmd)
+
+    async def set_joints_batch(
+        self,
+        joint_targets: List[tuple[int, float]],
+        target_vel: float = 0.0,
+        target_tau: float = 0.0,
+        mode: int = 0,
+        enable: bool = True,
+        set_zero: bool = False,
+        max_vel: int = 10,
+        max_acc: int = 30,
+        max_jerk: int = 50,
+        wait_for_completion: bool = False,
+        timeout: float = 8.0,
+        tolerance: float = 0.015
+    ) -> bool:
+        if not self.communicator:
+            raise ArmConnectionError("Not connected yet")
+        if not joint_targets:
+            raise ValueError("joint_targets list cannot be empty")
+
+        parts = [f"{time.time():.6f}"]
+        for can_id, target_pos in joint_targets:
+            if not isinstance(can_id, int) or not isinstance(target_pos, (int, float)):
+                raise ValueError(f"Invalid joint target: ({can_id}, {target_pos})")
+            part = f"{can_id}:{target_pos:.6f}:{target_vel:.6f}:{target_tau:.6f}:{mode}:{int(enable)}:{int(set_zero)}"
+            if max_vel is not None:
+                part += f":{max_vel:.6f}"
+            if max_acc is not None:
+                part += f":{max_acc:.6f}"
+            if max_jerk is not None:
+                part += f":{max_jerk:.6f}"
+            parts.append(part)
+
+        raw_payload = ";".join(parts)
+        await self.send_raw_msg(raw_payload)
+
+        if not wait_for_completion:
+            return True
+
+        start_time = time.time()
+        while True:
+            state = self.current_state
+            if not state:
+                await asyncio.sleep(0.02)
+                continue
+            all_reached = True
+            for can_id, target_pos in joint_targets:
+                js = next((j for j in state.joints if j.can_id == can_id), None)
+                if not js or abs(js.position - target_pos) > tolerance:
+                    all_reached = False
+                    break
+            if all_reached:
+                print(_("All joints reached targets successfully!"))
+                return True
+            if time.time() - start_time > timeout:
+                print(_("Timeout waiting for joints to reach targets (tolerance: {} rad)").format(tolerance))
+                return False
+            await asyncio.sleep(0.02)
+
+    async def zero_gravity_mode(self):
+        await self.send_command({"type": "zero_gravity_mode"})
+
+    async def back_to_zero(self):
+        await self.send_command({"type": "back_to_zero"})
+
+    async def back_to_initial(self):
+        await self.send_command({"type": "back_to_initial"})
+
+    async def gracefully_shutdown(self, wait_before_shutdown: float = 10.0):
+        await self.back_to_initial()
+        await asyncio.sleep(wait_before_shutdown)
+        if self.communicator:
+            await self.communicator.shutdown_control()
+        print(_("Graceful shutdown completed."))
+
+    async def emergency_shutdown(self):
+        if self.communicator:
+            await self.communicator.shutdown_control()
+        print(_("Emergency shutdown executed."))
+
+    async def close(self):
+        if self.communicator:
+            await self.communicator.close()
+        print(_("Connection closed."))

zeroarm_sdk-0.1.2/zeroArm_sdk/arm.py

@@ -0,0 +1,374 @@
+# zeroArm_sdk/arm.py
+# Copyright (c) 2026 Han / ForceEase Co. All Rights Reserved.
+# Public interface for ZeroArm SDK - only for licensed hardware owners
+
+import gettext
+import os
+from typing import Dict, List, Optional, Callable, Tuple
+from ._core import RobotArm as _RobotArmImpl
+from .arm_types import FullArmState, JointState, GripperState, Pose
+from .exceptions import ArmNotFoundError, ArmConnectionError, ArmCommandError
+
+
+class RobotArm(_RobotArmImpl):
+    """
+    Main class for controlling ZeroArm robotic arm.
+
+    机械臂控制主类。
+
+    Features / 主要功能：
+    - Automatically find and connect to the arm / 自动发现并连接机械臂
+    - Connect using short serial number prefix / 支持使用序列号前缀快速连接
+    - Control all joints, gripper, and end-effector pose / 控制所有关节、夹爪、末端位姿
+    - Switch control modes (zero gravity, etc.) / 切换控制模式（零重力等）
+    - Graceful and emergency shutdown / 优雅关机与紧急停止
+    - Real-time state updates / 实时状态更新
+    """
+
+    def __init__(
+        self,
+        sn: Optional[str] = None,
+        ip: Optional[str] = None,
+        control_port: int = 8888,
+        zmq_cmd_port: int = 6666,
+    ):
+        """
+        Create a new RobotArm instance.
+
+        创建 RobotArm 实例。
+
+        Args / 参数:
+            sn: Full serial number of the arm (optional) / 机械臂完整序列号（可选）
+            ip: IP address of the arm (optional) / 机械臂 IP 地址（可选）
+            control_port: WebSocket control port, default 8888 / 控制端口，默认 8888
+            zmq_cmd_port: ZMQ command port, default 6666 / 指令端口，默认 6666
+
+        Note / 注意:
+        - If both sn and ip are None, use auto_discover_and_connect() to find the arm automatically.
+          如果 sn 和 ip 均未提供，可通过 auto_discover_and_connect() 自动发现机械臂。
+        """
+        super().__init__(sn, ip, control_port, zmq_cmd_port)
+
+    async def find_all_devices(self, timeout: float = 1.0) -> List[Dict]:
+        """
+        Find all available ZeroArm devices on the network.
+
+        在局域网内发现所有可用的 ZeroArm 设备。
+
+        Args / 参数:
+            timeout: Maximum time to wait for discovery (seconds, default 1.0) / 发现最大等待时间（秒，默认 1.0）
+
+        Returns / 返回:
+            List[Dict]: List of device information dictionaries / 设备信息字典列表
+
+        Example / 示例:
+            devices = await arm.find_all_devices(timeout=2.0)
+            print(devices)
+        """
+        return await super().find_all_devices(timeout)
+
+    async def auto_discover_and_connect(self, timeout: float = 1.0) -> bool:
+        """
+        Automatically find the first available arm and connect to it.
+        Shows a progress bar during connection.
+
+        自动发现局域网内第一个可用机械臂并连接。
+        连接过程中显示进度条。
+
+        Args / 参数:
+            timeout: Maximum wait time for discovery (seconds, default 1.0) / 发现最大等待时间（秒，默认 1.0）
+
+        Returns / 返回:
+            bool: True if connected successfully, False otherwise / 连接成功返回 True，否则 False
+
+        Example / 示例:
+            success = await arm.auto_discover_and_connect(timeout=3.0)
+            if success:
+                print(_("Arm is ready!"))  # 支持本地化：已连接机械臂！
+        """
+        return await super().auto_discover_and_connect(timeout)
+
+    async def connect_with_short_sn(self, short_sn: str, timeout: float = 1.0) -> bool:
+        """
+        Connect to an arm using a serial number prefix.
+
+        使用序列号前缀连接机械臂，建议使用前 8 位以避免多臂环境中误匹配。
+
+        Args / 参数:
+            short_sn: Serial number prefix / 序列号前缀（建议至少 8 位）
+            timeout: Maximum wait time for discovery (seconds, default 1.0) / 发现最大等待时间（秒，默认 1.0）
+
+        Returns / 返回:
+            bool: True if connected successfully, False otherwise / 连接成功返回 True，否则 False
+
+        Example / 示例:
+            await arm.connect_with_short_sn("F82FCDC0")
+        """
+        return await super().connect_with_short_sn(short_sn, timeout)
+
+    async def connect(self) -> bool:
+        """
+        Connect to the arm using current serial number and IP.
+
+        使用当前已设置的序列号和 IP 进行连接。
+
+        Returns / 返回:
+            bool: True if successful, False otherwise / 连接成功返回 True，否则 False
+
+        Note / 注意:
+        - Must set sn and ip first (via __init__ or manually).
+          必须先设置 sn 和 ip。
+        """
+        return await super().connect()
+
+    def is_connected(self) -> bool:
+        """
+        Check if the arm is currently connected.
+
+        检查当前是否已连接到机械臂。
+
+        Returns / 返回:
+            bool: True if connected, False otherwise / 已连接返回 True，否则 False
+        """
+        return super().is_connected()
+
+    @property
+    def current_state(self) -> Optional[FullArmState]:
+        """
+        Get the latest received arm state.
+
+        获取机械臂的最新状态（实时更新）。
+
+        Returns / 返回:
+            FullArmState or None: Latest arm state / 最新机械臂状态；若无数据则返回 None
+
+        Example / 示例:
+            state = arm.current_state
+            if state:
+                print(f"Joint 1: {state.joints[0].position:.3f} rad")
+        """
+        return super().current_state
+
+    def on_state_update(self, callback: Callable[[FullArmState], None]):
+        """
+        Set a callback function to be called on every new state update.
+
+        设置状态更新回调函数，每次接收到新状态时调用。
+
+        Args / 参数:
+            callback: Function that receives FullArmState / 接收 FullArmState 的回调函数
+
+        Example / 示例:
+            def handler(state):
+                print(f"End-effector pose: {state.eef_pose}")
+            arm.on_state_update(handler)
+        """
+        super().on_state_update(callback)
+
+    async def set_joint(
+        self,
+        can_id: int,
+        target_pos: float,
+        target_vel: float = 0.0,
+        target_tau: float = 0.0,
+        mode: int = 0,
+        enable: bool = True,
+        set_zero: bool = False,
+        max_vel: Optional[float] = None,
+        max_acc: Optional[float] = None,
+        max_jerk: Optional[float] = None,
+    ):
+        """
+        Move a single joint to target position.
+
+        控制单个关节运动到目标位置。
+
+        Args / 参数:
+            can_id: Joint CAN ID (usually starts from 1) / 关节 CAN ID（通常从 1 开始）
+            target_pos: Target position in radians / 目标位置（弧度）
+            target_vel: Target velocity (rad/s), default 0.0 / 目标速度（弧度/秒，默认 0.0）
+            target_tau: Target torque (Nm), default 0.0 / 目标力矩（Nm，默认 0.0）
+            mode: Control mode (0 = position mode, see arm manual) / 控制模式（0=位置模式，参考臂说明书）
+            enable: Enable the joint, default True / 是否使能关节，默认 True
+            set_zero: Set current position as zero, default False / 是否将当前位置设为零位，默认 False
+            max_vel/max_acc/max_jerk: Optional speed/acceleration/jerk limits / 可选的最大速度/加速度/加加速度限制
+
+        Example / 示例:
+            await arm.set_joint(1, 0.785)  # Move joint 1 to 45° / 将关节1移动到45°
+        """
+        await super().set_joint(
+            can_id,
+            target_pos,
+            target_vel,
+            target_tau,
+            mode,
+            enable,
+            set_zero,
+            max_vel,
+            max_acc,
+            max_jerk,
+        )
+
+    async def set_gripper(
+        self,
+        target_pos: float,
+        target_vel: float = 0.0,
+        target_tau: float = 0.0,
+        set_zero: bool = False,
+    ):
+        """
+        Control gripper opening/closing.
+
+        控制夹爪开合。
+
+        Args / 参数:
+            target_pos: Target gripper position / 目标开合位置
+            target_vel: Gripper velocity, default 0.0 / 夹爪运动速度，默认 0.0
+            target_tau: Gripper torque, default 0.0 / 夹爪力矩，默认 0.0
+            set_zero: Set current position as zero, default False / 是否设为零位，默认 False
+
+        Example / 示例:
+            await arm.set_gripper(0.08)  # Open gripper to 8cm / 将夹爪打开到8cm
+        """
+        await super().set_gripper(target_pos, target_vel, target_tau, set_zero)
+
+    async def set_tf(
+        self,
+        x: float,
+        y: float,
+        z: float,
+        qw: float,
+        qx: float,
+        qy: float,
+        qz: float,
+        plan_mode: int = 0,
+    ):
+        """
+        Set end-effector position and orientation (quaternion).
+
+        设置末端执行器位姿（位置 + 四元数姿态）。
+
+        Args / 参数:
+            x, y, z: Position in meters / 位置（米）
+            qw, qx, qy, qz: Orientation quaternion / 姿态四元数
+            plan_mode: 0 = joint-space planning, 1 = Cartesian planning / 0=关节空间，1=笛卡尔
+
+        Example / 示例:
+            await arm.set_tf(0.5, 0.0, 0.3, 1.0, 0.0, 0.0, 0.0, plan_mode=1)
+        """
+        await super().set_tf(x, y, z, qw, qx, qy, qz, plan_mode)
+
+    async def enable_hold_current(
+        self,
+        max_vel: Optional[float] = None,
+        max_acc: Optional[float] = None,
+        max_jerk: Optional[float] = None,
+    ):
+        """
+        Hold all configured joints at their current feedback positions.
+
+        以当前反馈位置重新保持所有已配置关节。
+        """
+        await super().enable_hold_current(max_vel, max_acc, max_jerk)
+
+    async def set_joints_batch(
+        self,
+        joint_targets: List[Tuple[int, float]],
+        target_vel: float = 0.0,
+        target_tau: float = 0.0,
+        mode: int = 0,
+        enable: bool = True,
+        set_zero: bool = False,
+        max_vel: int = 10,
+        max_acc: int = 30,
+        max_jerk: int = 50,
+        wait_for_completion: bool = False,
+        timeout: float = 8.0,
+        tolerance: float = 0.015,
+    ) -> bool:
+        """
+        Move multiple joints simultaneously (recommended for synchronized motion).
+
+        同时控制多个关节运动（推荐用于同步轨迹规划）。
+
+        Args / 参数:
+            joint_targets: List of (can_id, target_pos) tuples / 关节目标列表：[(can_id, 目标位置), ...]
+            target_vel/target_tau: Reserved parameters (currently not used) / 保留参数（当前未使用）
+            mode/enable/set_zero: Global mode, enable, zero setting / 全局模式、使能、零位设置
+            max_vel/max_acc/max_jerk: Global limits (deg/s, deg/s², deg/s³) / 全局最大速度/加速度/加加速度限制
+            wait_for_completion: Wait until all joints reach targets, default False / 是否等待到达目标，默认 False
+            timeout: Timeout in seconds (when waiting) / 等待超时时间（秒）
+            tolerance: Position tolerance in radians, default 0.015 (~0.86°) / 位置容差（弧度，默认 0.015）
+
+        Returns / 返回:
+            bool: Command sent successfully (or reached targets if waiting) / 命令发送成功（或等待成功）
+
+        Example / 示例:
+            await arm.set_joints_batch([(1, 0.5), (2, -0.3), (5, 1.57)])
+        """
+        return await super().set_joints_batch(
+            joint_targets,
+            target_vel,
+            target_tau,
+            mode,
+            enable,
+            set_zero,
+            max_vel,
+            max_acc,
+            max_jerk,
+            wait_for_completion,
+            timeout,
+            tolerance,
+        )
+
+    async def zero_gravity_mode(self):
+        """
+        Switch to zero gravity mode (free manual movement).
+
+        切换到零重力模式（可手动自由拖动机械臂）。
+        """
+        await super().zero_gravity_mode()
+
+    async def back_to_zero(self):
+        """
+        Move all joints back to zero position.
+
+        将所有关节移动回零位。
+        """
+        await super().back_to_zero()
+
+    async def back_to_initial(self):
+        """
+        Move all joints to factory initial positions.
+
+        将所有关节移动到出厂初始位置。
+        """
+        await super().back_to_initial()
+
+    async def gracefully_shutdown(self, wait_before_shutdown: float = 10.0):
+        """
+        Gracefully shutdown: move to initial pose → wait → power off.
+
+        优雅关机：先移动到初始位置 → 等待 → 安全断电。
+
+        Args / 参数:
+            wait_before_shutdown: Wait time after movement (seconds, default 10.0) / 运动完成后等待时间（秒，默认 10.0）
+        """
+        await super().gracefully_shutdown(wait_before_shutdown)
+
+    async def emergency_shutdown(self):
+        """
+        Immediate emergency stop and shutdown.
+
+        紧急停止并关机（立即停止所有运动并断电）。
+        Use only in emergency situations / 仅在紧急情况下使用。
+        """
+        await super().emergency_shutdown()
+
+    async def close(self):
+        """
+        Close connection and release resources.
+
+        关闭连接并释放所有资源。
+        """
+        await super().close()

zeroarm_sdk-0.1.2/zeroArm_sdk/arm_types.py

@@ -0,0 +1,40 @@
+# zeroArm_sdk/arm_types.py
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class JointState:
+    can_id: int
+    position: float      # radians
+    velocity: float
+    torque: float
+    enable: bool
+    mode: int
+
+
+@dataclass
+class GripperState:
+    position: float
+    velocity: float
+    torque: float
+    enable: bool
+    mode: int
+
+
+@dataclass
+class Pose:
+    x: float
+    y: float
+    z: float
+    qw: float
+    qx: float
+    qy: float
+    qz: float
+
+
+@dataclass
+class FullArmState:
+    joints: List[JointState]
+    gripper: Optional[GripperState] = None
+    eef_pose: Optional[Pose] = None

zeroarm_sdk-0.1.2/zeroArm_sdk/exceptions.py

@@ -0,0 +1,15 @@
+# zeroArm_sdk/exceptions.py
+
+class ArmNotFoundError(Exception):
+    """No ZeroArm device found on the network."""
+    pass
+
+
+class ArmConnectionError(Exception):
+    """Failed to connect, select SN, or establish communication."""
+    pass
+
+
+class ArmCommandError(Exception):
+    """Command execution failed or invalid response."""
+    pass

zeroarm_sdk-0.1.2/zeroArm_sdk.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: zeroArm_sdk
+Version: 0.1.2
+Summary: Official SDK for ZeroArm robotic arm (proprietary)
+Home-page: https://github.com/HANCKH/zeroArm_python_sdk
+Author: ForceEase Co.
+Author-email: "ForceEase Co." <support@forceease.tech>
+License: MIT
+Project-URL: Source, https://github.com/HANCKH/zeroArm_python_sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Cython
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyzmq>=25.0
+Requires-Dist: websockets
+Requires-Dist: zeroconf
+Requires-Dist: tqdm
+Dynamic: author
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+
+# ZeroArm Python SDK
+
+Official Python SDK for ForceEase ZeroArm robotic arms.
+
+## Connection Notes
+
+- Use `RobotArm().auto_discover_and_connect()` for the default LAN workflow.
+- Use `connect_with_short_sn()` with at least the first 8 serial-number characters in multi-arm environments.
+- mDNS discovery only accepts connectable IPv4 addresses and ignores loopback or unspecified addresses such as `127.0.0.1` and `0.0.0.0`.
+- The controller advertises WebSocket control port `8888` and bridge port `8889`; SDK mode uses the fixed ZMQ command/state ports `6666/6667`.
+
+## Current Protocol Coverage
+
+- `set_tf(..., plan_mode=0)` uses joint-space planning; `plan_mode=1` uses Cartesian planning.
+- `enable_hold_current()` asks the controller to hold all configured joints at their current feedback positions.
+- `set_joints_batch()` sends a single `raw_msg` command through the normal `commands_<serial>` topic.
+
+## Build Notes
+
+- `pyproject.toml` declares Cython as a build-system dependency for isolated builds.
+- For direct `setup.py` builds, install `requirements-build.txt` first.
+- `setuptools` is capped below 80 to stay compatible with ROS `colcon-core` in the shared development environment.
+
+## Release
+
+- Publish Python SDK releases through `.github/workflows/build-wheels.yml`.
+- A GitHub Release with action `published` builds the sdist plus Linux, Windows, and macOS wheels, then uploads all distributions to PyPI in one publish job.
+- The workflow expects `PYPI_API_TOKEN` to be configured as a GitHub Actions secret.
+
+## Version
+
+Current SDK source version: `0.1.2`.

zeroarm_sdk-0.1.2/zeroArm_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+zeroArm_sdk/__init__.py
+zeroArm_sdk/_core.pyx
+zeroArm_sdk/arm.py
+zeroArm_sdk/arm_types.py
+zeroArm_sdk/exceptions.py
+zeroArm_sdk.egg-info/PKG-INFO
+zeroArm_sdk.egg-info/SOURCES.txt
+zeroArm_sdk.egg-info/dependency_links.txt
+zeroArm_sdk.egg-info/requires.txt
+zeroArm_sdk.egg-info/top_level.txt
+zeroArm_sdk/locale/zh_CN/LC_MESSAGES/zeroArm_sdk.mo

zeroarm_sdk-0.1.2/zeroArm_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zeroarm_sdk-0.1.2/zeroArm_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pyzmq>=25.0
+websockets
+zeroconf
+tqdm

zeroarm_sdk-0.1.2/zeroArm_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+zeroArm_sdk