Realtime Robotics RapidPlan 2.5 ASCII API

Revisions

• 2022/03/14: Initial 2.0 API documentation; motion and setup commands.

• 2022/03/21: Preset name argument added to Move and Combined move. Collision checking against DSM has been moved to an explicit new argument in Move command. Combined move structure row clarifications.

• 2022/03/30: GetTCPPose description added (formerly duplicated GetJointAngles). DSM command descriptions added. Additional desctiption added to SetAlternateLocation’s “mode” argument. Moved SetServos location for better organization.

• 2022/04/08: SetResponseType and SetUnits can now be stored per IP address rather than per client. Example CSV responses added to DSM commands. Robot Presets and Object states are now stored to disk so project reload will have the last set values. SetInterruptBehavior timeout value is now used as the timeout for the alternate location mode: 0 with complete_move: 1, and mode: 1. UpdateTarget can now optionally re-generate the autoconnects associated with that target.

• 2022/04/14: AddBox description updated to include box origin and offset argument. AddFrame description updated to note that frames are not saved to disk.

• 2022/04/21: API specs for enabling a subset of a project added (Activate, Deactivate, UpdateInactiveRobotSettings).

• 2022/05/04: SetUnits and SetResponseType descriptions updated to make it clear that only new connections will be affected by set_ip_default.

• 2022/05/12: GetTCPPose YAML response corrected, the key is pose, not tcp_pose. CreateTarget CSV response delayed response corrected from CreateTarget to CreateTargetResult. Added a note to the SetRobotPreset description that ReleaseControl must be called first, if the number of axes on the robot is changing. Added to the UpdateTarget description to indicate that auto connect constraints will be maintained at the targets new location. Updated CancelMove description to note that it is only accepted in OPERATION mode.

• 2022/05/31: Preset argument description updated in Move and CombinedMove. GetJointAngles is being renamed to GetJointConfiguration, but both are supported currently.

• 2022/06/01: Added acceptable string characters to the formation rules section.

• 2022/06/08: Added SetMaxLinearSpeed and SetMaxLinearAcceleration descriptions.

• 2022/06/14: More SetAlternateLocation examples added. Clarified the behavior of the reset flag for SetMaxLinearSpeeds and SetMaxLinearAcceleration.

• 2022/06/17: Corrected SetMaxLinearAcceleration’s max value.

• 2022/07/01: Updated Move with supported move type and goal combinations.

• 2022/08/08: Clarified the effect CancelMove has on queued Move and CombinedMove commands.

• 2022/08/30: Added OverrideInspectError, ToggleMonitorFaults, Calibrate descriptions.

• 2022/08/31: Updated Queuing Moves when a robot preset changes. Updated Queuing Moves with smoothing support. Updated Move spec that supports robot preset changes. Updated SetRobotPreset spec.

• 2022/10/03: Updated DeactivateRobots.

• 2022/12/03: (2.2)Updated CreateTarget to add a new target without connections.

• 2022/12/03: (2.2)Added RenameTarget command.

• 2022/12/03: (2.2)Added RemoveTarget command.

• 2022/12/03: (2.2)Added AddConnection command.

• 2022/12/03: (2.2)Added RemoveConnection command.

• 2022/12/03: (2.2)Updated Move with support for external axes and triggers.

• 2022/12/03: (2.2)Updated CombinedMove with support for external axes and triggers.

• 2022/12/03: (2.2)Updated CancelMove with ramp-down speed at a fixed 80%.

• 2022/12/03: (2.2)Updated SetDefaultProject to clear the default project if project name input is not specified.

• 2022/12/03: (2.2)Added GetLoadedProject command.

• 2022/12/03: (2.2)Added GetRobotPresets command.

• 2022/12/03: (2.2)Updated UserLog with allowed characters in a user log.

• 2022/12/04: (2.2)Danger/risk of interleaving RTR with non-RTR move commands is documented in the Move command.

• 2022/12/05: (2.2)GetJointAngles command is deprecated and replaced by GetJointConfiguration.

• 2022/12/05: (2.2)Added move type and target type support matrix.

• 2022/12/05: (2.2)Added two cautionary statements regarding mixing RTR with non-RTR moves and robot off-roadmap behaviors for Move command.

• 2022/12/09: (2.2)Added a cautionary statement regarding mixing RTR-controlled moves with non-RTR stop commands.

• 2023/01/04: (2.2)SetServos command is removed.

• 2023/01/13: (2.2)Move command and queued move smoothing behavior description is updated.

• 2023/01/18: (2.2)API command string size limit is specified.

• 2023/01/30: (2.2)Move command trigger behavior description is updated.

• 2023/03/06: SetRobotPreset command description is updated

• 2023/03/22: Move Type and Target Type(joint configuration) Support is updated.

• 2023/03/24: Added API Command Determinism section.

• 2023/03/24: (2.3)Added GetFrames command.

• 2023/03/24: (2.3)Added GetObjectStates command.

• 2023/03/24: (2.3)Updated SetDefaultProject command to allow project_name to be optional.

• 2023/03/24: (2.3)Updated GetJointConfiguration command with a new argument native.

