hex-zmq-servers 0.3.16__tar.gz → 1.0.0__tar.gz

hex_zmq_servers-1.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: hex_zmq_servers
+Version: 1.0.0
+Summary: HEXFELLOW ZMQ Servers
+Author-email: Dong Zhaorui <joray.dong@hexfellow.com>
+Maintainer-email: jecjune <zejun.chen@hexfellow.com>, Dong Zhaorui <joray.dong@hexfellow.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/hexfellow/hex_zmq_servers
+Project-URL: Repository, https://github.com/hexfellow/hex_zmq_servers.git
+Project-URL: Bug Tracker, https://github.com/hexfellow/hex_zmq_servers/issues
+Project-URL: Documentation, https://github.com/hexfellow/hex_zmq_servers/wiki
+Keywords: hex_zmq_servers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyzmq>=27.0.1
+Requires-Dist: hex_device<1.4.0,>=1.3.14
+Requires-Dist: hex_robo_utils<0.3.0,>=0.2.0
+Requires-Dist: opencv-python>=4.2
+Provides-Extra: berxel
+Requires-Dist: berxel_py_wrapper>=2.0.182; extra == "berxel"
+Provides-Extra: realsense
+Requires-Dist: pyrealsense2>=2.56.5.9235; extra == "realsense"
+Provides-Extra: dynamixel
+Requires-Dist: dynamixel-sdk==3.8.4; extra == "dynamixel"
+Provides-Extra: mujoco
+Requires-Dist: mujoco>=3.3.3; extra == "mujoco"
+Provides-Extra: all
+Requires-Dist: berxel_py_wrapper>=2.0.182; extra == "all"
+Requires-Dist: pyrealsense2>=2.56.5.9235; extra == "all"
+Requires-Dist: dynamixel-sdk==3.8.4; extra == "all"
+Requires-Dist: mujoco>=3.3.3; extra == "all"
+Dynamic: license-file
+
+<h1 align="center">HEXFELLOW ZMQ SERVERS</h1>
+
+<p align="center">
+    <a href="https://github.com/hexfellow/hex_zmq_servers/stargazers">
+        <img src="https://img.shields.io/github/stars/hexfellow/hex_zmq_servers?style=flat-square&logo=github" />
+    </a>
+    <a href="https://github.com/hexfellow/hex_zmq_servers/forks">
+        <img src="https://img.shields.io/github/forks/hexfellow/hex_zmq_servers?style=flat-square&logo=github" />
+    </a>
+    <a href="https://doi.org/10.5281/zenodo.18309954">
+        <img src="https://zenodo.org/badge/1088506315.svg" alt="DOI">
+    </a>
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+    <a href="https://github.com/hexfellow/hex_zmq_servers/issues">
+        <img src="https://img.shields.io/github/issues/hexfellow/hex_zmq_servers?style=flat-square&logo=github" />
+    </a>
+</p>
+
+---
+
+# 📖 Overview
+
+## What is `hex_zmq_servers`
+
+`hex_zmq_servers` provides a client–server layer on top of ZeroMQ to control and stream data from HEXFELLOW hardware (robots, RGB/RGB-D cameras) and MuJoCo-based simulators. Servers run device logic and command loops; clients send requests (e.g. `get_rgb`, `get_state`, `set_target`) and receive headers plus optional binary buffers (e.g. images, joint state).
+
+## What problem it solves
+
+- **Decoupled control**: Run device drivers and control loops in separate processes; clients connect over TCP.
+- **Unified transport**: All devices use the same ZMQ request/response pattern (JSON header + NumPy buffer).
+- **Multi-node management**: `HexLaunch` and `HexNodeConfig` start and monitor multiple server/client nodes from one process.
+
+## Target users
+
+- Engineers integrating HEXFELLOW robots into their systems.
+- Researchers running experiments with HEXFELLOW robots.
+
+---
+
+# 📦 Installation
+
+## Requirements
+
+- **Python**
+- **OS**: `Linux` / `macOS`
+- **Core dependencies**:
+  - `pyzmq`
+  - `hex_device`
+  - `hex_robo_utils`
+  - `opencv-python`
+
+Optional device support (install via extras):
+
+| Extra       | Purpose                                         |
+| ----------- | ----------------------------------------------- |
+| `berxel`    | Berxel RGB-D: `berxel_py_wrapper`               |
+| `realsense` | RealSense RGB-D: `pyrealsense2`                 |
+| `dynamixel` | Dynamixel: `dynamixel-sdk`                      |
+| `mujoco`    | MuJoCo sims: `mujoco`                           |
+| `all`       | `berxel` + `dynamixel` + `realsense` + `mujoco` |
+
+## Install from PyPI
+
+For those who don't need examples, you can install the package from PyPI.
+
+- **Full install**: includes all optional devices (Berxel, RealSense, Dynamixel, MuJoCo)
+
+    ```bash
+    pip install hex_zmq_servers[all]
+    ```
+
+- **Core install**: only the core package (no optional devices)
+
+    ```bash
+    pip install hex_zmq_servers
+    ```
+
+## Install from Source
+
+For those who need examples, you can install the package from source code with examples.
+
+**Noet**: We use [**uv**](https://github.com/astral-sh/uv) to manage the Python environment. Please install it first.
+
+1. Clone and install in editable mode. The `venv.sh` script expects [uv](https://github.com/astral-sh/uv).
+
+    ```bash
+    git clone https://github.com/hexfellow/hex_zmq_servers.git
+    cd hex_zmq_servers
+    ./venv.sh
+    ```
+
+   - `./venv.sh` — creates `.venv`, installs `hex_zmq_servers` with `[all]` and `examples/adv/requirements.txt` (e.g. `pygame` for some examples).
+   - `./venv.sh --min` — installs the core package only (no optional device extras). Some examples will not run.
+   - `./venv.sh --pkg-only` — installs the package only, skips example-related dependencies.
+
+2. Activate before running examples:
+
+    ```bash
+    source .venv/bin/activate
+    ```
+
+---
+
+# 📚 Tutorial
+
+See [**Tutorial**](docs/tutorial.md) for details of all tutorials.
+
+# 📑 API
+
+See [**API**](docs/api.md) for details of all APIs.
+
+# 💡 Example
+
+See [**Example**](docs/example.md) for details of all examples.
+
+---
+
+# 🏷️ Citation
+
+If you want to cite this project in your work, you can use the following BibTeX entry:
+
+```bibtex
+@software{hex_zmq_servers,
+  author    = {Dong, Zhaorui},
+  title     = {Hex ZMQ Servers: A ZeroMQ-Based Embodied AI Communication Framework},
+  year      = {2025},
+  publisher = {Zenodo},
+  version   = {v1.0.0},
+  doi       = {10.5281/zenodo.18309960},
+  url       = {https://doi.org/10.5281/zenodo.18309960}
+}
+```
+
+---
+
+# 📄 License
+
+Apache License 2.0. See [LICENSE](LICENSE).
+
+---
+
+# 🌟 Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=hexfellow/hex_zmq_servers&type=Date)](https://star-history.com/#hexfellow/hex_zmq_servers&Date)
+

hex_zmq_servers-1.0.0/README.md

@@ -0,0 +1,145 @@
+<h1 align="center">HEXFELLOW ZMQ SERVERS</h1>
+
+<p align="center">
+    <a href="https://github.com/hexfellow/hex_zmq_servers/stargazers">
+        <img src="https://img.shields.io/github/stars/hexfellow/hex_zmq_servers?style=flat-square&logo=github" />
+    </a>
+    <a href="https://github.com/hexfellow/hex_zmq_servers/forks">
+        <img src="https://img.shields.io/github/forks/hexfellow/hex_zmq_servers?style=flat-square&logo=github" />
+    </a>
+    <a href="https://doi.org/10.5281/zenodo.18309954">
+        <img src="https://zenodo.org/badge/1088506315.svg" alt="DOI">
+    </a>
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+    <a href="https://github.com/hexfellow/hex_zmq_servers/issues">
+        <img src="https://img.shields.io/github/issues/hexfellow/hex_zmq_servers?style=flat-square&logo=github" />
+    </a>
+</p>
+
+---
+
+# 📖 Overview
+
+## What is `hex_zmq_servers`
+
+`hex_zmq_servers` provides a client–server layer on top of ZeroMQ to control and stream data from HEXFELLOW hardware (robots, RGB/RGB-D cameras) and MuJoCo-based simulators. Servers run device logic and command loops; clients send requests (e.g. `get_rgb`, `get_state`, `set_target`) and receive headers plus optional binary buffers (e.g. images, joint state).
+
+## What problem it solves
+
+- **Decoupled control**: Run device drivers and control loops in separate processes; clients connect over TCP.
+- **Unified transport**: All devices use the same ZMQ request/response pattern (JSON header + NumPy buffer).
+- **Multi-node management**: `HexLaunch` and `HexNodeConfig` start and monitor multiple server/client nodes from one process.
+
+## Target users
+
+- Engineers integrating HEXFELLOW robots into their systems.
+- Researchers running experiments with HEXFELLOW robots.
+
+---
+
+# 📦 Installation
+
+## Requirements
+
+- **Python**
+- **OS**: `Linux` / `macOS`
+- **Core dependencies**:
+  - `pyzmq`
+  - `hex_device`
+  - `hex_robo_utils`
+  - `opencv-python`
+
+Optional device support (install via extras):
+
+| Extra       | Purpose                                         |
+| ----------- | ----------------------------------------------- |
+| `berxel`    | Berxel RGB-D: `berxel_py_wrapper`               |
+| `realsense` | RealSense RGB-D: `pyrealsense2`                 |
+| `dynamixel` | Dynamixel: `dynamixel-sdk`                      |
+| `mujoco`    | MuJoCo sims: `mujoco`                           |
+| `all`       | `berxel` + `dynamixel` + `realsense` + `mujoco` |
+
+## Install from PyPI
+
+For those who don't need examples, you can install the package from PyPI.
+
+- **Full install**: includes all optional devices (Berxel, RealSense, Dynamixel, MuJoCo)
+
+    ```bash
+    pip install hex_zmq_servers[all]
+    ```
+
+- **Core install**: only the core package (no optional devices)
+
+    ```bash
+    pip install hex_zmq_servers
+    ```
+
+## Install from Source
+
+For those who need examples, you can install the package from source code with examples.
+
+**Noet**: We use [**uv**](https://github.com/astral-sh/uv) to manage the Python environment. Please install it first.
+
+1. Clone and install in editable mode. The `venv.sh` script expects [uv](https://github.com/astral-sh/uv).
+
+    ```bash
+    git clone https://github.com/hexfellow/hex_zmq_servers.git
+    cd hex_zmq_servers
+    ./venv.sh
+    ```
+
+   - `./venv.sh` — creates `.venv`, installs `hex_zmq_servers` with `[all]` and `examples/adv/requirements.txt` (e.g. `pygame` for some examples).
+   - `./venv.sh --min` — installs the core package only (no optional device extras). Some examples will not run.
+   - `./venv.sh --pkg-only` — installs the package only, skips example-related dependencies.
+
+2. Activate before running examples:
+
+    ```bash
+    source .venv/bin/activate
+    ```
+
+---
+
+# 📚 Tutorial
+
+See [**Tutorial**](docs/tutorial.md) for details of all tutorials.
+
+# 📑 API
+
+See [**API**](docs/api.md) for details of all APIs.
+
+# 💡 Example
+
+See [**Example**](docs/example.md) for details of all examples.
+
+---
+
+# 🏷️ Citation
+
+If you want to cite this project in your work, you can use the following BibTeX entry:
+
+```bibtex
+@software{hex_zmq_servers,
+  author    = {Dong, Zhaorui},
+  title     = {Hex ZMQ Servers: A ZeroMQ-Based Embodied AI Communication Framework},
+  year      = {2025},
+  publisher = {Zenodo},
+  version   = {v1.0.0},
+  doi       = {10.5281/zenodo.18309960},
+  url       = {https://doi.org/10.5281/zenodo.18309960}
+}
+```
+
+---
+
+# 📄 License
+
+Apache License 2.0. See [LICENSE](LICENSE).
+
+---
+
+# 🌟 Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=hexfellow/hex_zmq_servers&type=Date)](https://star-history.com/#hexfellow/hex_zmq_servers&Date)
+

{hex_zmq_servers-0.3.16 → hex_zmq_servers-1.0.0}/hex_zmq_servers/__init__.py

@@ -15,7 +15,6 @@ from .zmq_base import HexZMQDummyClient, HexZMQDummyServer
 
 from .robot import HexRobotBase, HexRobotClientBase, HexRobotServerBase
 from .robot import HexRobotDummy, HexRobotDummyClient, HexRobotDummyServer
-from .robot import HexRobotGello, HexRobotGelloClient, HexRobotGelloServer
 from .robot import HexRobotHexarm, HexRobotHexarmClient, HexRobotHexarmServer, HEXARM_URDF_PATH_DICT
 
 from .cam import HexCamBase, HexCamClientBase, HexCamServerBase
@@ -28,7 +27,6 @@ file_dir = os.path.dirname(os.path.abspath(__file__))
 HEX_ZMQ_SERVERS_PATH_DICT = {
     "zmq_dummy": f"{file_dir}/zmq_base.py",
     "robot_dummy": f"{file_dir}/robot/dummy/robot_dummy_srv.py",
-    "robot_gello": f"{file_dir}/robot/gello/robot_gello_srv.py",
     "robot_hexarm": f"{file_dir}/robot/hexarm/robot_hexarm_srv.py",
     "cam_dummy": f"{file_dir}/cam/dummy/cam_dummy_srv.py",
     "cam_rgb": f"{file_dir}/cam/rgb/cam_rgb_srv.py",
@@ -36,7 +34,6 @@ HEX_ZMQ_SERVERS_PATH_DICT = {
 HEX_ZMQ_CONFIGS_PATH_DICT = {
     "zmq_dummy": f"{file_dir}/config/zmq_dummy.json",
     "robot_dummy": f"{file_dir}/config/robot_dummy.json",
-    "robot_gello": f"{file_dir}/config/robot_gello.json",
     "robot_hexarm": f"{file_dir}/config/robot_hexarm.json",
     "cam_dummy": f"{file_dir}/config/cam_dummy.json",
     "cam_rgb": f"{file_dir}/config/cam_rgb.json",
@@ -80,9 +77,6 @@ __all__ = [
     "HexRobotDummy",
     "HexRobotDummyClient",
     "HexRobotDummyServer",
-    "HexRobotGello",
-    "HexRobotGelloClient",
-    "HexRobotGelloServer",
     "HexRobotHexarm",
     "HexRobotHexarmClient",
     "HexRobotHexarmServer",
@@ -104,6 +98,7 @@ from importlib.util import find_spec
 
 _HAS_BERXEL = find_spec("berxel_py_wrapper") is not None
 _HAS_REALSENSE = find_spec("pyrealsense2") is not None
+_HAS_DYNAMIXEL = find_spec("dynamixel-sdk") is not None
 _HAS_MUJOCO = find_spec("mujoco") is not None
 
 # Optional: berxel
@@ -140,6 +135,23 @@ if _HAS_REALSENSE:
         "HexCamRealsenseServer",
     ])
 
+# Optional: dynamixel
+if _HAS_DYNAMIXEL:
+    from .robot import HexRobotGello, HexRobotGelloClient, HexRobotGelloServer
+    HEX_ZMQ_SERVERS_PATH_DICT.update({
+        "robot_gello":
+        f"{file_dir}/robot/gello/robot_gello_srv.py",
+    })
+    HEX_ZMQ_CONFIGS_PATH_DICT.update({
+        "robot_gello":
+        f"{file_dir}/config/robot_gello.json",
+    })
+    __all__.extend([
+        "HexRobotGello",
+        "HexRobotGelloClient",
+        "HexRobotGelloServer",
+    ])
+
 # Optional: mujoco
 if _HAS_MUJOCO:
     from .mujoco import HexMujocoBase, HexMujocoClientBase, HexMujocoServerBase

{hex_zmq_servers-0.3.16 → hex_zmq_servers-1.0.0}/hex_zmq_servers/cam/berxel/cam_berxel.py

@@ -47,8 +47,8 @@ class HexCamBerxel(HexCamBase):
 
         # variables
         # berxel variables
-        self.__context = None
-        self.__device = None
+        self.__context: BerxelHawkContext | None = None
+        self.__device: BerxelHawkDevice | None = None
         # camera variables
         self.__intri = np.zeros(4)
 
@@ -214,7 +214,15 @@ class HexCamBerxel(HexCamBase):
         return True
 
     def __start_stream(self):
-        self.__device.setColorExposureGain(self.__exposure, self.__gain)
+        if self.__serial_number.startswith('P008'):
+            self.__device.setSonixAEStatus(False)
+            self.__device.setSonixExposureTime(int(self.__exposure // 100))
+        else:
+            self.__device.setColorExposureGain(self.__exposure, self.__gain)
+        self.__device.setDepthElectricCurrent(700)
+        self.__device.setDepthAE(False)
+        self.__device.setDepthExposure(43)
+        self.__device.setDepthGain(1)
         self.__device.setRegistrationEnable(True)
         self.__device.setFrameSync(True)
         while self.__device.setSystemClock() != 0:

{hex_zmq_servers-0.3.16 → hex_zmq_servers-1.0.0}/hex_zmq_servers/config/robot_hexarm.json

@@ -13,7 +13,6 @@
         "device_port": 8439,
         "control_hz": 1000,
         "arm_type": "archer_l6y",
-        "use_gripper": true,
         "mit_kp": [
             200.0,
             200.0,
@@ -21,7 +20,13 @@
             75.0,
             15.0,
             15.0,
-            20.0
+            20.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0
         ],
         "mit_kd": [
             12.5,
@@ -30,7 +35,13 @@
             6.0,
             0.31,
             0.31,
-            1.0
+            1.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            0.0
         ],
         "sens_ts": true
     }

{hex_zmq_servers-0.3.16 → hex_zmq_servers-1.0.0}/hex_zmq_servers/mujoco/archer_y6/mujoco_archer_y6.py

@@ -76,21 +76,36 @@ class HexMujocoArcherY6(HexMujocoBase):
         mujoco.mj_resetData(self.__model, self.__data)
 
         # state init
-        self.__state_robot_idx = [0, 1, 2, 3, 4, 5, 6]
-        self.__state_obj_idx = [12, 13, 14, 15, 16, 17, 18]
-        self.__ctrl_robot_idx = [0, 1, 2, 3, 4, 5, 6]
-        self.__ctrl_obj_idx = [0, 1, 2, 3, 4, 5, 6]
-        self._limits = np.stack(
-            [self.__model.jnt_range[self.__state_robot_idx, :]],
-            axis=0,
-        )
+        self.__state_idx = {
+            "robot_arm": ([0, 1, 2, 3, 4, 5]),
+            "robot_gripper": [6],
+            "obj": [12, 13, 14, 15, 16, 17, 18],
+        }
+        self.__ctrl_idx = {
+            "robot_arm": [0, 1, 2, 3, 4, 5],
+            "robot_gripper": [6],
+        }
+        self.__limit_idx = {
+            "robot_arm":
+            np.arange(len(self.__state_idx["robot_arm"])).tolist(),
+            "robot_gripper":
+            (np.arange(len(self.__state_idx["robot_gripper"])) +
+             len(self.__state_idx["robot_arm"])).tolist(),
+        }
+        print(f"self.__limit_idx: {self.__limit_idx}")
+        self._limits = self.__model.jnt_range[np.concatenate(
+            [self.__state_idx["robot_arm"], self.
+             __state_idx["robot_gripper"]]), :].copy().reshape(-1, 1, 2)
         if not self.__tau_ctrl:
             self.__mit_kp = np.ascontiguousarray(np.asarray(self.__mit_kp))
             self.__mit_kd = np.ascontiguousarray(np.asarray(self.__mit_kd))
             self.__mit_ctrl = CtrlUtil()
         self.__gripper_ratio = 1.33 / 1.52
         self._limits[0, -1] *= self.__gripper_ratio
-        self._dofs = np.array([len(self.__state_robot_idx)])
+        self._dofs = np.array([
+            len(self.__state_idx["robot_arm"]),
+            len(self.__state_idx["robot_gripper"])
+        ])
         keyframe_id = mujoco.mj_name2id(
             self.__model,
             mujoco.mjtObj.mjOBJ_KEY,
@@ -242,16 +257,25 @@ class HexMujocoArcherY6(HexMujocoBase):
         pos = copy.deepcopy(self.__data.qpos)
         vel = copy.deepcopy(self.__data.qvel)
         eff = copy.deepcopy(self.__data.qfrc_actuator)
-        pos[self.__state_robot_idx[-1]] = pos[
-            self.__state_robot_idx[-1]] * self.__gripper_ratio
+        pos[self.__state_idx["robot_gripper"]] = pos[
+            self.__state_idx["robot_gripper"]] * self.__gripper_ratio
         return self.__mujoco_ts() if self.__sens_ts else hex_zmq_ts_now(
         ), np.array([
-            pos[self.__state_robot_idx],
-            vel[self.__state_robot_idx],
-            eff[self.__state_robot_idx],
-        ]).T, self.__data.qpos[self.__state_obj_idx].copy()
+            pos[self.__state_idx["robot_arm"] +
+                self.__state_idx["robot_gripper"]],
+            vel[self.__state_idx["robot_arm"] +
+                self.__state_idx["robot_gripper"]],
+            eff[self.__state_idx["robot_arm"] +
+                self.__state_idx["robot_gripper"]],
+        ]).T, self.__data.qpos[self.__state_idx["obj"]].copy()
 
     def __set_cmds(self, cmds: np.ndarray):
+        state_idx = self.__state_idx["robot_arm"] + self.__state_idx[
+            "robot_gripper"]
+        ctrl_idx = self.__ctrl_idx["robot_arm"] + self.__ctrl_idx[
+            "robot_gripper"]
+        limit_idx = self.__limit_idx["robot_arm"] + self.__limit_idx[
+            "robot_gripper"]
         tau_cmds = None
         if not self.__tau_ctrl:
             cmd_pos = None
@@ -278,8 +302,8 @@ class HexMujocoArcherY6(HexMujocoBase):
                 raise ValueError(f"The shape of cmds is invalid: {cmds.shape}")
             tar_pos = self._apply_pos_limits(
                 cmd_pos,
-                self._limits[0, :, 0],
-                self._limits[0, :, 1],
+                self._limits[limit_idx, 0, 0],
+                self._limits[limit_idx, 0, 1],
             )
             tar_pos[-1] /= self.__gripper_ratio
             tau_cmds = self.__mit_ctrl(
@@ -287,13 +311,13 @@ class HexMujocoArcherY6(HexMujocoBase):
                 cmd_kd,
                 tar_pos,
                 tar_vel,
-                self.__data.qpos[self.__state_robot_idx],
-                self.__data.qvel[self.__state_robot_idx],
+                self.__data.qpos[state_idx],
+                self.__data.qvel[state_idx],
                 cmd_tor,
             )
         else:
             tau_cmds = cmds.copy()
-        self.__data.ctrl[self.__ctrl_robot_idx] = tau_cmds
+        self.__data.ctrl[ctrl_idx] = tau_cmds
 
     def __get_rgb(self):
         self.__rgb_cam.update_scene(self.__data, "end_camera")