Revisions
Revision history from 2.6 onwards
2023/07/14: (2.5) Added
validation
argument to UpdateTarget command2023/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
withconstraints
.2023/09/28: (2.5) Add documentation about yaml parsing per RAPID-38095
2023/11/14: (2.6) Added IsOnTarget command
2023/11/29: (2.6) Removed MultiRobotMove command
2023/11/29: (2.6) Added support for roadmap + planning moves to configs
2023/11/29: (2.6) Added Move command optional parameter
roadmap_mode
to define how the robot should use the roadmap + off-roadmap motions for roadmap moves to a pose or joint config2023/11/29: (2.6) Added new Move goal type
route
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 keymy_key
whose value ismy_value
{my_key:my_value}
will parse as an object with a keymy_key:value
whose value isnull
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: <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:
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 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 its completion before theCombinedMove
completes and returns itsDelayedResponse
.
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 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:
| direct | roadmap | planning |
---|---|---|---|
target | >=2.2 | >=2.0 | >=2.0 |
config | >=2.3 | >=2.3 | 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 | N/A* | N/A* | N/A* |
pose | >=2.2 | >=2.2 | >=2.2 |
*In Rapidplan Create, targets and robot configurations are defined by full joint configuration of the robot, including external axes values.
API Endpoints - Project
SetResponseType
Structure | {topic: SetResponseType,data: {response_type: <value>, set_ip_default: <value>}} |
---|---|
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 | {topic: SetResponseType,data: {response_type: csv}} |
Example YAML Responses | {topic: SetResponseType,type: Response} |
Example CSV Responses | SetResponseType,0 |
GetUnits
Structure | {topic: GetUnits} |
---|---|
Argument Description |
|
Function Description |
|
Response Details | This command will return a response to show the units used by the loaded project. |
Example Request | {topic: GetUnits} |
Example YAML Responses | {topic: GetUnits, data: {length: inches, angle: degrees}} |
Example CSV Responses | GetUnits,0,inches,degrees |
SetUnits
Structure | {topic: SetUnits,data: {length: <value>,angle: <value>, set_ip_default: <value>}} |
---|---|
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 | {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. The states of the system are: Config mode, Operation mode, Calibration mode and Fault mode. |
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, data: {reset_connection: <value>}} |
---|---|
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 due to an E-stop, 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 programmatically, and transition the Controller back into Config mode if possible. It will fail if there are still active, unresolvable faults. If |
Response Details | This command will return a single response code as a result value. |
Example Request | {topic: ClearFaults} |
Example Responses | {topic: ClearFaults,type: Response} {topic: ClearFaults,type: Response,error: {code:1004,msg:FAILED_TO_CLEAR_FAULTS}} |
LoadProject
Structure | {topic: LoadProject,data: {project_name: <value>, upgrade: <value>}} |
---|---|
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. {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 |
Response Details | This command will return a response code, followed by the currently loaded project or an 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 |
|
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 |
|
Function Description | This command is used to define which project is the Default project that will automatically be loaded when RapidPlan powers on or is otherwise not in Operation Mode. Sending a SetDefaultProject command without specifying the |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: SetDefaultProject,data: {project_name: DemoProject}} or {topic: SetDefaultProject} |
Example YAML Responses | {topic: SetDefaultProject,type: Response} |
Example CSV Responses | SetDefaultProject,0 |
EnterOperationMode
Structure | {topic: EnterOperationMode, data:{connect: true}} |
---|---|
Argument Description |
|
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. |
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 |
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, 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 | {topic: Shutdown} |
Example YAML Responses | {topic: Shutdown,type: Response,data: {seq: 162}} And if the shutdown fails... {topic: Shutdown,type: DelayedResponse,error: {code: 2019,INVALID_SHUTDOWN_STATE}} or {topic: Shutdown,type: DelayedResponse,error: {code: 2020,APPLIANCE_SHUTDOWN_FAILED}} |
Example CSV Responses | Shutdown,0,162 And if the shutdown fails... ShutdownResult,1001,162 |
UserLog
Structure | {topic: UserLog,data: {message: <value>}} |
---|---|
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 | {topic: UserLog,data: {message: CYCLE_START}} |
Example YAML Responses | {topic: UserLog,type: Response |
Example CSV Responses | UserLog,0 |
BeginInterlockRecording
Structure | {topic: BeginInterlockRecording} |
---|---|
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 | {topic: BeginInterlockRecording} |
Example YAML Responses | {topic: BeginInterlockRecording,type: Response} |
Example CSV Responses | BeginInterlockRecording,0 |
GenerateInterlockData
Structure | {topic: GenerateInterlockData} |
---|---|
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 | {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 |
|
API Endpoints - Robot
ActivateRobots
Structure | {topic: ActivateRobots,data: {robot_names: <value>, project_name: <value>}} |
---|---|
Argument Description |
|
Function Description | This command will re-activate a robot. 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. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: ActivateRobots} {topic: ActivateRobots, data: {project_name: Proj1, robot_names: [Robot2]}} |
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 |
|
Function Description | This command ‘deactivates’ a robot which means the RTR controller will ignore it when connecting to the robots within a project. Subsequent |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: DeactivateRobot, data: {robot_name: Robot2}} {topic: DeactivateRobot, data: {robot_name: Robot2, preset_name: gripper_open, treat_as_obstacle: true, use_last_known_config: true}} {topic: DeactivateRobot, data: {robot_name: Robot2, project_name: Project1}} |
Example YAML Response | {topic: DeactivateRobot,type: Response} |
Example CSV Response | DeactivateRobot,0 |
Connect
Structure | {topic: Connect,data: {robot_name: <value>}} |
---|---|
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 | {topic: Connect} |
Example YAML Responses | {topic: Connect,type: Response} |
Example CSV Responses | Connect,0 |
Disconnect
Structure | {topic: Disconnect,data: {robot_name: <value>}} |
---|---|
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 | {topic: Disconnect} |
Example YAML Responses | {topic: Disconnect,type: Response} |
Example CSV Responses | Disconnect,0 |
AcquireControl
Structure | {topic: AcquireControl,data: {robot_name: <value>,preset_name: <value>}} |
---|---|
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 | {topic: AcquireControl,data: {robot_name: robot_1}} |
Example YAML Responses | {topic: AcquireControl,type: Response} |
Example CSV Responses | AcquireControl,0 |
ReleaseControl
Structure | {topic: ReleaseControl,data: {robot_name: <value>,preset_name: <value>}} |
---|---|
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 | {topic: ReleaseControl,data: {robot_name: robot_1}} |
Example YAML Responses | {topic: ReleaseControl,type: Response} |
Example CSV Responses | ReleaseControl,0 |
SetMaxLinearAcceleration
ℹ️ Note: This command will apply to both activated and deactivated robots. If sent to a deactivated robot, the settings will apply when reactivating the robot.
Structure | {topic: SetMaxLinearAcceleration,data: {robot_name: <value>,max_accel: <value>}} {topic: SetMaxLinearAcceleration,data: {robot_name: <value>,reset: <value>}} |
---|---|
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 | {topic: SetMaxLinearAcceleration,data: {robot_name: robot_1,max_accel: 10000}} {topic: SetMaxLinearAcceleration,data: {robot_name: robot_1,reset: True}} |
Example YAML Responses | {topic: SetMaxLinearAcceleration,type: Response} |
Example CSV Responses | SetMaxLinearAcceleration,0 |
SetMaxLinearSpeed
ℹ️ Note: This command will apply to both activated and deactivated robots. If sent to a deactivated robot, the settings will apply when reactivating the robot.
Structure | {topic: SetMaxLinearSpeed,data: {robot_name: <value>,max_speed: <value>}} {topic: SetMaxLinearSpeed,data: {robot_name: <value>,reset: <value>}} |
---|---|
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 | {topic: SetMaxLinearSpeed,data: {robot_name: robot_1,max_speed: 500}} |
Example YAML Responses | {topic: SetMaxLinearSpeed,type: Response} |
Example CSV Responses | SetMaxLinearSpeed,0 |
SetAlternateLocation
ℹ️ Note: This command will apply to both activated and deactivated robots. If sent to a deactivated robot, the settings will apply when reactivating the robot.
Structure | {topic: SetAlternateLocation,data: {robot_name: <value>,enabled: <value>,target_name: <value>,complete_move: <value>, timeout: <value>}} |
---|---|
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 Error code indicating the robot reached the alternate location, or continue to plan to the location that was first specified in the move command. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | // To enable an alternate position for the robot to move to in the event the original move fails {topic: SetAlternateLocation,data: {robot_name: robot_1,enabled: 1,target_name: pounce, complete_move: 1}} // To enable the partial move behavior where a robot will move as far as it can and then wait until the path is free {topic: SetAlternateLocation,data: {robot_name: robot_1,enabled: 1,mode: 1}} // To enable multi robot move behavior {topic: SetAlternateLocation, data: {robot_name: robot_1,enabled: 1,mode: multirobot}} // To disable any alternate location behavior {topic: SetAlternateLocation,data: {robot_name: robot_1,enabled: 0}} |
Example Responses | {topic: SetAlternateLocation,type: Response} |
Example CSV Responses | SetAlternateLocation,0 |
SetInterruptBehavior
ℹ️ Note: This command will apply to both activated and deactivated robots. If sent to a deactivated robot, the settings will apply when reactivating the robot.
Structure | {topic: SetInterruptBehavior,data: {robot_name: <value>, timeout: <value>, max_replans: <value>} |
---|---|
Argument Description |
|
Function Description | This function should be invoked towards the beginning of a robot program. It sets the behavior for the robot with respect to replanning and timeout behavior. This function must be called when a project is already loaded. 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 | {topic: SetInterruptBehavior,data: {robot_name: robot_1,timeout: 5}} |
Example YAML Responses | {topic: SetInterruptBehavior,type: Response} |
Example CSV Responses | SetInterruptBehavior,0 |
SetRobotPreset
Structure | {topic: SetRobotPreset,data: {robot_name: <value>,preset_name: <value>}} |
---|---|
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 | {topic: SetRobotPreset,data: {robot_name: robot_1,preset_name: open_gripper}} |
Example YAML Responses | {topic: SetRobotPreset,type: Response} |
Example CSV Responses | SetRobotPreset,0 |
GetRobotPresets
Structure | {topic: GetRobotPresets, data: {robot_name: <value>}} |
---|---|
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 | {topic: GetRobotPresetsdata: {robot_name: Robot1} |
Example YAML Responses | {topic: GetRobotPresets,type: Response,data: {active_preset: preset1, robot_presets:[preset1, preset2]}} |
Example CSV Responses | GetRobotPresets,0, preset1, 2, preset1, preset2 |
Queueing Moves
Move commands can be sent to a robot before its current motion has finished. The new Move
request will be added to the queue for the specified robot to be executed as soon as its 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 its current motion into the next in the queue using its 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 its 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 queued 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 | {topic: Move,data: {robot_name: <value>,goal: <values>,speed: <value>,move_type: <value>,smoothing: <value>,interp: <value>,collision_check: <value>,collision_check_dsm: <value>,timeout: <value>,relative: <value>,ref_frame: <value>,preset_name: <value>, trigger: {name: <value>, output: <value>, time: <value>}, external_axes: {<axis name 1>: active, <axis name 2>: <value>}, costs: {external_axis: <value>, path_length: <value>, via_points: <value>}} |
---|---|
Argument Description |
A
If a robot's external axes remain fixed during a move, or switch to different setpoint values defined by a target,
Robot pose value plus
|
Function Description | With this new generic A A A |
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. {topic: Move,type: Response,data: {robot_name: <value>,seq: <value>}} |
Delayed Response Details | If a path was found, the system will send a {topic: Move,type: DelayedResponse,data: {robot_name: <value>,seq: <value>}} or, for a {topic: Move,type: Feedback, data: {robot_name: <value>,seq: <value>, trigger: {name: <value>, output: <value>}}} |
Example Request | {topic: Move,data: {robot_name: robot_1,move_type: roadmap,target: pre_pick,speed: 1.0,smoothing: 1, trigger: {name: output_1, output: 1, time: -0.5}}} |
Example YAML Responses | {topic: Move,type: Response,data: {robot_name: robot_1,seq: 312}} ... move executes ... {topic: Move, type: Feedback, data: {robot_name: robot_1, seq: 312, trigger: {name: output_1, output: 1}} ... 0.5s {topic: Move,type: DelayedResponse,data: {robot_name: robot_1, seq: 312}} |
Example CSV Responses | Move,0,robot_1,312 ... move executes ... MoveFeedback,0,robot_1,312,Output_1,1 ... 0.5s MoveResult,0,robot_1,312 |
CombinedMove
Structure | {topic: CombinedMove, data: {robot_name: <value>, preset_name: <value>, moves: [{move_type: <value>, goal: <value>, speed: <value> ...},{move_type: <value>, goal: <value>, speed: <value> ...}, ... ,{move_type: <value>, goal: <value>, speed: <value> ...},...]}} |
---|---|
Argument Description |
HoldMove is also able to be sent as a segment of a CombinedMove command. |
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 HoldMove is also able to be sent as a segment of a CombinedMove command to hold before executing a section of movement until a ResumeMove command has been sent. |
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 {topic: CombinedMove,type: Response,data: {robot_name: <value>, seq: <value>}} |
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 {topic: CombinedMove,type: Feedback,data: {robot_name: <value>, seq: <value>, index: <value>}} ... additional Move DelayedResults ... {topic: CombinedMove,type: DelayedResponse,data: {robot_name: <value>, seq: <value>}} |
Example Request | { topic: CombinedMove, data: { robot_name: robot_1, moves: [ {move_type: roadmap,target: staging,speed: 1.0,smoothing: 0.25, trigger: {name: output_1, output: 1, time: -0.5}}, {move_type: roadmap,target: pre_pick,speed: 1.0,smoothing: 0.1, trigger: {name: output_1, output: 0, time: -0.5}}, {move_type: direct,pose: [0,0.5,0,0,180,0],speed: 1.0,smoothing: 0.0} ] } } Note: the new line (\n) and tab (\t) characters have been added for readability, the actual request format does not include them. CombinedMove (including a HoldMove segment): |
Example YAML Responses | {topic: CombinedMove, type: Response, data: {robot_name: robot_1, seq: 61}} {topic: CombinedMove, type: Feedback, data: {robot_name: robot_1, seq: 61, index: 0}} {topic: Move, type: Feedback, data: {robot_name: robot_1, seq: 61, trigger: {name: output_1, output: 1}} {topic: CombinedMove, type: Feedback, data: {robot_name: robot_1, seq: 61, index: 1}} {topic: Move, type: Feedback, data: {robot_name: robot_1, seq: 61, trigger: {name: output_1, output: 0}} {topic: CombinedMove, type: Feedback, data: {robot_name: robot_1, seq: 61, index: 2}} {topic: CombinedMove, type: DelayedResponse, data: {robot_name: robot_1, seq: 61}} |
Example CSV Responses | CombinedMove,0,Robot1,61 CombinedMoveFeedback,0,Robot1,61,0 CombinedMoveFeedback,0,robot_1,61,output_1,1 CombinedMoveFeedback,0,Robot1,61,1 CombinedMoveFeedback,0,robot_1,61,output_1,0 CombinedMoveFeedback,0,Robot1,61,2 CombinedMoveResult,0,Robot1,61 |
CancelMove
Structure | {topic: CancelMove,data: {robot_name: <value>, acceleration_factor: <value>}} |
---|---|
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 If a move is canceled mid-motion after a |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: CancelMove,data: {robot_name: robot_1, acceleration_factor: 0.9}} |
Example YAML Responses | {topic: CancelMove,type: Response} |
Example CSV Responses | CancelMove,0 |
HoldMove
Structure | {topic: HoldMove, data: { robot_name: <robot_name>}} |
---|---|
Argument Description |
|
Function Description | This command blocks a robot from executing pre-sent or combined moves for a defined robot until a ResumeMove command is sent. HoldMove is also able to be sent as a segment of a CombinedMove command. |
Response Details | A robot that is holding will return an error while holding. |
Example Request | HoldMove: CombinedMove (including a blocked segment): |
Example YAML Responses | HoldMove: |
Example CSV Responses | HoldMove: |
ResumeMove
Structure | {topic: ResumeMove, data: { robot_name: <robot_name>}} |
---|---|
Argument Description |
|
Function Description | ResumeMove: This command continues robot the through combined or pre-set moves for a defined robot. |
Response Details | |
Example Request | ResumeMove: |
Example YAML Responses | ResumeMove: |
Example CSV Responses | ResumeMove: |
GetTargets
Structure | {topic: GetTargets,data: {robot_name: <value>}} |
---|---|
Argument Description |
|
Function Description | This command retrieves the targets for a given robot in a specific preset in the loaded project. The default behavior is to return the targets in the active robot preset, but a different preset can be specified. |
Response Details | This command will return a response code, followed by a comma separated array of the target names. |
Example Request | {topic: GetTargets,data: {robot_name: robot_1}} |
Example YAML Responses | {topic: GetTargets,type: Response,data: {targets:[weld_1,weld_2,weld_3]}} |
Example CSV Responses | GetTargets,0,3,weld_1,weld_2,weld_3 |
CreateTarget
Structure | {topic: CreateTarget,data: {target_name: <value>,robot_name: <value>}} |
---|---|
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 | {topic: CreateTarget,data: {target_name: weld5,robot_name: robot_1}} |
Example YAML Responses | {topic: CreateTarget,type: Response} |
Example CSV Responses | CreateTarget,0 |
UpdateTarget
Structure | {topic: UpdateTarget,data: {target_name: <value>, robot_name: <value>, retrigger_autoconnect: <value>, object_states: <value>, pose: [x,y,z,rx,ry,rz]}} |
---|---|
Argument Description |
If
|
Function Description | This command updates the specified targets position to be at the specified robot TCP location in its current preset, or using an optional pose value. The target’s new position will be used for all assigned robots. A target’s position will only be updated, if all of its 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 | {topic: UpdateTarget,data: {target_name: weld5, robot_name: robot1}} |
Example YAML Responses | {topic: UpdateTarget,type: Response,data: {seq: 154}} After the target position has been updated and the roadmap has been regenerated... {topic: UpdateTarget,type: DelayedResponse,data: {seq: 154}} |
Example CSV Responses | UpdateTarget,0,154 After the target position has been updated and the roadmap has been regenerated... UpdateTargetResult,0,154 |
RenameTarget
Structure | {topic: RenameTarget,data: {target_name: <value>, new_target_name: <value>}} |
---|---|
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 | {topic: RenameTarget,data: {target_name: weld5, new_target_name: newweld6}} |
Example YAML Responses | {topic: RenameTarget,type: Response} |
Example CSV Responses | RenameTarget,0 |
RemoveTarget
Structure | {topic: RemoveTarget,data: {target_name: <value>}} |
---|---|
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 | {topic: RemoveTarget,data: {target_name: weld5}} |
Example YAML Responses | {topic: RemoveTarget,type: Response} |
Example CSV Responses | RemoveTarget,0 |
AddConnection
Structure | {topic: AddConnection,data: {robot_name: <value>, preset: <value>, targets: <value>, type: <value>, autoconnect_name: <value>, validation: <value>}} |
---|---|
Argument Description |
|
Function Description | This command creates new connections within a given roadmap. It can be used to create manual connections or auto-connects. |
Response Details | This command will return a response code. |
Delayed Response Details | This command will also return a delayed response only if |
Example Request | {topic: AddConnection,data: {robot_name: robot_1, presets: [preset_1], targets: [target_1, target_2], type: cartesian, validation: allow_invalid}} {topic: AddConnection,data: {robot_name: robot_1, presets: [preset_1], targets: [target_1, target_2], type: auto, autoconnect_name: autoconnect_1, validation: require_valid}} |
Example YAML Responses | {topic: AddConnection,type: Response,data: {seq: 154}} After the connection is created and the roadmap has been regenerated and validated... {topic: AddConnection,type: DelayedResponse,data: {seq: 154}} |
Example CSV Responses | AddConnection,0,154 After the connection is created and the roadmap has been regenerated and validated... AddConnectionResult,0,154 |
RemoveConnection
Structure | {topic: RemoveConnection,data: {autoconnect_name: <value>}} or {topic: RemoveConnection,data: {robot_name: <value>, preset: <value>, targets: <value>}} |
---|---|
Argument Description |
|
Function Description | This command removes connections in the roadmap. It can remove manual connections between two targets or an auto-connect by name. It can only be run in CONFIG mode. |
Response Details | This command will return a response code. |
Example Request | {topic: RemoveConnection,data: {autoconnect_name: autoconnect_1}} or {topic: RemoveConnection,data: {robot_name: robot_1, preset: preset_1, targets: [target_1, target_2]}} |
Example YAML Responses | {topic: RemoveConnection,type: Response} |
Example CSV Responses | RemoveConnection,0 |
GetJointConfiguration
Structure | {topic: GetJointConfiguration,data: {robot_name: <value>, native: false}} |
---|---|
Argument Description |
|
Function Description | This command retrieves the current joint angles of a specified robot. If the robot has additional axes, they will be included sorted by their driver index. The values will be returned in the client’s units for both revolute and prismatic joints. |
Response Details | This command will return a response code, followed by the current joint angles in a comma separated array. This command will always include the robot axes, and by default will include the position of external axes if present. |
Example Request | {topic: GetJointConfiguration,data: {robot_name: robot_1, with_joint_names: true}} |
Example YAML Responses | {topic: GetJointConfiguration,type: Response,data: {joint_configuration: [j1,j2,j3,j4,j5,j6...jN], joint_names: [<j1 name>,<j2 name>,<j3 name>,...<jN name>]}} |
Example CSV Responses | GetJointConfiguration,0,j1,j2,j3,j4,j5,j6...jN,joint1name,joint2name,...,jointNname |
GetTCPPose
Structure | {topic: GetTCPPose,data: {robot_name: <value>,ref_frame: <value>}} |
---|---|
Argument Description |
|
Function Description | This command returns the specified robot’s TCP coordinates in the world or user specified frame for the active robot preset. The coordinates are returned in the client’s unit and rotation convention. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully along with the position and rotation of the specified robot’s TCP. |
Example Request | {topic: GetTCPPose,data: {robot_name: robot_1}} |
Example YAML Responses | {topic: GetTCPPose,type: Response,data: {pose:[1.0,0.5,0.375,90.0,0.0,0.0]}} |
Example CSV Responses | GetTCPPose,0,1.0,0.5,0.375,90.0,0.0,0.0 |
IsOnTarget
Structure |
|
---|---|
Argument Description |
|
Function Description |
|
Response Details |
|
Example Request |
|
Example YAML Responses | {topic: IsOnTarget, type: Response, data: {on_target: true}} |
Example CSV Responses | IsOnTarget,0,false |
API Endpoints - Scene Modeling
In addition to Static Scene Model command SetObjectState, there are Dynamic Scene Model (DSM) commands that allow a user to add obstacles at runtime. A user may need DSM feature if the size or location of the obstacles is unknown offline, and therefore cannot be modeled. A user may also use the DSM object if the number of obstacle variations is unrealistic to model (e.g. in palletizing there may be thousands of obstacle sizes and possible object states).
Any possible DSM obstacle can be modeled with either a Box or CAD Object.
CAD objects must be configured in RapidPlan Create ahead of time to reference at runtime.
The DSM objects cannot be attached to stateful objects.
GetObjectStates
Structure | {topic: GetObjectStates, data: {object_name: <arg>}} |
---|---|
Argument Description |
|
Function Description | This command returns information about an object’s state for a loaded project. |
Response Details | This command will return a response with the object’s active state and a list of possible object states. |
Example Request | {topic: GetObjectStates, data: {object_name: object1}} |
Example YAML Responses | {topic: GetObjectStates,type: Response,data: {states: [state1, state2], active_state: state2}} |
Example CSV Responses | GetObjectStates,0,state2,2,state1,state2 |
GetStatefulObjects
Structure | {topic: GetStatefulObjects} |
---|---|
Argument Description | None. |
Function Description | This command retrieves the stateful object names for the loaded project. |
Response Details | This command will return a response code, followed by a comma separated array of the object names. |
Example Request | {topic: GetStatefulObjects} |
Example YAML Responses | {topic: GetStatefulObjects,type: Response,data: {objects:[Object_1,Object_2,Object_3]}} |
Example CSV Responses | GetStatefulObjects,0,3,Object_1,Object_2,Object_3 |
SetObjectState
Structure | {topic: SetObjectState,data: {object_name: <value>,state_name: <value>}} |
---|---|
Argument Description |
|
Function Description | This command changes the active state of a stateful mate. An object is specified as a function argument, and the direct parent’s mate state will be set based on the specified When called, the selected object state is stored to disk so upon project reload, the last active state will be used. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: SetObjectState,data: {object_name: jig,state_name: open}} |
Example YAML Responses | {topic: SetObjectState,type: Response} |
Example CSV Responses | SetObjectState,0 |
GetFrames
Structure | {topic: GetFrames} |
---|---|
Function Description | This command retrieves the frames added in RPC and the frames added by DSM commands for a loaded project that can be used as reference frames in |
Response Details | This command will return a response code, followed by a comma separated array of the frame names. |
Example Request | {topic: GetFrames} |
Example YAML Responses | {topic: GetFrames,type: Response,data: {frames:[car,jig,tip_dress]}} |
Example CSV Responses | GetFrames,0,car,jig,tip_dress |
AddFrame
Structure | {topic: AddFrame,data: {frame_name: <value>,offset: <value>, parent_frame: <value>}} |
---|---|
Argument Description |
|
Function Description | This command adds a frame to the project. The frame is stored to disk, so when the project is unloaded, the frame will be saved. If the project is downloaded from the control panel and opened in RapidPlan Create, the frame will show up and be editable. The frame can be used as a reference/parent frame for:
|
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: AddFrame,data: {frame_name: pallet_origin,offset: [0.5,0.25,0.35,0.0,180.0,0.0]}} |
Example YAML Response | {topic: AddFrame,type: Response} |
Example CSV Response | AddFrame,0 |
UpdateFrame
Structure | {topic: UpdateFrame,data: {frame_name: <value>,offset: <value>,reference_frame: <value>}} {topic: UpdateFrame,data: {frame_name: <value>,pose: <value>,reference_frame: <value>}} |
---|---|
Argument Description |
Mutually exclusive keys:
|
Function Description | This command updates the position of a frame and all of its children. A frame can be updated by applying an offset from its current position with the offset argument. A frame can also be relocated to a new position in a given frame. It is important to note that this cannot re-parent the frame. Frames can only be updated if they:
|
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: UpdateFrame,data: {frame_name: pallet_origin,offset: [0.5,0.25,0.35,0.0,0.0,0.0]}} {topic: UpdateFrame,data: {frame_name: pallet_origin,pose: [0.5,0.25,0.35,0.0,0.0,0.0]}} |
Example YAML Response | {topic: UpdateFrame,type: Response} |
Example CSV Response | UpdateFrame,0 |
RemoveFrames
Structure | {topic: RemoveFrames} {topic: RemoveFrames,data: {frame_names: <value>}} |
---|---|
Argument Description |
|
Function Description | This command removes a specified frame/s added to the scene. When a frame is removed, any DSM boxes or objects with that frame as a parent will also be removed. If no arguments are passed, all frames will be removed, or an array of the frame names can be passed to selectively remove. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: RemoveFrames,data: {frame_name: [pallet_origin,layer_one_offset]}} |
Example YAML Response | {topic: RemoveFrames,type: Response} |
Example CSV Response | RemoveFrames,0 |
AddBox
Structure | {topic: AddBox,data: {box_name: <value>,size: <value>, parent_frame: <value>}} |
---|---|
Argument Description |
|
Function Description | This command adds a box into the Dynamic Scene Model. Once added, all robots in all robot presets will avoid it. Additionally, current robot motions will avoid the box when added. The box origin is at the corner which the size and offset arguments are relative to. The box has a fixed offset relative to the parent frame, and if the parent frame’s position is updated, the position of the box will be as well. The Dynamic Scene Model is not stored to disk, so when the Project is unloaded, the Dynamic Scene Model is reset. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: AddBox,data: {box_name: case_1,size: [0.5,0.5,0.5], parent_frame: pallet_origin}} |
Example YAML Response | {topic: AddBox,type: Response} |
Example CSV Response | AddBox,0 |
AddObject
Structure | {topic: AddObject,data: {object_name: <value>,object_type: <value>, parent_frame: <value>, offset: <value>}} |
---|---|
Argument Description |
|
Function Description | This command adds a CAD object from the RPC project into the Dynamic Scene Model. Once added, all robots in all robot presets will avoid it. Additionally, current robot motions will avoid the box when added. The object has a fixed offset relative to the parent frame, and if the parent frame’s position is updated, the position of the object will be as well. The Dynamic Scene Model is not stored to disk, so when the Project is unloaded, the Dynamic Scene Model is reset. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: AddObject,data: {object_name: case_1,object_type: case_model, parent_frame: conveyor_origin}} |
Example YAML Response | {topic: AddObject,type: Response} |
Example CSV Response | AddObject,0 |
RemoveBoxes
Structure | {topic: RemoveBoxes} {topic: RemoveBoxes,data: {box_names: <value>}} |
---|---|
Argument Description |
|
Function Description | This command removes a specified box/es from the Dynamic Scene Model. If no arguments are passed, all boxes will be removed, or an array of the box names can be passed to selectively remove. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: RemoveBoxes,data: {box_name: [case_1,case_2]}} |
Example YAML Response | {topic: RemoveBoxes,type: Response} |
Example CSV Response | RemoveBoxes,0 |
RemoveObjects
Structure | {topic: RemoveObject,data: {object_name: <value>}} |
---|---|
Argument Description |
|
Function Description | This command removes a specified object from the Dynamic Scene Model. If no arguments are passed, all objects will be removed, or an array of the box names can be passed to selectively remove. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: RemoveObject,data: {object_name: case_1}} |
Example YAML Response | {topic: RemoveObject,type: Response} |
Example CSV Response | RemoveObject,0 |
Reparent
Structure | {topic: Reparent,data: {box_name: <value>, parent_frame: <value>}} |
---|---|
Argument Description |
|
Function Description | This command will re-assign the parent frame for a specified DSM box. After this command executes, the box will have a new parent frame with an offset such that it remains in its current position. If the box’s new parent frame is moved, the box will move with it with that offset. A box’s parent frame can also be the TCP of a robot, and as the robot moves, the box moves with it maintaining the initial offset. A robot’s default TCP should be used that way it is independent of presets. A robot’s default TCP can be specified as {robot_name}_default_tcp. In order to assign a robot’s tcp as the parent of a box, the robot must be stationary. |
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. |
Example Request | {topic: Reparent,data: {box_name: case_1, parent_frame: Robot1_default_tcp}} |
Example YAML Response | {topic: Reparent,type: Response} |
Example CSV Response | Reparent,0 |
API Endpoints - Robot + Scene Modeling
SetWorkcellState
Structure |
|
---|---|
Argument Description |
|
Function Description | This command changes the entire workcell preset for the loaded project with a combination of robot presets and object states. The combination can contain all robot presets and object states or a partial list. |
Response Details | This command will return a response to acknowledge the command has executed successfully. |
Example Request | {topic: SetWorkcellState, data: { objects: {object_1: object_state_1, object_2: object_state_2}, robots: {robot_1: robot_preset1, robot_2: robot_preset2}}} |
Example YAML Responses | {topic: SetWorkcellState,type: Response} |
Example CSV Responses | SetWorkcellState,0 |