/
2.2 Realtime Robotics RapidPlan ASCII API

2.2 Realtime Robotics RapidPlan 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: Initial RSM command documentation. 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/04/28: GetRapidSenseStatus now returns the pallet_id if one exists. InspectPallet no longer returns the package_id. QueryClearance argument description and response details corrected to state that the clients active units will be used for the clearance value. Fixed minor typos in AddFrame and InspectInboundPackage.

  • 2022/05/02: InspectInboundPackage now returns the package_orientation. Interlock generation and report commands added.

  • 2022/05/03: InspectPallet now returns the package_id.

  • 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 spec for 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 spec for DeactivateRobots.

  • 2022/12/03: (2.2)Updated spec for 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 spec for Move with support for external axes and triggers.

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

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

  • 2022/12/03: (2.2)Updated spec for 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 spec for 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 2 cautionary statements regarding mixing RTR with non-RTR moves and robot off-roadmap behaviors for Move command.

  • 2022/12/09: (2.2)Added 1 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

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.

Command strings will be terminated with CR+LF line endings. 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: <value>, type: <value>, id: <value>, data: {key1: value1,...,keyN: valueN}}

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:

  • true (or any capitalized form eg. True, TRUE)

  • 1

The following are evaluated as False:

  • false (or any capitalized form eg. False, FALSE)

  • 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 type are: Response,Feedback, and DelayedResponse.

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

  • 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 it’s completion before the CombinedMove completes and returns it’s DelayedResponse.

Immediate Responses:

{topic: <value>, type: Response, id: <value>, error: {code: <value>, msg: <value>}, data: {result1: <value>,...,resultN: <value>}} or in the CSV response, TopicName,code,result1,...,resultN

Feedback Responses:

{topic: <value>,type: Feedback, id: <value>, error: {code: <value>, msg: <value>}, data: {result1: <value>,...,resultN: <value>}} or in the CSV response, TopicNameFeedback,code,result1,...,resultN

Delayed Responses:

{topic: <value>,type: DelayedResponse, id: <value>, error: {code: <value>, msg: <value>}, data: {result1: <value>,...,resultN: <value>}} or in the CSV response, TopicNameResult,code,result1,...,resultN

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

type: The type of response being provided; either Response or DelayedResponse.

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

  • SetRobotPreset

  • SetObjectState

  • CreateTarget

  • UpdateTarget

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:

 

direct

roadmap

planning

 

direct

roadmap

planning

target

>=2.2

>=2.0

>=2.0

config

Not supported

Not supported

Not supported

pose

>=2.0

>=2.0

>=2.2

 

API support for moves using external_axes argument:

 

direct

roadmap

planning

 

direct

roadmap

planning

target

N/A*

N/A*

N/A*

config

Not supported

Not supported

Not supported

pose

>=2.2

>=2.2

>=2.2

*In Rapidplan create, targets are defined by full joint configuration of a robot, including external axes values.

API Endpoints - Project

SetResponseType

Structure

{topic: SetResponseType,data: {response_type: <value>, set_ip_default: <value>}}

Argument Description

response_type: This indicates which format the Realtime Controller will use when sending responses; either CSV or yaml. The default response type is yaml. The argument can be either case insensitive text or its numeric equivalent.

  • 0 or csv

  • 1 or yaml

set_ip_default: optional This optional boolean argument will store the response type based on the devices IP address rather than for the current socket. All new connections from the IP address will use this response type.

Function Description

This command is used to set the response format of the TCP/IP communication with the Realtime Controller. The Realtime controller stores this response type for each client that is connected to it. This command should be called at the beginning of a program to indicate the format in which the responses should be sent. If this command is not sent, the default response type is yaml.

If the set_ip_default argument is enabled, then all new connections from the IP address will use the specified response type. Existing sockets will be unaffected by this change, until they re-establish a connection.

As long as the IP address has at least one open connection, the settings will persist.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: SetResponseType,data: {response_type: csv}}

Example YAML Responses

{topic: SetResponseType,type: Response}

Example CSV Responses

SetResponseType,0

SetUnits

Structure

{topic: SetUnits,data: {length: <value>,angle: <value>, set_ip_default: <value>}}

Argument Description

