Connecting to the robot

The plugin talks to your robot through a small Python daemon called the bridge, egret_bridge.py. It speaks JSON-over-TCP to Grasshopper and the xArm Python SDK to your robot.

Why a bridge? The xArm SDK is Python-only; reimplementing it in C# inside the .gha would mean tracking every firmware change uFactory ships. A small bridge isolates that surface.

Where the bridge runs

Normally, right on your PC, Connect auto-starts egret-bridge.exe for you and it talks to the robot over IP. Your PC just needs network access to the arm.

Topology	Bridge runs on	GH `Host` value
Robot + your PC on the same network (typical)	your PC (auto-started)	`127.0.0.1`
Bridge on a separate machine you manage	that machine	that machine's IP

Starting it, automatic

You don't start the bridge by hand. When you Enable Connect with Host 127.0.0.1 and Auto-start on, Egret launches the bundled egret-bridge.exe against your Robot IP, in read-only (safe) mode first. It accepts state queries but refuses motion until you flip Allow Motion, which restarts it motion-enabled. No terminal, no Python install.

Connect from Grasshopper

Drop a Connect component (→ Live).
Inputs:
- Host: 127.0.0.1 (the default, same-machine bridge).
- Robot IP: your arm's address (see uFactory Studio).
- Port: 65432 (the default).
- Enable: Boolean Toggle, set true.
Drop a Test Bridge downstream. Should report a successful ping with latency in ms, plus the robot IP, mode, and state.
Drop Live State downstream too. Right-click → Timer → check it → set to 100-200 ms. Joint / TCP outputs start streaming.

Wake the robot up, Enable

Robots commonly sit in a stopped / safety state at first contact (state 4 or 5). You'll see status messages like code=9: emergency stop / safety state or code=11: controller state error. Two ways to clear:

Drop the Enable component (→ Live). Wire Connection → C, add a Bool Toggle → Go. Flip to true once. Sends the standard xArm startup sequence: motion_enable(True) + set_mode(0) + set_state(0). Equivalent to clicking "Enable" / "Set Ready" in xArm Studio.
Or open the xArm Studio web UI (typically at the robot's IP over HTTP) and click the equivalent button there.

After enabling, Live State should report state=0 (sport / ready). Motion commands will now go through.

Go motion-enabled (drop --read-only)

Once you trust the path and have enabled the controller, stop the bridge (Ctrl+C) and restart it without the safety flag:

python egret_bridge.py --robot 192.168.1.159 --bind 0.0.0.0

From now on, motion components (Home, Live Send, Drag Mode, etc.) actually move the arm.

Common errors when sending motion:

code=9, emergency stop / safety state. Send Enable.
code=11, controller not in sport state (state 0). Send Enable.
code=1, no motion enable. Send Enable.
code=25, joint motion blocked (collision check). Check the target, lower collision sensitivity if you trust it, or reposition.
code=32, self-collision detected. Plan a different path.
code=10 / code=33, joint out of range. Check Analysis output for which joint exceeds limits.
code=19, Cartesian command unreachable (out of envelope or singularity). Use the IK diagnostic message; try a different orientation or move the target closer to the base.

Read the safety disclaimer before any motion command. Egret is NOT safety-certified. The robot can hurt people and damage property. You are responsible for safe operation, risk assessment, enclosure, the physical E-stop. The GH E-Stop component sends a software command; it is NOT a substitute for the hardware E-stop on the controller.

Next: build the digital twin.