hex-zmq-servers 1.0.0

HEXFELLOW ZMQ Servers

HEXFELLOW ZMQ SERVERS

      

---

📖 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)

  pip install hex_zmq_servers[all]
  

• Core install: only the core package (no optional devices)

  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 to manage the Python environment. Please install it first.

1. Clone and install in editable mode. The venv.sh script expects uv.

   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:

   source .venv/bin/activate
   

---

📚 Tutorial

See Tutorial for details of all tutorials.

📑 API

See API for details of all APIs.

💡 Example

See Example for details of all examples.

---

🏷️ Citation

If you want to cite this project in your work, you can use the following BibTeX entry:

@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.

---

🌟 Star History