length: This specifies the unit of measure for length. The unit can be specified with a case insensitive string or its corresponding integer value. For example, when a pose is specified this length unit will be used.

  • 0 or m,meter,meters

  • 1 or cm,centimeter,centimeters

  • 2 or mm,millimeter,millimeters

  • 3 or ft,foot,feet,'

  • 4 or in,inch,inches,”

angle: This specifies the unit of measure for angles. The unit can be specified with a case insensitive string or its corresponding integer value. For example, when a robot’s joint angles are set or when a frame’s rotation is specified, this angle unit will be used.

  • 0 or rad,rads,radian,radians

  • 1 or deg,degs,degree,degrees,°

set_ip_default: optional This optional boolean argument will store the unit change based on the devices IP address rather than for the current socket. All new connections from the IP address will use these unit preferences.

Function Description

This command is used to set the unit convention for API calls made to the Realtime controller. On first project load, the default units of millimeters and degrees will be used, and if this command is called, the units will be stored for that specific client. Subsequent loads for that project will use require the client to reinitialize their unit convention.

If the set_ip_default argument is enabled, then all new connections from the IP address will use these unit preferences. Existing sockets will be unaffected by this change, until they re-establish a connection.

As long as the IP address has at least one open connection, the settings will persist.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: SetUnits,data: {length: in, angle: deg}}

Example YAML Responses

{topic: SetUnits,type: Response}

Example CSV Responses

SetUnits,0

GetMode

Structure

{topic: GetMode}

Argument Description

None

Function Description

This command retrieves the current mode of the Realtime Controller.

Response Details

This command will return a response code, followed by the current state of the system.

Example Request

{topic: GetMode}

Example YAML Responses

{topic: GetMode,type: Response,data: {mode: CONFIG}} {topic: GetMode,type: Response,data: {mode: OPERATION}} {topic: GetMode,type: Response,data: {mode: CALIBRATION}} {topic: GetMode,type: Response,data: {mode: FAULT}}

Example CSV Responses

GetMode,0,CONFIG GetMode,0,OPERATION GetMode,0,CALIBRATION GetMode,0,FAULT

ClearFaults

Structure

{topic: ClearFaults}

Argument Description

None

Function Description

If a robot error/fault state occurs for one of the robots in the currently loaded deconfliction group, the Realtime Controller will enter a fault state. Examples of reasons may be: lost connection to a robot, robot entering an E-stopped state, or the robot entering a fault state due to excessive speed or force. The ClearFaults command will attempt to recover any faults that the OEM controller allows allows to be cleared programatically, and transition the Controller back into Config mode if possible. It will fail if there are still active, unresolvable faults.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: ClearFaults}

Example YAML Responses

{topic: ClearFaults,type: Response} or if the faults cannot be cleared by the Realtime Controller {topic: ClearFaults,type: Response,error: {code:1004,msg:FAILED_TO_CLEAR_FAULTS}}

Example CSV Responses

ClearFaults,0 or if the faults cannot be cleared by the Realtime Controller ClearFaults,1004

LoadProject

Structure

{topic: LoadProject,data: {project_name: <value>}}

Argument Description

project_name: The name of the project installed on the control panel that you want to load.

Function Description

This function loads an RPC project. A load result will be returned once the process has finished and then RapidPlan will be in configuration mode.

Response Details

This command will return a response code to acknowledge the command has been received.

{topic: LoadProject,type: Response,data: {seq: <value>}}

Delayed Response Details

Once the load is completed, the system will send a delayed response to indicate the project has finished loading.  

{topic: LoadProject,type: DelayedResponse,data: {seq: <value>}}

Example Request

{topic: LoadProject,data: {project_name: DemoProject}}

Example YAML Responses

{topic: LoadProject,type: Response,data: {seq: 128}} … load executes … {topic: LoadProject,type: DelayedResponse,data: {seq: 128}}

Example CSV Responses

LoadProject,0,128 … load executes … LoadProjectResult,0,128

GetLoadedProject

Structure

{topic: GetLoadedProject}

Argument Description

None

Function Description

This command retrieves the currently loaded project on the Realtime Controller.

If a project is not currently loaded, an error code will be returned {code: 3009,msg: PROJECT_NOT_LOADED}

Response Details

This command will return a response code, followed by the currently loaded project or appropriate error code.

Example Request

{topic: GetLoadedProject}

Example YAML Responses

