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:

Message Categories

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 HexFbsMsgEnvelope 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
│   ├── teleop_joystick_state.fbs
│   ├── teleop_joystick_state_stamped.fbs
│   ├── teleop_keyboard_state.fbs
│   └── teleop_keyboard_state_stamped.fbs
├── 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 (
    HexDcBaseVector3, HexDcBaseQuaternion, HexDcBasePose, HexDcBaseTwist,
    HexDcBaseTime, HexDcBaseHeader,
    HexDcBaseJntState, HexDcBaseJntFull,
    HexDcRoboArmCtrl, HexDcRoboArmCtrlMode, HexDcRoboArmCtrlStamped,
    HexDcRoboArmState, HexDcRoboArmStateStamped,
    HexDcRoboManipCtrl, HexDcRoboManipState,
    HexDcTeleopHandleState,
)

Serialize and deserialize with HexMsgTrans

from hex_util_msg.trans import HexMsgTrans

# --- Create a stamped arm control message ---
arm_ctrl = HexDcRoboArmCtrlStamped(
    header=HexDcBaseHeader(
        seq=1,
        stamp=HexDcBaseTime(secs=123, nsecs=456_000_000),
        frame_id="arm_base",
    ),
    arm_ctrl=HexDcRoboArmCtrl(
        ctrl_mode=HexDcRoboArmCtrlMode.MIT,
        grav=HexDcBaseVector3(x=0.0, y=0.0, z=9.81),
        jnt=HexDcBaseJntFull(
            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=HexDcBasePose(
            position=HexDcBaseVector3(x=0.5, y=0.0, z=1.0),
            orientation=HexDcBaseQuaternion(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 HexDcRoboArmCtrlStamped dataclass
print(restored.header.seq)          # 1
print(restored.arm_ctrl.ctrl_mode)  # HexDcRoboArmCtrlMode.MIT

Arm state

arm_state = HexDcRoboArmStateStamped(
    header=HexDcBaseHeader(seq=0, stamp=HexDcBaseTime(secs=0), frame_id=""),
    arm_state=HexDcRoboArmState(
        jnt=HexDcBaseJntState(
            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=HexDcBasePose(
            position=HexDcBaseVector3(x=1.0, y=2.0, z=3.0),
            orientation=HexDcBaseQuaternion(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 = HexDcTeleopHandleState(
    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 = HexDcRoboManipState(
    arm_state=HexDcRoboArmState(
        jnt=HexDcBaseJntState(
            position=np.zeros(7, dtype=np.float64),
        ),
    ),
    grip_state=HexDcRoboGripState(
        jnt=HexDcBaseJntState(
            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

🌟 Star History

👥 Contributors