Metadata-Version: 2.4
Name: hex_util_msg
Version: 0.1.0a2
Summary: HEXFELLOW Util Message
Author-email: Dong Zhaorui <dzr159@gmail.com>
Maintainer-email: jecjune <zejun.chen@hexfellow.com>, Dong Zhaorui <dzr159@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/hexfellow/hex_util_msg
Project-URL: Repository, https://github.com/hexfellow/hex_util_msg.git
Project-URL: Bug Tracker, https://github.com/hexfellow/hex_util_msg/issues
Project-URL: Documentation, https://github.com/hexfellow/hex_util_msg/wiki
Keywords: hex,util,message
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.8
Classifier: Programming Language :: Python :: 3.9
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.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flatbuffers>=25.0.0
Requires-Dist: numpy>=1.17.4
Dynamic: license-file

<h1 align="center">HEXFELLOW UTILITY MESSAGES</h1>

<p align="center">
    <a href="https://github.com/hexfellow/hex_util_msg/stargazers">
        <img src="https://img.shields.io/github/stars/hexfellow/hex_util_msg?style=flat-square&logo=github" />
    </a>
    <a href="https://github.com/hexfellow/hex_util_msg/forks">
        <img src="https://img.shields.io/github/forks/hexfellow/hex_util_msg?style=flat-square&logo=github" />
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    <a href="https://github.com/hexfellow/hex_util_msg/issues">
        <img src="https://img.shields.io/github/issues/hexfellow/hex_util_msg?style=flat-square&logo=github" />
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    <img src="https://img.shields.io/badge/python-≥3.8-blue?style=flat-square&logo=python" />
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    <img src="https://img.shields.io/badge/platform-Linux-orange?style=flat-square" />
</p>

---

# 📖 Overview

## What is `hex_util_msg`

