hex-util-msg 0.1.0a1

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

Import and construct dataclasses

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

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

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

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)

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 — Detailed documentation of all dataclasses, enums, and converter functions.

---

🔧 Development

Environment setup

./venv.sh
source .venv/bin/activate

Regenerating code from schemas

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

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

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

Testing

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