robonix.skill.dobot.nova5.pick_return

skill package v0.1.0

Separate RGB-guided Nova5 pick, place and home capabilities.

README skill-nova5-pick-return-rbnx@main

Nova5 pick and return

This package exposes three independently callable capabilities: pick locates the box using wrist RGB and holds it after a verified 30 mm lift; place returns it to the recorded position and retreats; home returns the empty arm to the configured home pose. Pilot composes these actions according to the request. No action automatically starts the next one. SDK commands use Tool0 flange MovL at 50 mm/s and a 174 mm TCP offset: the measured 165 mm gripper assembly plus the 9 mm white adapter plate. This does not guarantee constant fingertip speed during rotation.

Build

Use Linux, Python 3.12, and Robonix configured with rbnx setup, with its executables on PATH. The robot deployment README lists the required core changes and setup commands.

export NOVA5_SUPPORT_SOURCE=/absolute/path/to/nova5-support
export NOVA5_HARDWARE_SOURCE=/absolute/path/to/primitive-dobot-nova5-arm-rbnx
rbnx validate .
rbnx build -p .

Use version 0.1.0 of both dependencies. Source variables also accept pip VCS URLs pinned to a published commit. The build installs dependencies into rbnx-build/venv and generates interfaces using the API located by rbnx path robonix-api.

Configure and run

Deploy with rbnx boot and an absolute workflow JSON path in the package's settings configuration key. The JSON contains calibration_config, artifacts_dir, arm_provider_id, camera_provider_id, object_description, object_height_mm, allowed_xy_mm, and home_flange_mm_deg; file paths resolve relative to that JSON. The robot deployment supplies a template. Generate calibration results for the actual hardware using nova5-support.

The skill connects to deployed arm, hand and camera capabilities through Atlas. Device connections belong to the primitives. Arm commands and feedback use the 174 mm TCP in base_link; the hardware primitive converts commands to flange poses. PGI contact and continuous controller feedback use the hardware package's typed status extension. All providers run on the same host.

Provide VLM_BASE_URL and VLM_API_KEY. The endpoint must support gpt-6-astra, images and structured responses. Workflow visual checks default to VLM_REASONING_EFFORT=high.

The arm must be enabled, idle and in TCP control mode with zero User0/Tool0. The gripper must be initialized and idle, with force 20%, speed 1%, IO mode 0, and equal target/actual opening. Start at least 200 mm above the table. The target must be a box 40–60 mm tall inside the configured workspace.

Grasp execution requires motion.enabled=true, motion.speed_mm_s=50, and finite XYZ workspace_min_mm/workspace_max_mm bounds in the calibration configuration. The hardware provider also needs enable_opening=true to release the box after placement. Planned and current flange/TCP endpoints must remain within those bounds; stage-specific bounds and allowed_xy_mm still apply. Endpoint checks do not establish a collision-free path.

After activation, call pick with target="box", place with {}, or home with {}. Each action returns a run ID and has its own /status and /cancel contracts. Executor polls completion and forwards cancellation. The allowed order is EMPTY -> pick -> HOLDING -> place -> PLACED -> home -> EMPTY. The skill remains one provider so the three actions share a lock and task state.

The task journal is artifacts_dir/task-state.json; keep it and its referenced images between calls. It records the observed position, final pose, hand state, hardware session and configuration fingerprint. Place/home reject changed configuration, a restarted hardware provider, lost contact or an altered pose. A failed, canceled or interrupted action blocks continuation even after restart. After physical inspection and manual recovery to an empty, stationary arm at a valid starting pose, stop the deployment and archive the journal before a fresh task. Never delete it while holding an object or while an action is running. The skill does not perform unattended recovery or release a held object on exit.

The workflow waits for remote workers and stationary feedback before confirming cancellation. A cancellation acknowledgement and Executor ControlPlan.completed only confirm acceptance and local plan completion. Skill CANCELED confirms worker exit after arm/hand stop checks; camera cleanup belongs to its Driver. Deactivation waits up to 15 seconds and reports unconfirmed cleanup as failure. Logs are under artifacts_dir and must be accessible to Pilot. After 100 retained action records, stop the deployment and archive old records before continuing.

Test

PYTHONPATH="$PWD/rbnx-build/codegen/proto_gen:$PWD/rbnx-build/codegen/robonix_mcp_types" \
  rbnx-build/venv/bin/python -m unittest discover -s tests

Tests do not move hardware. Before publication, verify registration and lifecycle.

CI runs the build script and offline tests on Linux with Python 3.12. Its build baseline is Robonix commit e66e4abebd9c2cbb034015f5589592825d65f3df, with robonix-api[codegen] installed. It installs dependencies from the public mikequ95/nova5-support and mikequ95/primitive-dobot-nova5-arm-rbnx repositories at their v0.1.0 tags.