hex-util-msg 0.1.0a0

HEXFELLOW Util Message

HEXFELLOW UTILITY MESSAGES

                    

---

📖 Overview

What is hex_util_msg

hex_util_msg is a Python message library that provides FlatBuffers 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

pip install hex_util_msg

Install from Source

We use uv to manage the Python environment. Please install it first.

1. Clone and install in editable mode:

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

2. Activate before using:

source .venv/bin/activate

---

⚡ Quick Start

Basic Types

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

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

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

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

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 — 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:

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

This will remove existing generated directories and re-run flatc --python for all namespaces.

Testing

pip install pytest
pytest tests/ -v

---

📄 License

Apache License 2.0. See LICENSE.

---

👥 Authors & Maintainers

Role	Name	Email
Author	Dong Zhaorui	[e-mail]
Maintainer	jecjune (Chen Zejun)	[e-mail]
Maintainer	Dong Zhaorui	[e-mail]

---

🌟 Star History

---

👥 Contributors