Hex Device Python Library

中文 | English

Overview

This library provides a simple interface for communicating with and controlling Hex devices. It uses Protocol Buffers for message serialization and WebSocket for real-time communication. The supported hardware list is as follows:

• [✅] ChassisMaver
• [✅] ChassisMark2
• [✅] ChassisTriggerA3
• [✅] ArmArcher
• [✅] ArmSaber
• [✅] ArmFirefly
• [✅] HandsHtGp100
• [✅] HandGp80G1
• [✅] LiftLotaP1
• [✅] RtZetaVc2
• [✅] Hello

Prerequisites

• Python 3.9 or higher
• Anaconda Distribution (recommended for beginners) - includes Python, NumPy, and commonly used scientific computing packages

Installation

Install from PyPI (Recommended)

pip install hex_device

Clone the Repository (Development)

git clone --recurse-submodules https://github.com/hexfellow/hex_device_python.git

Quickstart

If you have already installed the library from PyPI using pip, please refer to Usage

Install protoc

1. Install protoc from package manager (Recommended only for Debian13/Ubuntu24.04)

   sudo apt install protobuf-compiler
   

2. Install protoc from Github Releases (Recommended Ubuntu22.04 and below)

   Just choose a suitable version and install it. Here below is an example of installing protoc-27.1.

   # For Linux x86_64
   wget https://github.com/protocolbuffers/protobuf/releases/download/v27.1/protoc-27.1-linux-x86_64.zip
   sudo unzip protoc-27.1-linux-x86_64.zip -d /usr/local
   rm protoc-27.1-linux-x86_64.zip
   
   # For Linux arm64
   wget https://github.com/protocolbuffers/protobuf/releases/download/v27.1/protoc-27.1-linux-aarch_64.zip
   sudo unzip protoc-27.1-linux-aarch_64.zip -d /usr/local
   rm protoc-27.1-linux-aarch_64.zip
   
   # Verify installation
   protoc --version # Should be or more than 3.21.12
   

Install hex_device

Compile Protocol Buffer messages:

mkdir ./hex_device/generated
protoc --proto_path=proto-public-api --python_out=hex_device/generated proto-public-api/*.proto && cp ./proto-public-api/version.py ./hex_device/generated/version.py

Option 1: Package Installation

To install the library in your Python environment:

python3 -m pip install .

Option 2: Direct Usage (No Installation)

If you prefer to run the library without installing it in your Python environment:

1. Install dependencies:

   python3 -m pip install -r requirements.txt
   

2. Add the library path to your script:

   import sys
   sys.path.insert(1, '<your project path>/hex_device_python')
   sys.path.insert(1, '<your project path>/hex_device_python/hex_device/generated')
   

Usage

• The complete function interfaces can be found in our wiki. If you are new to the library, we strongly recommend skimming the available control interfaces first.
• If you are using a robotic arm, you can refer to the docs for the controller port instructions.

Examples

• Simple demo for all devices: tests/main.py
• Robotic arm trajectory tracking: tests/archer_traj_test.py or tests/saber7dof_traj_test.py

Basic Usage

IPv4 connection:

python3 tests/main.py --url ws://0.0.0.0:8439

IPv6 connection:

python3 tests/main.py --url ws://[fe80::500d:96ff:fee1:d60b%3]:8439

Q&A

How do I connect using IPv6?

You can connect to our devices using IPv6, which enables direct connection without a router (e.g., using a single cable to connect the robot and PC).

Note: We assume you have basic knowledge about IPv6. If you don't, please use IPv4 instead. We will not explain IPv6 in detail.

Key points:

• Without DHCP6, devices can still have a link-local address
• To use link-local addresses, you must specify the zone ID of the interface using the % symbol
• You can find the zone ID of the interface by running ip a

Example:

# Find the interface and zone ID
ip a

# Use the zone ID in the connection URL
ws://[fe80::500d:96ff:fee1:d60b%3]:8439

Why did a previously working software package stop working after a redeployment?

Please check the Change log to see if you are using cross-version software packages. Additionally, we recommend that you use a fixed software version after successful deployment to avoid code failures due to incompatible updates.

If I want to use newer software packages, how do I perform hardware upgrades?

Please contact our after-sales service, and we will provide hardware upgrade instructions based on the equipment you purchased.

Copyright © 2025-present Hexfellow Org