Migration guide v1 → v2

This migration guide highlights the changes in the Wandelbots NOVA API v2 compared to the Wandelbots NOVA API v1. v2 comes with improvements like a less complex API and a more intuitive way to interact with the robot. We're happy to announce that the v2 will feature consistent API behavior across endpoints as well as less endpoints.

Read through the NOVA API v2 quickstart and try it out using the NOVA API v2 reference (opens in a new tab)! If you have any questions or need help, feel free to ask in the Wandelbots Robotics community.

Wandelbots NOVA API V1 will be deprecated once v2 is stable.

How to read this guide

With Wandelbots NOVA API v2, some workflows have changed in their functionality while other endpoints remain unchanged in their functionality. Almost all endpoints have been renamed to be more intuitive and easier to use. Some of them have been regrouped.

To facilitate the migration from v1 to v2, this guide is structured as follows:

Both workflow updates and name changes include a mapping table per endpoint that lists the version, group and endpoint for both v1 and v2. If the endpoint name differs between v1 and v2, the v2 endpoint is listed with the renamed endpoint so that it's easier to find.

Details about endpoints are provided in horizontal tabs.

Parameter conversion

Refer to this table for the parameter conversion between v1 and v2:

General changes

Parameter case

v2 endpoints use snake_case for the parameters, while v1 endpoints use camelCase.

Separation of input and feedback

With v2, input and feedback are separated, which means that all output is provided by the state centrally, not individually by each endpoint.

Planning and execution endpoints

Planning and execution endpoints were separated.

State and description endpoints

State endpoints fetch dynamically changing data, e.g. joint positions, controller operating modes. Description endpoints fetch static data that is valid over the lifetime of a connection, e.g. configured TCPs, safety zones, limits.

Managing coordinate systems on controllers

Adding and deleting coordinate systems on physical controllers is no longer supported in v2. Use the original teaching pendant to add and delete coordinate systems on the controller.

For virtual controllers, you can still add and delete coordinate systems using the Virtual Robot Configuration endpoints.

Typo fixed in motion group path of Virtual Robot Description endpoint

motiongroups was fixed to motion-groups in v2.

Created controllers can immediately be listed

Performance upgrade: After adding a controller via POST /api/v2/cells/{cell]/controllers, a subsequent GET /api/v2/cells/{cell}/controllers immediately lists the added controller, using an adequate status.

New functionalities

Group attributes

System state and cell service state provide a group attribute for each service with v2.

Backup

You can now create a configuration backup of controller configurations, including filtering for specific services.

1. Use System > List Configuration Resources GET /api/v2/system/configuration/resources to list available configuration resources.
2. Use System > Retrieve Configuration Backup GET /api/v2/system/configuration and use the previously listed configuration resources. to create a backup.
3. Use System > Restore Configuration Backup POST /api/v2/system/configuration to restore a configuration backup.

Activate and deactivate cells

Manage which cells are active or inactive with Cell > Operating State PUT /api/v2/cells/{cell}/status. Inactive cells will not be displayed on the homescreen.

Motion group state streams and description

Listing and (de)activating motion groups is no longer supported in v2, but therefore a new state stream websocket as well as a state and description endpoints are available.

• Motion Group > Description GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description\
• Motion Group > State GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state\
• Motion Group > State Stream GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state-stream

Inverse kinematics

You can now receive a list of reachable joint positions for a given pose with Kinematics > Inverse kinematics POST /api/v2/cells/{cell}/kinematic/inverse

Trajectory caching

With v2, you can cache trajectories to avoid planning them again with the endpoint group labelled Trajectory Caching.

Workflow updates

Use v1 endpoints for these functionalities

Generic capabilities

Capabilities of a controller were previously listed in Motion Group Infos > Capabilities and very specific, e.g. list_tcps. They are now replaced by Controller > Descriptions endpoint.

Current payload

Payloads are only supported by Motion Group > State and not by Motion Group > State Stream. We're working on streaming active payloads in the future.

Planning and executing trajectories for connected motion groups

API v2 features a bi-directional websocket to execute trajectories. The Trajectory Planning, Execution and Caching endpoints replace the v1 Motion endpoints for planning and executing motions.

The common workflow with v2 is the following:

1. Fetch parameters for the connected motion group using getMotionGroupDescription.
2. planTrajectory.
3. executeTrajectory.

For a detailed mapping of v1 Motion endpoints to v2 Trajectory Planning, Execution and Caching endpoints, see the section below.

Jogging motion groups

You now have a single bi-directional websocket for jogging functionalities:

Jogging > Execute Jogging GET /api/v2/cells/{cell}/execution/jogging

Device Configuration

All Device Configuration endpoints were removed in v2. To replace the functionalities, use the Controller endpoint and update the devices by updating controller configurations.

Regrouped endpoints resulting in new paths

The endpoints listed in this section have been regrouped in v2 but maintain the same functionality.

Motion Group Infos

Motion Group Kinematic

Virtual Robot

Virtual Robot Mode