Workflow guide

This guide describes how to build a practical Robots Grasshopper definition. It is not a complete component reference; for individual components, see Components.

Shape of a Good Definition

A robust definition usually has these zones:

1. Cell setup: load the robot system and define the base placement for the current Rhino model.
2. Process data: create or import planes, curves, meshes, fixture geometry, and process parameters.
3. Robot attributes: define tools, frames, speeds, zones, commands, and external axes.
4. Targets: create target lists or toolpaths.
5. Program check: create the program and inspect warnings and errors.
6. Review: simulate, inspect solved joints, check collisions, and review generated code.
7. Output: save files or use remote upload where supported.

Keeping those zones separate makes it easier to see whether a problem belongs to geometry, robot setup, target construction, postprocessor support, or controller transfer.

1. Load the Robot System

Use Load Robot System once for the robot cell.

The Name input selects a library entry. The Base input places the whole system in the current Rhino model. Do not use Base to patch incorrect robot library data; fix reusable kinematic and mesh facts in the library instead.

Use the Libraries button to install online libraries or inspect local overrides. See Robot libraries for library search order, override rules, and file conventions.

2. Define the Tool

Use Load Tool for tools that belong in the shared robot library. Use Create Tool for definition-local tools, temporary tools, or tools driven by Rhino geometry.

At minimum, a tool needs a TCP. Add weight and centroid when payload matters for generated controller code. Add preview meshes only when they help read the file. Library tools can also define collision meshes; Create Tool currently supplies display geometry from Grasshopper.

If the real controller already has tool data, use controller-managed tools in the library XML. See Manufacturer support for controller-managed tool and frame support.

3. Build Targets Intentionally

Targets are the most important objects in a Robots definition.

Use joint targets for home, start, and recovery poses. They are unambiguous and make the beginning of a program easier to verify.

Use Cartesian targets for drawn paths and process geometry. Cartesian targets are convenient, but they still need inverse kinematics. If a pose has several valid joint solutions, previous joints and configuration flags influence which solution is chosen.

Prefer this pattern for process paths:

1. Joint home or safe start target.
2. Approach target.
3. Process targets.
4. Retreat target.
5. Joint safe end target.

Avoid putting commands on targets that you expect to fly through. Robots treats command-bearing targets as stop points so command timing is not hidden inside blended motion.

4. Add Speeds and Zones

Create shared Speed and Zone values when many targets should use the same behavior. This keeps generated code cleaner than repeatedly casting the same numbers or strings.

Use stop zones for targets where precision, tool actions, or operator synchronization matter. Use nonzero zones for continuous motion where exact target contact is not required.

Acceleration settings belong to speed data and generated controller code; they do not turn the preview into a dynamic simulation. See Speed Parameter and Simulation for the exact behavior.

5. Use Frames and External Axes Only When They Mean Something

Frames are useful for work coordinates, fixtures, tables, and mechanisms. Static frames do not need coupling. Coupled frames should be used only when the work coordinate system moves with an external mechanism or coordinated robot.

External axes must match the robot system. If the system expects external values, targets need the right number of values for kinematics, simulation, collision checking, and code generation.

For advanced scripting workflows, custom external-axis output strings can be supplied for code generation, but numeric external-axis values are still needed for simulation.

6. Create the Program

Create Program is the checkpoint before simulation and generated code. Keep the Warnings and Errors outputs visible in the definition, then use Program Parameter as the detailed validation reference.

For multi-robot systems, Create Program adds one target/toolpath input per mechanical group. Keep target counts aligned across groups unless the cell and postprocessor explicitly support the pattern.

7. Simulate and Inspect

Use Program Simulation after Create Program.

Start with normalized time from 0 to 1 to scrub the whole program. Use the solved planes, joint rotations, current target index, and errors to understand where motion fails.

Use Deconstruct Program Targets when you need a table or custom visualization of solved target data. Use Kinematics when you want immediate pose feedback before creating a full program.

Simulation is useful for geometry, sequence, reach, sampling, fly-by previews, and many programming mistakes. See Simulation for the scope and controller behaviors it does not model.

8. Check Collisions Where It Matters

Use Check Collisions after the program can simulate.

Collision checking compares two sets of posed meshes. Mesh order follows Program Simulation. If a library defines collision meshes, they are used internally while keeping the same index order.

Keep collision checks targeted. Checking every mesh against every other mesh is usually noisy and slow. Typical checks include:

• tool against robot links,
• tool against fixture or stock,
• robot links against environment,
• external mechanism against robot or environment.

Treat a clear collision result as one useful check, not a safety certificate.

9. Save or Upload

Use Save Program when generated code is ready to inspect and transfer. Use Remote Connection only for supported manufacturers and only when the controller/network setup is understood.

Always review generated code before running it. If you edit generated files manually, Robots can no longer check those edits.

Pre-Controller Checklist

Before sending anything to a real robot:

• Create Program has no errors.
• All warnings have been reviewed and accepted.
• The first target and recovery target are safe and understandable.
• The selected tool and frame match the real controller setup.
• Speeds and zones are appropriate for first tests.
• Simulation reaches the expected poses.
• Collision checks cover the relevant robot, tool, fixture, and environment geometry.
• Generated code has been reviewed for the selected controller.
• First physical run will happen at reduced speed with normal cell safety procedures.

Where To Go Next

• Core concepts: object model and terminology.
• Components: component-specific behavior.
• Simulation: simulation, fly-by zones, timing limits, and collision checking.
• Manufacturer support: controller-specific support and limitations.
• Troubleshooting: common failures and how to narrow them down.