Metadata-Version: 2.4
Name: hex_util_msg
Version: 0.1.0a0
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.10-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 builder/parser helpers for robotics, teleoperation, and image transport. It is part of the HEXFELLOW ecosystem.

| Module | Primary Purpose | Key Components |
|--------|----------------|----------------|
| **builder_basic** | Scalar, array & timestamp message serialization | `build_hex_float64()`, `build_hex_string()`, `build_hex_ts_ns()`, `parse_hex_float64_array()` |
| **builder_robot** | Robot state & control message serialization | `build_hex_arm_state()`, `build_hex_arm_ctrl()`, `build_hex_grip_ctrl()` |
| **builder_image** | Image transport message serialization | `build_hex_img_simple()`, `parse_hex_img_simple()` |
| **builder_teleop** | Teleoperation input message serialization | `build_hex_teleop_joy()`, `build_hex_teleop_keyboard()` |

## What problem it solves

- **Zero-copy serialization**: Leverage FlatBuffers for high-performance message passing without serialization overhead on the receiving end.
- **High-level builder API**: Convert between `bytes` and plain Python `dict` / `numpy` objects without manually constructing FlatBuffers tables.
- **NumPy integration**: Array fields are serialized and deserialized as `numpy` arrays, making the library natural for scientific and robotics workflows.
- **Four message namespaces**: Organised message types for basic primitives, robot state/control, image transport, and teleoperation input.

## Target users

- Robotics engineers who need efficient inter-process communication with structured messages.
- Developers building control systems that produce or consume FlatBuffers-encoded data.
- Anyone working in the HEXFELLOW ecosystem who needs a standardised message format.

## Project structure

```
hex_util_msg/
├── hex_util_msg/              # Python package
│   ├── __init__.py
│   ├── builder_basic.py       # build/parse for msg_basic
│   ├── builder_image.py       # build/parse for msg_image
│   ├── builder_robot.py       # build/parse for msg_robot
│   ├── builder_teleop.py      # build/parse for msg_teleop
│   ├── msg_basic/             # generated FlatBuffers code
│   ├── msg_image/             # generated FlatBuffers code
│   ├── msg_robot/             # generated FlatBuffers code
│   └── msg_teleop/            # generated FlatBuffers code
├── msgs/                      # FlatBuffers schema sources (.fbs)
│   ├── msg_basic/
│   ├── msg_image/
│   ├── msg_robot/
│   └── msg_teleop/
├── docs/
│   ├── api.md                 # Full API reference
├── tests/                     # pytest test suite
├── generate.sh                # regenerate Python code from .fbs schemas
├── pyproject.toml
└── LICENSE
```

---

# 📦 Installation

## Requirements

- **Python** ≥ 3.10
- **OS**: Linux
- **Dependencies**:
  - `flatbuffers ≥ 25.0.0`
  - `numpy ≥ 2.0.0`

## Install from PyPI

```bash
pip install hex_util_msg
```

## 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

## Basic Types

```python
from hex_util_msg.builder_basic import (
    build_hex_float64, parse_hex_float64,
    build_hex_string, parse_hex_string,
    build_hex_float64_array, parse_hex_float64_array,
)

# Scalar
buf = build_hex_float64(ts_ns=1_000_000, data=3.14)
msg = parse_hex_float64(buf)
# msg == {"ts_ns": 1000000, "data": 3.14}

# String
buf = build_hex_string(ts_ns=1_000_000, data="hello")
msg = parse_hex_string(buf)
# msg == {"ts_ns": 1000000, "data": "hello"}

# Array
buf = build_hex_float64_array(ts_ns=1_000_000, data=[1.0, 2.0, 3.0])
msg = parse_hex_float64_array(buf)
# msg == {"ts_ns": 1000000, "data": array([1., 2., 3.])}
```

## Timestamp Message

```python
from hex_util_msg.builder_basic import build_hex_ts_ns, parse_hex_ts_ns

# Timestamp-only message (no data payload)
buf = build_hex_ts_ns(ts_ns=1_704_000_000_000_000_000)
msg = parse_hex_ts_ns(buf)
# msg == {"ts_ns": 1704000000000000000}
```

## Robot Messages

```python
import numpy as np
from hex_util_msg.builder_robot import (
    build_hex_arm_state, parse_hex_arm_state,
    build_hex_arm_ctrl, parse_hex_arm_ctrl,
)
from hex_util_msg.msg_robot import HexArmCtrlMode

# Build arm state
buf = build_hex_arm_state(
    ts_ns=123,
    jnt_pos=[0.0, 0.25, 0.5],
    jnt_vel=[0.0, 0.0, 0.0],
    pose_pos=[1.0, 2.0, 3.0],
    pose_quat=[0.0, 0.0, 0.707, 0.707],
)
state = parse_hex_arm_state(buf)

# Build arm control
buf = build_hex_arm_ctrl(
    ts_ns=999,
    ctrl_mode=HexArmCtrlMode.mit,
    jnt_pos=np.zeros(6),
    jnt_vel=np.zeros(6),
    mit_tau=np.zeros(6),
    mit_kp=np.full(6, 100.0),
    mit_kd=np.full(6, 10.0),
)
ctrl = parse_hex_arm_ctrl(buf)
```

## Image Messages

```python
import numpy as np
from hex_util_msg.builder_image import build_hex_img_simple, parse_hex_img_simple
from hex_util_msg.msg_image import HexImgEncoding

frame = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
buf = build_hex_img_simple(
    ts_ns=1_704_000_000_000_000_000,
    encoding=HexImgEncoding.bgr8,
    width=640, height=480,
    data=frame,
)
msg = parse_hex_img_simple(buf)
# msg["data"] is a flat uint8 numpy array
```

## Teleop Messages

```python
from hex_util_msg.builder_teleop import (
    build_hex_teleop_joy, parse_hex_teleop_joy,
    build_hex_teleop_keyboard, parse_hex_teleop_keyboard,
)

# Joystick
buf = build_hex_teleop_joy(ts_ns=100, btn_a=True, axis_lx=0.5, axis_ly=-0.3)
joy = parse_hex_teleop_joy(buf)

# Keyboard
buf = build_hex_teleop_keyboard(ts_ns=200, key_w=True, key_a=True)
kb = parse_hex_teleop_keyboard(buf)
```

---

# 📑 Documentation

- [**API Reference**](docs/api.md) — Detailed documentation of all builder functions and message types.

---

# 🔧 Development

## 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 will remove existing generated directories and re-run `flatc --python` for all namespaces.

## Testing

```bash
pip install pytest
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>
