dora-ulite6/AGENTS.md

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

What this is

A dora-rs Python node that interfaces with a UFactory Lite6 robot arm. On each tick it reads joint angles and TCP pose from the robot and publishes them as dora outputs. It also accepts JSON commands (home, move_to, move_to_pose, vacuum_on/off) via a command input. A FastAPI REST server with a web UI runs in a background thread for manual control. The robot control wrapper lives in dora_ulite6/main.py as the ULite6Helper class, and the dora event loop is the main() function in the same file.

Build

uv pip install -e .

Requirements: Python >=3.8, uv, and network access to the UFactory Lite6 robot.

Run

dora up
dora start dataflow.yml

Robot behavior is configured through environment variables (see README.md for the full list: ROBOT_IP, DEFAULT_SPEED, DEFAULT_UNITS, API_HOST, API_PORT, VACUUM_ENABLED, INIT_MODE, etc.).

Architecture

• dora_ulite6/main.py -- Single-file implementation containing:
  • ULite6Helper: Wraps the xArm Python SDK for motion control (go_home, move_to_pose, get_current_position, get_joint_angles_deg, get_pose_matrix, vacuum gripper, status, reset).
  • MoveToRequest / MoveToPoseRequest: Pydantic models for API validation.
  • create_api(): FastAPI app factory with REST endpoints and embedded HTML/JS web UI for manual control.
  • main(): Dora event loop. Starts FastAPI in a daemon thread, then processes tick (publishes joint_pose and tcp_pose) and command (executes robot actions and publishes status) inputs.
• dora_ulite6/__init__.py -- Package marker.
• pyproject.toml -- Package metadata, dependencies, and entry point.
• dataflow.yml -- Example dora dataflow using the git: source format.

Key APIs

• dora Python API (dora): Node(), node.send_output(), event iteration via for event in node.
• xArm SDK (xarm.wrapper.XArmAPI): connect(), motion_enable(), set_mode(), set_state(), set_position(), move_gohome(), get_position(), get_servo_angle(), set_vacuum_gripper().
• Output data is sent as PyArrow arrays with metadata dicts.

Tools

• Issue tracker: Gitea. Use the Gitea MCP tools (mcp__gitea__*) to read and manage issues, pull requests, and other repository operations.

Rules

• Do not mention AI tools in commit messages or documentation.
• This controls a real robot. Test changes carefully and preserve safety checks.