// Response when a project is loaded {topic: GetLoadedProject,type: Response,data: {project_name: WeldCell}} // Response with no project loaded {topic: GetLoadedProject,type: Response,error: {code: 3009,msg: PROJECT_NOT_LOADED}}

Example CSV Responses

// Response when a project is loaded GetLoadedProject,0,WeldCell // Response with no project loaded GetLoadedProject,3009

UnloadProject

Structure

{topic: UnloadProject}

Argument Description

None

Function Description

This command brings the Realtime Controller out of operation mode and unloads the project. Current motions will be cancelled, and no new motion requests will be accepted. Duplicate calls have no effect. Connection to robot controllers will be terminated.

Response Details

This command will return a response to acknowledge the command has been received.

{topic: UnloadProject,type: Response}

Example Request

{topic: UnloadProject}

Example YAML Responses

{topic: UnloadProject,type: Response}

Example CSV Responses

UnloadProject,0

SetDefaultProject

Structure

{topic: SetDefaultProject,data: {project_name: <value>}}

Argument Description

project_name: This indicates which project will be made the default project. if the project name is not specified, the default project is cleared.

Function Description

This command is used to enable and set which project is the Default project that will automatically be loaded when a RapidPlan controller powers on or is otherwise not in Operation Mode.
Once this behavior was enabled, it has to explicitly be disabled for it to not function.

Response Details

This command will return an acknowledgement with a status code indicating the command was received and executed.

  • Responses

    • Success

    • Improper number of arguments

    • Improper argument format

    • Project not found

Example Request

{topic: SetDefaultProject,data: {project_name: DemoProject}} {topic: SetDefaultProject,data: {project_name: }}

Example Responses

{topic: SetDefaultProject,type: Response}

 

EnterOperationMode

Structure

{topic: EnterOperationMode}

Argument Description

None

Function Description

This command indicates that the project is ready to begin operation. This call is blocking, until all active robots have been connected. Once all participating robots have indicated readiness, return messages will be sent, and subsequent Move calls will be accepted. Move calls received previously will be ignored.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: EnterOperationMode}

Example YAML Responses

{topic: EnterOperationMode,type: Response}

Example CSV Responses

EnterOperationMode,0

EnterConfigurationMode

Structure

{topic: EnterConfigurationMode}

Argument Description

None

Function Description

This command brings the Realtime Controller out of operation mode back into Config Mode. Current motions will be cancelled, and no new motion requests will be accepted. Duplicate calls have no effect. Connection to robot controllers will be maintained when returning to CONFIG mode.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: EnterConfigurationMode}

Example YAML Responses

{topic: EnterConfigurationMode,type: Response}

Example CSV Responses

EnterConfigurationMode,0

Shutdown

Structure

{topic: Shutdown}

Argument Description

None

Function Description

This command issues an asynchronous system call, systemctl poweroff -i, which shuts the appliance down, if in Fault or Configuration Mode.
Should the appliance be in operation or in calibration mode, this command will be rejected.

Between this call and the system shutting down, the appliance will be in a “Shutdown” state and refuse any further ASCII commands.
If this system call results in an error, rather than shutting down the following will occur:

  • An additional delayed response will be returned, with the command and error status

  • The controller will enter “Fault”.

Response Details

This command will return a response to acknowledge the command has been received and queued for execution.

Delayed Response Details

If the shutdown command fails during execution, a delayed response will be sent with the command’s error status.

Example Request

{topic: Shutdown}

Example YAML Responses

{topic: Shutdown,type: Response,data: {seq: 162}} And if the shutdown fails... {topic: Shutdown,type: DelayedResponse,error: {code:1001,RTR_SERVER_ERROR}}

Example CSV Responses

Shutdown,0,162 And if the shutdown fails... ShutdownResult,1001,162

UserLog

Structure

{topic: UserLog,data: {message: <value>}}

Argument Description

message: A string to be written to the RapidPlan logs. Must be less than 500 characters and may only contain letters, numbers, - and ..

Function Description

This function allows the user to write a simple string to the RapidPlan logs.

Response Details

This command will return immediately with a response indicating whether or not the string could be written to the log.

Example Request

{topic: UserLog,data: {message: CYCLE_START}}

Example YAML Responses