• 2023/03/24: (2.3)Updated Move command to support joint configuration target types.

• 2023/03/24: (2.3)Updated Move command to support relative moves including external axes.

• 2023/03/24: (2.3)Updated SetAlternateLocation command with a new argument timeout.

• 2023/03/24: (2.3)Updated SetInterruptBehavior command default values.

• 2023/03/24: (2.3)Updated DeactivateRobot command to allow different key values for treat_as_obstacle.

• 2023/03/24: (2.3)Updated ActivateRobot command with a new argument project_name.

• 2023/03/24: (2.3)Updated CancelMove command with a new argument acceleration_factor.

• 2023/03/24: (2.3)Updated UpdateTarget command with new arguments object_states and pose.

• 2023/03/24: (2.3)Updated ClearFaults command with new argument reset_connection.

• 2023/03/27: (2.3)Updated Move command with new argument costs.

• 2023/03/28: Updated Shutdown command fault codes.

• 2023/03/30: (2.3)Removed UpdateInactiveRobotSettings command due to redundant functionality as DeactivateRobot.

• 2023/03/30: Updated the list of commands that are stored on disk and added the list of commands that are not persistent, under Commands Stored on Disk section.

• 2023/04/03: Updated LoadProject command with argument upgrade.

• 2023/06/12: (2.4) Updated accepted formats for a Boolean value.

• 2023/06/12: (2.4) Updated Move command with a new argument shortest_path_only.

• 2023/06/12: (2.4) Added SetWorkcellState Command.

• 2023/06/12: (2.4) Updated EnterOperationMode command with argument connect.

• 2023/06/12: (2.4) Updated UpdateTarget command with arguments joint_configand ref_frame.

• 2023/06/12: (2.4) Updated GetJointConfiguration command with argument with_joint_names.

• 2023/06/13: (2.4) Move command can use external_axes to specify a relative direct pose move.

• 2023/06/13: (2.4) Added GetTargets command.

• 2023/06/13: (2.4) Added GetStatefulObjects command.

• 2023/06/13: (2.4) Added GetUnits command.

• 2023/06/16: (2.4) Updated description of the system responses to null values.

• 2023/07/14: (2.5) Added validation argument to UpdateTarget command

• 2023/07/19: (2.5) Added BlockMove + ContinueMove commands (more details to come), also updated CombinedMove with new optional blockMove argument

• 2023/08/02: (2.5) Updated Move command with a new argument constraint.

• 2023/08/09: (2.5) Correction of the preset-switching behavior in a CombinedMove command.

• 2023/08/10: (2.5) Updated name of HoldMove and ResumeMove commands (prev. block/continue)

• 2023/08/11: (2.5) Added MultiRobotMove command and updated SetAlternateLocation with a new mode multirobot.

• 2023/09/22: (2.5) Replaced Move command argument constraint with constraints.

• 2023/09/28: (2.5) Add documentation about yaml parsing per RAPID-38095

• 2023/11/16: (2.5) Added a cautionary statement regarding mixing RTR-controlled moves with non-RTR stop commands.

Goal

The ASCII API is a fundamental component of how a user interacts with the Realtime Controller and ultimately controls a robot. In order to effectively complete a task, the user must be able to retrieve information from the Rapidplan Create project, set behavioral characteristics of the robots, and move the robots either following the offline motion plans or with conventional move types.

The 2.0 ASCII API re-implements commands from the 1.x.x version with simplifications, renaming, and overall improvements. Most importantly, the request syntax changed to inline YAML, so that in future 2.x.x versions more functionality can be added while maintaining backwards compatibility. The key value structure will also make messages more readable, and easier to format. Requests can be returned in the same inline YAML format, or the same CSV response type as 1.x.x. versions.

API Format

Syntax (Inline YAML 1.2 Spec)

The ASCII strings received by the Realtime Controller will be formatted to adhere to the inline YAML format, for robust parsing. Inline YAML allows the API to use key-value pairs (KVPs). KVPs will be comma delimited, much like the current API, but attaching keys to the values will allow parameters to come in any order. Additionally, there can be multiple optional parameters and any combination of them. If the optional parameters aren’t used, they can simply be omitted and a default value will be used. Another benefit is readability, since now the values in the requests can be identified based on their key.

Note: the YAML 1.2 spec requires whitespace between after the : in key value pairs.

• {my_key: my_value} will parse as an object with a key my_key whose value is my_value

• {my_key:my_value} will parse as an object with a key my_key:value whose value is null

Command strings will be terminated with CR and LF ASCII characters. The length of the command strings should be less then 2KB. Commands that exceed the 2KB size limit are not forwarded out of the networking layer. They’re simply discarded and the connection is closed.

Requests

Requests sent to the Realtime controller will be formatted according to the inline YAML spec. The function type is set by the topic key and then arguments are passed as key value pairs.

Inline YAML allows the API to be more easily backwards compatible. When arguments are added in the future, they will have a default value, so that existing code will remain functional on newer software versions.

topic: The name of the function being requested. Topic values are case insensitive. Eg. GetMode, Move

data: optional The arguments for the specific topic if required. See the detailed topic descriptions below for more information.