`hex_util_msg` is a Python message library that provides [FlatBuffers](https://flatbuffers.dev/) message definitions and high-level dataclass-based helpers for robotics and teleoperation. It is part of the HEXFELLOW ecosystem.

The library consists of three layers:

| Layer | Subpackage | Purpose |
|-------|-----------|---------|
| **Dataclass** | `hex_util_msg.dataclass` | Type-safe Python `@dataclass` objects for all 28 message types (base geometry, robot arm/chassis/grip/lift/manip, teleoperation handle) |
| **Converters** | `hex_util_msg.trans` | Bidirectional `dc2fbs` / `fbs2dc` functions plus the `HexMsgTrans` high-level envelope-based dispatcher |
| **FlatBuffers** | `hex_util_msg.fbs` | Auto-generated FlatBuffers Python bindings for 4 namespaces (`msg_base`, `msg_robo`, `msg_teleop`, `msg_envelope`) |

## Message Categories

| Category | Robot Subsystem | Message Pairs |
|----------|----------------|---------------|
| **Arm** | Robotic arm (7-DOF) | `Ctrl` / `State` (each with `Stamped` variant) |
| **Chassis** | Mobile base | `Ctrl` / `State` (each with `Stamped` variant) |
| **Grip** | Gripper/end-effector | `Ctrl` / `State` (each with `Stamped` variant) |
| **Lift** | Vertical lift | `Ctrl` / `State` (each with `Stamped` variant) |
| **Manip** | Composite arm+grip | `Ctrl` / `State` (each with `Stamped` variant) |
| **Teleop** | Teleoperation handle | `HandleCtrl` / `HandleState` (each with `Stamped` variant) |
| **Base** | Geometry & time | `Vector3`, `Quaternion`, `Pose`, `Twist`, `Time`, `Header`, `Odometry`, `JntState`, `JntFull` |

## What problem it solves

- **Zero-copy deserialization**: FlatBuffers enables direct memory access on the receiving end without decode overhead.
- **Type-safe dataclass API**: Work with standard Python dataclasses and numpy arrays — no manual FlatBuffers table construction.
- **Envelope dispatch**: `HexMsgTrans.dc2fbs()` and `.fbs2dc()` wrap all messages in a self-describing envelope so the receiver auto-detects the message type.
- **NumPy integration**: Joint fields are `np.float64` / `np.uint8` arrays, natural for scientific and robotics workflows.

## Target users

- Robotics engineers building control systems with structured inter-process communication.
- Developers producing or consuming FlatBuffers-encoded data in the HEXFELLOW ecosystem.
- Anyone needing a standardised, typed message format with zero-copy deserialization.

## Project structure

```
hex_util_msg/
├── hex_util_msg/                # Python package
│   ├── __init__.py
│   ├── dataclass/               # Python dataclass definitions
│   │   ├── __init__.py
│   │   ├── dataclass_base.py    # Base geometry/time/joint types
│   │   ├── dataclass_robo.py    # Robot arm/chassis/grip/lift/manip types
│   │   └── dataclass_teleop.py  # Teleoperation handle types
│   ├── fbs/                     # FlatBuffers-generated Python code
│   │   ├── msg_base/
│   │   ├── msg_envelope/
│   │   ├── msg_robo/
│   │   └── msg_teleop/
│   └── trans/                   # Dataclass <-> FlatBuffers converters
│       ├── __init__.py
│       ├── hex_msg_trans.py     # HexMsgTrans class + dispatch tables
│       ├── trans_base.py
│       ├── trans_robo.py
│       └── trans_teleop.py
├── msgs/                        # FlatBuffers schema sources (.fbs)
│   ├── base.fbs
│   ├── msg_envelope.fbs
│   ├── robo_arm_*.fbs           # 4 files
│   ├── robo_chs_*.fbs           # 4 files
│   ├── robo_grip_*.fbs          # 4 files
│   ├── robo_lift_*.fbs          # 4 files
│   ├── robo_manip_*.fbs         # 4 files
│   └── teleop_handle_*.fbs      # 4 files
├── docs/
│   └── api.md                   # Full API reference
├── tests/                       # pytest test suite
├── generate.sh                  # Regenerate Python code from .fbs schemas
├── venv.sh                      # Set up dev virtual environment
├── pyproject.toml
└── LICENSE
```

---

# 📦 Installation

## Requirements

- **Python** ≥ 3.8
- **OS**: Linux
- **Dependencies**:
  - `flatbuffers ≥ 25.0.0`
  - `numpy ≥ 1.17.4`

## Install from Source

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:

```bash
git clone https://github.com/hexfellow/hex_util_msg.git
cd hex_util_msg
./venv.sh
```

2. Activate before using:

```bash
source .venv/bin/activate
```

---

# ⚡ Quick Start

## Import and construct dataclasses

```python
import numpy as np
from hex_util_msg.dataclass import (
    HexBaseVector3, HexBaseQuaternion, HexBasePose, HexBaseTwist,
    HexBaseTime, HexBaseHeader,
    HexBaseJntState, HexBaseJntFull,
    HexRoboArmCtrl, HexRoboArmCtrlMode, HexRoboArmCtrlStamped,
    HexRoboArmState, HexRoboArmStateStamped,
    HexRoboManipCtrl, HexRoboManipState,
    HexTeleopHandleState,
)
```

## Serialize and deserialize with `HexMsgTrans`

```python
from hex_util_msg.trans import HexMsgTrans

# --- Create a stamped arm control message ---
arm_ctrl = HexRoboArmCtrlStamped(
    header=HexBaseHeader(
        seq=1,
        stamp=HexBaseTime(secs=123, nsecs=456_000_000),
        frame_id="arm_base",
    ),
    arm_ctrl=HexRoboArmCtrl(
        ctrl_mode=HexRoboArmCtrlMode.MIT,
        grav=HexBaseVector3(x=0.0, y=0.0, z=9.81),
        jnt=HexBaseJntFull(
            pos=np.zeros(7, dtype=np.float64),
            vel=np.zeros(7, dtype=np.float64),
            eff=np.zeros(7, dtype=np.float64),
            kp=np.full(7, 100.0, dtype=np.float64),
            kd=np.full(7, 10.0, dtype=np.float64),
            lim_vel=np.zeros(7, dtype=np.float64),
            lim_acc=np.zeros(7, dtype=np.float64),
        ),
        pose=HexBasePose(
            position=HexBaseVector3(x=0.5, y=0.0, z=1.0),
            orientation=HexBaseQuaternion(x=0.0, y=0.0, z=0.0, w=1.0),
        ),
    ),
)

# Serialize to bytes
buf = HexMsgTrans.dc2fbs(arm_ctrl)

# Deserialize back — type is auto-detected from the envelope
restored = HexMsgTrans.fbs2dc(buf)

# restored is a HexRoboArmCtrlStamped dataclass
print(restored.header.seq)          # 1
print(restored.arm_ctrl.ctrl_mode)  # HexRoboArmCtrlMode.MIT
```

## Arm state

```python
arm_state = HexRoboArmStateStamped(
    header=HexBaseHeader(seq=0, stamp=HexBaseTime(secs=0), frame_id=""),
    arm_state=HexRoboArmState(
        jnt=HexBaseJntState(
            position=np.array([0.0, 0.25, 0.5], dtype=np.float64),
            velocity=np.array([0.0, 0.0, 0.0], dtype=np.float64),
            effort=np.zeros(3, dtype=np.float64),
        ),
        pose=HexBasePose(
            position=HexBaseVector3(x=1.0, y=2.0, z=3.0),
            orientation=HexBaseQuaternion(x=0.0, y=0.0, z=0.707, w=0.707),
        ),
    ),
)
buf = HexMsgTrans.dc2fbs(arm_state)
restored = HexMsgTrans.fbs2dc(buf)
```

## Teleop handle state

```python
handle = HexTeleopHandleState(
    trigger=0.5,
    axis_x=0.3,
    axis_y=-0.2,
    btn_w=True,
    btn_x=False,
    btn_y=False,
    btn_z=False,
)
buf = HexMsgTrans.dc2fbs(handle)
restored = HexMsgTrans.fbs2dc(buf)
# restored.btn_w == True, restored.trigger == 0.5
```

## Manipulator (composite arm + grip)

```python
manip_state = HexRoboManipState(
    arm_state=HexRoboArmState(
        jnt=HexBaseJntState(
            position=np.zeros(7, dtype=np.float64),
        ),
    ),
    grip_state=HexRoboGripState(
        jnt=HexBaseJntState(
            position=np.zeros(1, dtype=np.float64),
        ),
    ),
)
buf = HexMsgTrans.dc2fbs(manip_state)
restored = HexMsgTrans.fbs2dc(buf)
```

---

# 📑 Documentation

- [**API Reference**](docs/api.md) — Detailed documentation of all dataclasses, enums, and converter functions.

---

# 🔧 Development

## Environment setup

```bash
./venv.sh
source .venv/bin/activate
```

## Regenerating code from schemas

If you modify `.fbs` files under `msgs/`, regenerate the Python bindings:

```bash
# Requires flatc (FlatBuffers compiler) on PATH
./generate.sh
```

This removes existing generated directories and re-runs `flatc --python` for all namespaces.

## Testing

```bash
pytest tests/ -v
```

---

# 📄 License

Apache License 2.0. See [LICENSE](LICENSE).

---

# 👥 Authors & Maintainers

| Role | Name | Email |
|------|------|-------|
| **Author** | Dong Zhaorui | dzr159@gmail.com |
| **Maintainer** | jecjune (Chen Zejun) | zejun.chen@hexfellow.com |
| **Maintainer** | Dong Zhaorui | dzr159@gmail.com |

---

# 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=hexfellow/hex_util_msg&type=Date)](https://star-history.com/#hexfellow/hex_util_msg&Date)

---

# 👥 Contributors

<a href="https://github.com/hexfellow/hex_util_msg/graphs/contributors">
    <img src="https://contrib.rocks/image?repo=hexfellow/hex_util_msg" />
</a>