{topic: UserLog,type: Response

Example CSV Responses

UserLog,0

BeginInterlockRecording

Structure

{topic: BeginInterlockRecording}

Argument Description

None

Function Description

This command indicates to RTR that for the upcoming cycle, RTR should record motion data for interlock calculations. This command is only accepted in CONFIG mode. To generate an interlock report, issue BeginInerlockRecording, execute all the robot motions, call EnterConfigMode, and then call GenerateInterlockData to retrieve the result.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: BeginInterlockRecording}

Example YAML Responses

{topic: BeginInterlockRecording,type: Response}

Example CSV Responses

BeginInterlockRecording,0

GenerateInterlockData

Structure

{topic: GenerateInterlockData}

Argument Description

None

Function Description

This command indicates to RTR to that the simulation tool wishes to retrieve the interlock data for the preceding cycle. This command is only accepted in CONFIG mode.

Response Details

The response is a report of interlock data for each edge taken by a robot while interlock recording was active in YAML format. The report contains keys for each robot, and for each robot there is a key for every motion it takes.

  • Each motion taken by the robot is represented as a sequence_number

  • For each sequence_number, a path is provided which contains a list of waypoints.

    • The first waypoint is always the starting position of the robot during the move.

    • The last waypoint is always the position the robot when the move finishes.

  • For each sequence_number an interlock list is provided.

    • Each interlock is given a unique name.

    • An empty list indicates that no interlocks are required for that motion.

    • The begin_interlock key indicates the furthest point the robot can proceed to before it is required to obtain the specific interlock.

    • The end_interlock key indicates which point the robot must reach in order to release the interlock.

    • It is possible for the end_interlock key to be achieved through a different move.

    • Sometimes, the interlocks starting position is the first waypoint of the move which means the robot cannot move at all until the interlock is obtained.

    • Interlocks are not robot specific, so the same interlock can appear for multiple robots motions.

    • A null value for end_interlock indicates that the robot was still in a position that required an interlock when the recording was terminated.

Example Request

{topic: GenerateInterlockData}

Example YAML Response

For each robot, the information of the robot motion and interlock is returned.

{ topic: GenerateInterlockData, type: Response, data: { rtr_interlock_report: { version: 0.0.1, robots: { Robot1: [ {sequence_number: 1, path: [[0, 0, 0, 0, 0, 0], [0.866353, 0.676527, 0.235204, 1.375235, -0.889543, -1.26606]], interlocks: [{interlock_id: 0, begin_interlock: {sequence_number: 1, waypoint_index: 0}, end_interlock: "null"}, {interlock_id: 1, begin_interlock: {sequence_number: 1, waypoint_index: 0}, end_interlock: "null"}]}, {sequence_number: 4, path: [[0.866353, 0.676527, 0.235204, 1.375235, -0.889543, -1.26606], [0, 0, 0, 0, 0, 0]], interlocks: [{interlock_id: 2, begin_interlock: {sequence_number: 4, waypoint_index: 0}, end_interlock: "null"}, {interlock_id: 3, begin_interlock: {sequence_number: 4, waypoint_index: 0}, end_interlock: "null"}]}], Robot2: [ {sequence_number: 3, path: [[0, 0, 0, 0, 0, 0], [-0.790681, 0.486338, 0.122411, 1.691136, 0.798099, -1.742254]], interlocks: [{interlock_id: 0, begin_interlock: {sequence_number: 3, waypoint_index: 0}, end_interlock: "null"}, {interlock_id: 2, begin_interlock: {sequence_number: 3, waypoint_index: 0}, end_interlock: "null"}]}, {sequence_number: 5, path: [[-0.790681, 0.486338, 0.122411, 1.691136, 0.798099, -1.742254], [0, 0, 0, 0, 0, 0]], interlocks: [{interlock_id: 1, begin_interlock: {sequence_number: 5, waypoint_index: 0}, end_interlock: "null"}, {interlock_id: 3, begin_interlock: {sequence_number: 5, waypoint_index: 0}, end_interlock: "null"}]}] } } } }

 

Example CSV Response

None, only the YAML response type is supported for interlock generation.

API Endpoints - Robot

ActivateRobots

Structure

{topic: ActivateRobots,data: {robot_names: <value>}}

Argument Description

robot_names: optional An array specifying which robots should be activated. If not passed, all inactive robots in the project will be activated.

Function Description