type: optional The type of request being sent. The default value is Command and currently that is the only request type.

id: optional A client can provide an id for the message in order to easily match responses to requests. Any id provided in the request, will be returned in the matching responses. The value can be either a string or int. Note: CSV response types omit this field since it is optional.

Formation Rules

All requests made to the Realtime Controller adhere to the following formation rules:

• The topic values are case insensitive.

• Any required key must be 100% correct and contain a valid value, otherwise the request is rejected.

• If an optional key is not specified (either because it was not provided or because the key was malformed) the default value for the key is used.

• Any optional key that is provided must contain a correct and valid value, otherwise the request is rejected.

• If irrelevant keys are passed (including malformed optional keys), they are ignored.

• If a value is valid but out of a range that we specify, the request is rejected.

• Strings may only contain: numbers, letters, hyphens, and underscores

Boolean Values

When an argument expects a boolean type, the acceptable values are integers or case insensitive strings.

The following are evaluated as True:

• y|Y|yes|Yes|YES|true|True|TRUE|on|On|ON

• 1

The following are evaluated as False:

• n|N|no|No|NO|false|False|FALSE|off|Off|OFF

• 0

Responses

Responses can be returned in CSV format for easy parsing, or in YAML format for human readability and programming languages that support it. The CSV responses will follow a fixed order with no optional returns, and therefore are more limited than the YAML response type. For any complex types returned in YAML (like an array), the values will be broken out in the CSV response. See GetJointConfiguration for an example.

The default response type is YAML, but upon establishing a connection, a client can immediately specify CSV response type with the SetResponseType command and never needs to parse YAML.

Responses will include an optional error key if a problem has occurred preventing completion of the request. This key data is a dictionary containing code and msg keys, which provide the numeric code and a text description of the error. Note: CSV responses will always contain the error code, with code 0 indicating success. Subsequent result key value pairs depend on the request command that was received.

Commands can have multiple response types. The types are: Response,Feedback, and DelayedResponse.

• A Response is always returned and it indicates if the request has executed successfully or not.

• Null values, such as null, ~, '' (empty string), Null, and NULL are interpreted as normal strings. If a user sets an API command argument with a null value, the value will be checked for validity against the target RapidPlan project or RapidPlan settings. If not found, these null values will be rejected by RapidPlan with a “xxxx_NOT_FOUND” error.

• A DelayedResponse is returned for commands that take time to execute, like a Move or LoadProject. When a Response includes a seq key, that indicates that a DelayedResponse will be returned for that command. Both the immediate and delayed responses will have a globally unique sequence number (referred to as seq) so that the delayed response can be matched to the command it is for.

• A Feedback response is returned when an intermediate event occurs before the completion of the command. For example, each move segment in a CombinedMove command returns a Feedback response to indicate its completion before the CombinedMove completes and returns its DelayedResponse.

Immediate Responses:

Feedback Responses:

Delayed Responses:

topic: The name of the message type. Eg. GetMode, Move

type: The type of response being provided; either Feedback Responses or Delayed Responses.

data: optional The return arguments for the specific topic. If an error occurs, data will not be returned.

error: optional If an error occurs, the error code and text description will be returned in the YAML format. In the CSV response the code will be returned in every response.

id: optional A client can provide an id for the message in order to easily match responses to requests. If a client provided an id, the same id will be returned in the responses. Note: if the response type is CSV and a id is provided in the request, it will be omitted in all responses due to the no optional returns rule.

Stateful Commands

Commands can now be stateful. Before, a workstate had to be passed in every MOVE command, but now the workcell and robot presets are set, and then subsequent move commands use the active preset.

Commands Stored on Disk

Certain commands are now stored on disk, so when the project is unloaded and reloaded, they hold their previous state. This will reduce the amount of repetitive commands during integration and testing, while also resulting in more predictable behavior.

• SetDefaultProject

• DeactivateRobot

• SetRobotPreset

• SetObjectState

• CreateTarget

• UpdateTarget

• RenameTarget

• RemoveTarget

• AddConnection

• RemoveConnection

The following API commands are not persistent after a RTR controller is rebooted. These commands must be reissued to ensure the project settings are restored after the project is reloaded.

• SetMaxLinearAcceleration

• SetMaxLinearSpeed

• SetAlternateLocation

• SetInterruptBehavior

• SetResponseType

• SetUnits

• Scene Modeling commands

Command Determinism

When API commands come from the same source, e.g. a single TCP socket, the API commands are processed in the order of when they are received. In a multi-robot cell, the execution of the API commands for each robot is ordered and deterministic when the response code is confirmed by the source before the next API command is sent.

When API commands come from multiple sources, the API commands are processed by a RTR controller without considering the order of the command execution between robots. As a result, the execution of the API commands between robots may become out of order, due to the timing of when each API command arrives from different sources. Therefore, if consistent API command ordering is required from multi sources, it is necessary for the command sources to synchronize with each other.

Default Units

Unless set by the SetUnits command, all requests and responses with the Realtime Controller assume millimeters for lengths and degrees for angles.

Move Type and Target Type Support

API support for moves without using external_axes argument:

API support for moves using external_axes argument: