2.2 Realtime Robotics RapidPlan ASCII API
- 1 Revisions
- 2 Goal
- 3 API Format
- 3.1 Syntax (Inline YAML 1.2 Spec)
- 3.2 Requests
- 3.2.1 Formation Rules
- 3.2.2 Boolean Values
- 3.3 Responses
- 3.4 Stateful Commands
- 3.5 Commands Stored on Disk
- 4 Default Units
- 5 Move Type and Target Type Support
- 6 API Endpoints - Project
- 6.1 SetResponseType
- 6.2 SetUnits
- 6.3 GetMode
- 6.4 ClearFaults
- 6.5 LoadProject
- 6.6 GetLoadedProject
- 6.7 UnloadProject
- 6.8 SetDefaultProject
- 6.9 EnterOperationMode
- 6.10 EnterConfigurationMode
- 6.11 Shutdown
- 6.12 UserLog
- 6.13 BeginInterlockRecording
- 6.14 GenerateInterlockData
- 7 API Endpoints - Robot
- 7.1 ActivateRobots
- 7.2 DeactivateRobot
- 7.3 UpdateInactiveRobotSettings
- 7.4 Connect
- 7.5 Disconnect
- 7.6 AcquireControl
- 7.7 ReleaseControl
- 7.8 SetMaxLinearAcceleration
- 7.9 SetMaxLinearSpeed
- 7.10 SetAlternateLocation
- 7.11 SetInterruptBehavior
- 7.12 SetRobotPreset
- 7.13 GetRobotPresets
- 7.14 Queueing Moves
- 7.15 Move
- 7.16 CombinedMove
- 7.17 CancelMove
- 7.18 CreateTarget
- 7.19 UpdateTarget
- 7.20 RenameTarget
- 7.21 RemoveTarget
- 7.22 AddConnection
- 7.23 RemoveConnection
- 7.24 GetJointConfiguration
- 7.25 GetTCPPose
- 8 API Endpoints - Scene Modeling
- 8.1 SetObjectState
- 8.2 AddFrame
- 8.3 UpdateFrame
- 8.4 RemoveFrames
- 8.5 AddBox
- 8.6 AddObject
- 8.7 RemoveBoxes
- 8.8 RemoveObjects
- 8.9 Reparent
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 aMove
orLoadProject
. When aResponse
includes aseq
key, that indicates that aDelayedResponse
will be returned for that command. Both the immediate and delayed responses will have a globally unique sequence number (referred to asseq
) 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 aCombinedMove
command returns aFeedback
response to indicate it’s completion before theCombinedMove
completes and returns it’sDelayedResponse
.
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
: 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 |
---|---|---|---|
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 |
---|---|---|---|
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 | |
---|---|
Argument Description |
|
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 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 | |
Example YAML Responses | |
Example CSV Responses |
SetUnits
Structure | |
---|---|
Argument Description |
|
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 If the 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 | |
Example YAML Responses | |
Example CSV Responses |
GetMode
Structure | |
---|---|
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 | |
Example YAML Responses | |
Example CSV Responses |
ClearFaults
Structure | |
---|---|
Argument Description |
|
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 | |
Example YAML Responses | |
Example CSV Responses |
LoadProject
Structure | |
---|---|
Argument Description |
|
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. |
Delayed Response Details | Once the load is completed, the system will send a delayed response to indicate the project has finished loading. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
GetLoadedProject
Structure | |
---|---|
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 |
Response Details | This command will return a response code, followed by the currently loaded project or appropriate error code. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
UnloadProject
Structure | |
---|---|
Argument Description |
|
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. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
SetDefaultProject
Structure | |
---|---|
Argument Description |
|
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. |
Response Details | This command will return an acknowledgement with a status code indicating the command was received and executed.
|
Example Request | |
Example Responses |
EnterOperationMode
Structure | |
---|---|
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 | |
Example YAML Responses | |
Example CSV Responses |
EnterConfigurationMode
Structure | |
---|---|
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 |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
Shutdown
Structure | |
---|---|
Argument Description | None |
Function Description | This command issues an asynchronous system call, Between this call and the system shutting down, the appliance will be in a “Shutdown” state and refuse any further ASCII commands.
|
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 | |
Example YAML Responses | |
Example CSV Responses |
UserLog
Structure | |
---|---|
Argument Description |
|
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 | |
Example YAML Responses | |
Example CSV Responses |
BeginInterlockRecording
Structure | |
---|---|
Argument Description |
|
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 |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
GenerateInterlockData
Structure | |
---|---|
Argument Description |
|
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 |
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.
|
Example Request | |
Example YAML Response | For each robot, the information of the robot motion and interlock is returned.
|
Example CSV Response |
|
API Endpoints - Robot
ActivateRobots
Structure | |
---|---|
Argument Description |
|
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 | |
Example YAML Response | |
Example CSV Response |
DeactivateRobot
Structure | |
---|---|
Argument Description |
If
If none of the optional keys is set, the last configured setting will be used. If the robot has never been deactivated then the |
Function Description | This command ‘deactivates’ a robot which means the RTR controller will ignore it when connecting to the robots within a project. Subsequent 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 | |
Example YAML Response | |
Example CSV Response |
UpdateInactiveRobotSettings
Structure | |
---|---|
Argument Description |
If
|
Function Description | This command updates the settings used for collision checking against a deactivated robot. If the settings were not specified in 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 | |
Example YAML Response | |
Example CSV Response |
Connect
Structure | |
---|---|
Argument Description |
|
Function Description | This command connects to all active robots in the loaded project, or optionally a single robot. After this command executes, the Realtime Controller will begin monitoring the position of the robot/s. This command should normally be called near the beginning of a robot program, before attempting to make any Move commands. If the robot/s have already been connected, this command will return successfully. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
Disconnect
Structure | |
---|---|
Argument Description |
|
Function Description | This command disconnects from all robots in the project (unless a robot is specified) and returns them to the |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
AcquireControl
Structure | |
---|---|
Argument Description |
|
Function Description | This command allows the user to signal that they are done with an operation that required RTR to release external control of the robot, and the Realtime Controller should resume control, with the last active robot preset or a specified preset. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
ReleaseControl
Structure | |
---|---|
Argument Description |
|
Function Description | This command is intended to enable the user to take temporary control of the robot to get/set IOs, or execute a portion of their robot program that is not suitable for RTR control at this point. This may be gluing, welding, or some other time-dependent, sensitive process. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
SetMaxLinearAcceleration
Structure | |
---|---|
Argument Description |
|
Function Description | This command limits the linear acceleration of a robots TCP. A user can specify the max acceleration allowed for a robot using this command, or reset to the default value using the |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
SetMaxLinearSpeed
Structure | |
---|---|
Argument Description |
|
Function Description | This command limits the max linear speed of a specified robot. In following move commands, the speed parameter will move the robot at a percent of this specified speed. For example, if this command is called and A user can specify the max linear speed allowed for a robot using this command, or reset to the default value using the This command can only be sent when the specified robot is stationary, and all subsequent motions will adhere to the provided limit. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
SetAlternateLocation
Structure | |
---|---|
Argument Description |
|
Function Description | This command is used to enable and set the alternate location for a robot. With this feature enabled, in the event a Move command fails or is interrupted, the Realtime Controller will not return a response code immediately, and will instead automatically plan to the specified alternate position. Depending on the behavior of complete move the Realtime Controller will either return a response code indicating the robot reached the alternate location, or continue to plan to the location that was first specified in the move command. Only one target can be set as the alternate location, so if that target does not exist in all of the robots presets, when a preset it changed, the alternate location should be updated. Enabling the alternate location behavior changes the way a robot will execute a move, therefore a When this behavior is enabled, the robot will execute motions using the same parameters as the original move. For example, if a move is sent using When partial execution is enabled ( |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
SetInterruptBehavior
Structure | |
---|---|
Argument Description |
|
Function Description | This function should be invoked towards the beginning of a robot program. It sets the behavior for the server with respect to replanning and timeout behavior. If this function is not called, the default behavior for a project will be: |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
SetRobotPreset
Structure | |
---|---|
Argument Description |
|
Function Description | This command changes the active robot preset for a specific robot. When a preset is changed, current robot motions are not re-validated, but new move commands will respect the new active preset. A robot must be stationary in order to call this command explicitly. SetRobotPreset commands will be rejected if sent between a user issuing move request to the RTR controller, and the final response being sent from the RTR controller to the user for a given bot . If a preset change is needed, it can be accomplished using the preset_name key within a queued move or combined move request. In the case of switching presets using the preset_name key, there is a requirement that changes in preset during queued moves or CombinedMoves must not change the TCP or the controllable axes. This requirement is in effect if there are any current motions that the user has issued to RTR, that RTR has not yet returned the final API response to the user. If the new preset has a different number of controlled axes than the current preset, ReleaseControl must be called for that robot prior to the SetRobotPreset command. Once the preset change has succeeded, AcquireControl can be called again. When called, the selected preset is stored to disk so upon project reload, the last active preset will be used. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
GetRobotPresets
Structure | |
---|---|
Argument Description |
|
Function Description | This command will return a response with a comma separated array of the robot preset names ( |
Response Details |
For CSV responses, after the acknowledgement codes, i.e., |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
Queueing Moves
Move commands can be sent to a robot before it's current motion has finished. The new Move
request will be added to the queue for the specified robot to be executed as soon as it’s current motion finishes.
Only
Direct
andRoadmap
move types can be added to the queue.A maximum of 100 moves can be added to the queue.
If received in time, the robot will smooth it's current motion into the next in the queue using it's smoothing argument.
The move queue for a given robot is cleared when:
A Move fails
A Move is cancelled
While a robot is executing a motion, the next move in the queue is planned
A robot reserves the swept volume of it’s current motion and the next move in the queue.
A Move is only added to the queue, if a path could be found.
Initial responses will be sent for move requests when planning has finished.
Delayed responses will be sent when queued move segments terminate (due to completion, cancelling, or interruption).
Canceling a robot’s motion with
CancelMove
will clear the move queue and cancel all moves simultaneously. The delayed responses of these moves are not guaranteed to be in queue order.Queued motions will use the interrupt settings when planning in the background.
Queued motions will use the alternate location, if enabled.
A robot’s preset can be changed when Moves are queued. The number of controlled axes shall stay the same. The robot TCP could change when a robot’s preset switches in the queue.
It is highly recommended to include
preset_name
in every queued Move command in case a robot’s preset switches in the queue.Smoothing is supported in queue moves. If the new motion is received in time, the robot will use the current motions smoothing value to blend into the new motion.
Move
Structure | |
---|---|
Argument Description |
If a robot's external axes remain fixed during a move, or switch to different setpoint values defined by a target,
|
Function Description | Formerly there were blind moves, MoveToXXX, and OffroadtoXXX commands. We would end up with a minimum of 9 different move commands based on if you wanted to move to a target, coordinate (pose) or a joint configuration. With this new generic Caution: There are risks involved with mixing RTR moves with non -RTR moves(for example, native moves from a robot teach pendant program). The user must make sure that a RTR Caution: There are collision risks involved with stopping a robot from a robot teach pendant program when multi-robot moves are controlled by a RapidPlan controller. The user must make sure that all RTR Caution: When a roadmap move is issued, how far the robot can be away from the roadmap is defined as the distance tolerance to the roadmap node,
|
Response Details | When a Move request is received, path planning occurs before a response is sent. If a path is found, this command will return a response code to acknowledge the command has been received, the name of the robot that this move is for, and a unique sequence ID for this specific move. If planning fails, an appropriate error code will be returned, and no delayed response will be sent. |
Delayed Response Details | If a path was found, the system will send a or, for a |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
CombinedMove
Structure | |
---|---|
Argument Description |
|
Function Description |
The smoothing argument of each individual move command will specify if it will blend into the next move in the list, and at what distance from the end of the current move. In the event a If move queuing is being used, a |
Response Details | This command will return an initial response to indicate that the command has been processed and a collision free path has been found for all moves, smoothing included. A unique sequence number will be included to identify the |
Delayed Response Details | For every If a trigger output is specified for a move segment, a feedback message will be sent as soon as the trigger output is activated to on or off. Different segments of the same |
Example Request | Note: the new line (\n) and tab (\t) characters have been added for readability, the actual request format does not include them. |
Example YAML Responses | |
Example CSV Responses |
CancelMove
Structure | |
---|---|
Argument Description |
|
Function Description | This function tells the Realtime Controller to abort planning and motion for the specified robot. After calling this, a robot may be left in an off roadmap location and will require a planning move command. If a series of If If a move is canceled mid-motion after a The ramp-down speed of |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
CreateTarget
Structure | |
---|---|
Argument Description |
|
Function Description | This command creates a target in the active robot preset for the specified robot. The target is created using the robot’s current joint angles. To ensure consistent joint angle readings, the robot must stay stationary while the target is created. Therefore, the controller must be in No connections will be created automatically for the new target. |
Response Details | This command will return an acknowledgement with a status code indicating the command was received and executed. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
UpdateTarget
Structure | |
---|---|
Argument Description |
|
Function Description | This command updates the specified targets position to be at the specified robots TCP location in it’s current preset. The target’s new position will be used for all assigned robots. A target’s position will only be updated, if all of it’s connections remain valid, otherwise the command fails and returns an error code Only one target can be updated at a time. While a target is updating, any subsequent UpdateTarget commands will be rejected. With the |
Response Details | This command will return an acknowledgement with a status code indicating the command was received and is being executed. |
Delayed Response Details | This command will also return a delayed response when the update has completed or failed. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
RenameTarget
Structure | |
---|---|
Argument Description |
|
Function Description | This command renames a target. To rename a target, the Realtime Controller must be in RapidPlan Create naming conventions must be followed. Duplicate names are not allowed. Any invalid names will be rejected by the command. |
Response Details | This command will return an acknowledgement with a status code indicating the command was received and executed. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
RemoveTarget
Structure | |
---|---|
Argument Description |
|
Function Description | This command removes a target in the active robot preset for the specified robot. To remove the target, Realtime Controller must be in Removing the target will remove any manually created connections , and any connections created by auto-connect, between this target and other targets. |
Response Details | This command will return an acknowledgement with a status code indicating the command was received and executed. |
Example Request | |
Example YAML Responses | |
Example CSV Responses |
AddConnection
Structure | |
---|---|
Argument Description |
|