This command will re-activate a robot for the loaded project. After this command, when Connect is called, the activated robot will be connected to, and when in OPERATION mode this robot will be controlled by RTR.

This command must be called when a project is loaded and the controller is in CONFIG mode.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: ActivateRobots}

Example YAML Response

{topic: ActivateRobots,type: Response}

Example CSV Response

ActivateRobots,0

DeactivateRobot

Structure

{topic: DeactivateRobot,data: {robot_name: <value>, treat_as_obstacle: <value>,joint_config: <value>,target_name: <value>,preset_name: <value>}}

Argument Description

robot_name: Specifies which robot should be deactivated.

treat_as_obstacle: optional A boolean value that specifies if the deactivated robot should be treated for collisions by the other robots in the work cell. Default value is true.

preset_name: optional A string specifying the preset of the robot to be used in the inactive state. The preset will determine the collision geometry as well as the number of joints. If not specified, the active preset will be used.

 

If treat_as_obstacle is enabled, then the following keys are mutually exclusive to specify the behavior of the deactivated robot:

joint_config: optional An array of floats specifying the angle for each joint of the robot. If the robot’s preset includes user defined joints, they must be provided as well, sorted by the driver index.

target_name: optional A string specifying the name of the target that the robot will be positioned at.

use_last_known_config: optional Default option. A boolean flag that specifies the last known joint configuration of the robot should be used. A robot must have been Connected at least once for there to be known joint angles. These values are saved to disk, so on project reload, this option can still be used.

If none of the optional keys is set, the last configured setting will be used. If the robot has never been deactivated then the use_last_known_config behavior is active. Setting target_name or joint_config does not clear the last known configuration.

Function Description

This command ‘deactivates’ a robot which means the RTR controller will ignore it when connecting to the robots within a project. Subsequent Connect commands will only connect to activated robots, and when in Operation mode, only the activated robots will be controlled by RTR. In order to prevent collisions, the deactivated robots can be configured for collision checking by setting the appropriate preset and joint angles. Optionally, the robot can be ignored during collision checking if it is not present in the workcell.

This command must be called when a project is loaded and the controller is in CONFIG mode.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: DeactivateRobot} {topic: DeactivateRobot, data: {preset_name: gripper_open, treat_as_obstacle: true, use_last_known_config: true}}

Example YAML Response

{topic: DeactivateRobot,type: Response}

Example CSV Response

DeactivateRobot,0

UpdateInactiveRobotSettings

Structure

{topic: UpdateInactiveRobotSettings,data: {robot_name: <value>,treat_as_obstacle: <value>,preset: <value>,joint_config: <value>,target_name: <value>,use_last_known_config: <value>}}

Argument Description

robot_name: Specifies which robot should have it’s settings updated while in the deactivated state.

treat_as_obstacle: A boolean value that specifies if the deactivated robot should be treated for collisions by the other robots in the work cell.

preset_name: A string specifying the preset of the robot to be used in the inactive state. The preset will determine the collision geometry as well as the number of joints.

 

If treat_as_obstacle is enabled, then the following keys are mutually exclusive to specify the behavior of the deactivated robot:

joint_config: An array of floats specifying the angle for each joint of the robot. If the robot’s preset includes user defined joints, they must be provided as well, sorted by the driver index.

target_name: A string specifying the name of the target that the robot will be positioned at.

use_last_known_config: A boolean flag that specifies the last known joint configuration of the robot should be used. A robot must have been Connected at least once for there to be known joint angles. These values are saved to disk, so on project reload, this option can still be used.

Function Description

This command updates the settings used for collision checking against a deactivated robot. If the settings were not specified in DeactivateRobot or if they have changed, this command can be used to specify them.

This command must be called when a project is loaded and the controller is in CONFIG mode.

Response Details

This command will return a response to acknowledge the command has been received and executed successfully.

Example Request

{topic: UpdateInactiveRobotSettings,data: {robot_name: Robot1, preset_name: gripper_open, treat_as_obstacle: true, joint_config: [0.0,0.0,90.0,0.0,90.0,0.0]}} {topic: UpdateInactiveRobotSettings,data: {robot_name: Robot1, preset_name: gripper_open, treat_as_obstacle: true, use_last_known_config: true}} {topic: UpdateInactiveRobotSettings,data: {robot_name: Robot1, preset_name: gripper_open, treat_as_obstacle: true, target_name: staging}}