# Execution model

> Understand how trajectory planning and execution work in Wandelbots NOVA, including planning approaches and control mechanisms.

Wandelbots NOVA's execution model defines how robot motions are planned and executed through the API.
Follow the steps below to understand the end-to-end workflow of planning trajectories and executing them on robots using Wandelbots NOVA.

## Workflow

1. Author motion commands, e.g., line, p2p, via [planTrajectory](https://portal.wandelbots.io/docs/api/v2/ui/#/operations/planTrajectory).
2. Provide planning context with `motion_group_setup`, e.g., robot model, mounting,
   TCP offset, global limits, collision setups, payload, cycle time, including safety data.\
   → The planner returns a joint trajectory.
3. Optional: Cache the trajectory to use a trajectory id instead of sending raw data again.
4. Open the websocket [executeTrajectory](https://portal.wandelbots.io/docs/api/v2/ui/#/operations/executeTrajectory).
5. Initialize, start, pause, adjust the speed, resume or reverse.\
   → The state is streamed until a standstill or completion.

---

The goal: Convert motion commands into a time‑parameterized joint trajectory sampled to a controller's cycle time.

## Step 1: Trajectory planning

1. Enter the planning context: robot kinematics, limits, collision setups, payload, cycle time.
   - If you're using collision-free planning, the collision setups are respected. The planned path length can differ from the geometric path.
   - If you're not using collision-free planning, the planner assumes free space and plans the direct feasible path.
2. Enter the current joint position from [getCurrentMotionGroupState](https://portal.wandelbots.io/docs/api/v2/ui/#/operations/getCurrentMotionGroupState).
3. Provide a list of motion commands including their path, optional blending and limits override.
4. Press `Run`.\
   → The planner will
   - Validate reachability & constraints against `motion_group_setup`.
   - Generate geometric path per command.
   - Optionally plan collision‑free: search a valid path and if not possible, generate a straight path.
   - Sample at cycle\_time to produce joint positions and times.

→ The response will contain the planned joint trajectory or an error if planning failed.

## Step 2: Execution websocket model

The execution model uses a location concept where a scalar \[0, n] indicates progress along the trajectory. `n` is the number of motion commands used in planning.
Integer boundaries correspond to command indices, fractional values indicate positions within path segments.

Open the bidirectional websocket [executeTrajectory](https://portal.wandelbots.io/docs/api/v2/ui/#/operations/executeTrajectory) by streaming one of 4 request types:

| Request | Description |
| - | - |
| `InitializeMovementRequest` | Locks trajectory by id or inline data to connection, sets control mode on the controller, establishes start location. One trajectory per connection is allowed. In order to change the trajectory, reopen the connection |
| `StartMovementRequest` | Begins or resumes a motion forward or backward with `direction` or toward a `target_location`, you can attach output actions `set_outputs` at specific locations and define IO triggers with `start_on_io` and `pause_on_io` |
| `PauseMovementRequest` | Requests pause, movement halts when `Standstill` is emitted, resume with `StartMovementRequest` |
| `PlaybackSpeedRequest` | Adjusts playback speed by scaling velocity profile (0–100%) uniformly, does not reshape profile. Adjusting the playback speed multiple times is possible. |

All requests emit responses, some of them state updates.

### Sequences

Execute repetitions by re-starting closed trajectories for looping. This is useful for cyclic motions.

### Direction & target

| Parameter | Direction |
| - | - |
| `direction` | `forward`: start → end, `backward`: end → start |
| `target_location` | Execute partial ranges, stops at desired location on planned trajectories |

### I/O interactions

| Parameter | Description |
| - | - |
| `set_outputs` | Activate digital/analog outputs immediately after a location is reached |
| `start_on_io` | Gate start until comparator evaluates true |
| `pause_on_io` | Automatically pause when condition true |

## Step 3: States

States are streamed with the closest multiple of the controller step rate ≤ rate configured at initialization.

**Key streamed responses**

- Movement: current joint positions (desired vs. actual), location, velocities.
- `Standstill`: emitted on completion or pause; signals stable state.
- `MovementError`: execution aborted (e.g., controller disconnect).

## Step 4: Control loops & timing

Controller cycle time depends on the manufacturer.\
Wandelbots NOVA performs forward joint position control by sending desired joint positions to the robot controller each cycle.
NOVA OS does not directly command actuator-level outputs such as motor currents.
The robot controller's internal control system is responsible for translating the requested joint positions into the low-level control
outputs required to follow them.

Because execution is subject to the controller, interface, and physical dynamics of the robot,
the actual joint positions can deviate from the commanded positions.

Wandelbots NOVA OS makes sure to send feasible positions.

**Single source of control**

At any given time, only one control source can command robot movements.

**Round‑trip latency**

\~30 ms for virtual controllers; \~100–300 ms for physical controllers, depending on the manufacturer.

**Interpolation & smoothing**

Trajectory assumes spline‑based interpolation. Wandelbots NOVA scales velocities `PlaybackSpeed`
and resamples spline if needed.

## Step 5: Caching & reuse

Reuse trajectories by passing their `id` in the `InitializeMovementRequest` instead of raw data. This allows for faster execution and reduced bandwidth usage, especially for large trajectories or repeated executions.
Caching reduces planning overhead and bandwidth.

## Step 6: Combining trajectories

Combining trajectories is currently not supported but planned for future releases.
This will allow concatenating multiple planned trajectories into one,
preserving location continuity and optionally blending to enable continuous motion.

## Best practices

- Always make sure the robot is at `start_joint_position` before sending `InitializeMovementRequest`.
- Send `PlaybackSpeedRequest` before first `StartMovementRequest` if you need reduced speed from the beginning.
- Use backward direction for safe return along same path.
- For slider UI: `PlaybackSpeedRequest` can be sent repeatedly; each affects next controller cycles.
- Detect completion via `Standstill` flag in state.

## Troubleshooting

### `MovementError`

Stop issuing `Start`/`Pause`. Log the error, re‑establish connection and optionally re‑initialize trajectory.

## Definitions

- [Joint trajectory](/nova/26.7/nova-api/core-concepts/cells-controllers-motion-groups#joint-trajectory)
- [Motion command](/nova/26.7/nova-api/core-concepts/cells-controllers-motion-groups#motion-commands)
- [Location](/nova/26.7/nova-api/core-concepts/cells-controllers-motion-groups#location-on-a-path)
- [Standstill](/nova/26.7/nova-api/core-concepts/cells-controllers-motion-groups#standstill)
- [Playback speed](/nova/26.7/nova-api/core-concepts/cells-controllers-motion-groups#playback-speed)