[COPY] RapidPlan 2.1 ASCII API

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

• 0 or csv

• 1 or yaml

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

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

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

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

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

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

• 0 or m,meter,meters

• 1 or cm,centimeter,centimeters

• 2 or mm,millimeter,millimeters

• 3 or ft,foot,feet,'

• 4 or in,inch,inches,”

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

• 0 or rad,rads,radian,radians

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

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

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

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

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

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

None

This command retrieves the current mode of the Realtime Controller.

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

None

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.

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

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

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.

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

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

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>}}

None

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.

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

{topic: UnloadProject,type: Response}

project_name: This indicates which project will be made the default project.

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.

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

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

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.

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

robot_name: Specifies which robot should be deactivated.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

robot_name: OPTIONAL Specify which robot should be connected to. If not passed, all active robots in the project will be connected.

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.

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

robot_name: OPTIONAL The specific robot to disconnect from.

This command disconnects from all robots in the project (unless a robot is specified) and returns them to the Initialized status. Disconnect can only be called successfully when in CONFIG mode.
This command is useful for saving time by keeping the project loaded on the controller while allowing the robots to perform tasks independent of Realtime control like rebooting.

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

None

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.

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

None

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

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

robot_name: The name of the robot to acquire control of.
preset_name:OPTIONAL Switches the active robot preset when acquiring control.

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.

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

robot_name: The name of the robot to release control of.
preset_name:OPTIONAL Switches the active robot preset when releasing control.

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. 
While a robot is in Released mode, the rest of the Realtime Controller system will use the last known joint state of the paused robot as an obstacle, and will use the robot preset that was active (or optionally set) when that call was made. 
After completing the desired operation, the user should call AcquireControl. Until that call, the robot will not accept any Move commands from this API.

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

robot_name: The name of the robot this command is for.

enabled: Specifies if the servos are being enabled or disabled. A value of 0 will disable (turn off) the servos.

This command is used to disable a robots servos. Enabling the robot servos with this command is currently not possible. A robots servos can only be disabled while the controller is in CONFIG mode since operation mode assumes the robots are ready and able to move. This command is often used to disable a robots servos after returning to config mode.

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

robot_name: The name of the robot this command is for.
max_accel: A value from 1mm/s^2 to 10,000,000mm/s^2 that defines the maximum acceleration allowed for the specified robot. The clients active units will be used, or the default units of mm/s^2.

reset: OPTIONAL A boolean flag that indicates the Linear Acceleration limits should be reset to the default values. The only accepted value for this flag is one that evaluates to True. Note: if max_accel is also provided, it’s value will be ignored, and the acceleration limits will be reset.

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 reset flag. This command can only be sent when the specified robot is stationary, and all subsequent motions will adhere to the provided limit.

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

robot_name: The name of the robot this command is for.
max_speed: A value from 0.1mm/s to 100,000mm/s that defines the max linear speed allowed for a specified robots TCP. The clients active units will be used, or the default units of mm/s.

reset: OPTIONAL A boolean flag that indicates the Linear Acceleration limits should be reset to the default values. The only accepted value for this flag is one that evaluates to True. Note: if max_accel is also provided, it’s value will be ignored, and the acceleration limits will be reset.

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 500 (in mm/s) is passed for the max_speed parameter, a move command with a speed parameter of 0.5 will move the robot at up to 250mm/s.

A user can specify the max linear speed allowed for a robot using this command, or reset to the default value using the reset flag.

This command can only be sent when the specified robot is stationary, and all subsequent motions will adhere to the provided limit.

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

robot_name: This indicates which robot this call pertains to .
enabled: Accepts 0 to disable alternate behavior or 1 to enable alternate behavior at the specified target. If enabled is being set to 0, no other arguments are required.

mode: OPTIONAL Specifies what the robot should do if the original motion fails.

• 0: Default behavior. Move to a different, specified, position.

• 1: Partial Execution. If this option is selected, the robot will move along its path as far as it can before a robot-based obstruction is present. If the obstruction is removed before deceleration, the robot will not stop at this point and continue smoothly towards the goal. If the obstruction is still present, the robot will come to a stop and automatically resume motion when the robot-based obstruction is removed. This behavior does not trigger for static-obstacle obstructions.

goal: OPTIONAL If mode is set to 0, this argument specifies the position that will act as the alternate position for the specified robot. Goal is a placeholder, and the actual key value pair would correspond to the acceptable positions which are:

• target_name: <target_name>

• pose: [x,y,z,r,p,y]

complete_move: OPTIONAL Default value of 1. This boolean specifies if the robot should continuously try to plan a motion to the original target after it has successfully moved to the alternate location. If True a robot that has a move timed out will first move to the alternate location. If this alternate move is successful it will continuously try to plan a motion from the alternate location to the original move request location. If False a robot that has a move timed out will move to the alternate location and wait there for the next command.

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 SetAlternateLocation command can only be sent while a robot is stationary and while the Realtime Controller is in either CONFIG or OPERATION mode.

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 move_type: roadmap then the robot will make a roadmap move to the alternate location. If the original move is a move_type: direct then a direct move will be made to the alternate location.

When partial execution is enabled (mode: 1) or the default behavior (mode: 0) with complete move enabled, the timeout value from SetInterruptBehavior will be used.

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

robot_name: This indicates which robot this call pertains to. 
timeout: -1 or 0.05 to 1000.0. This indicates how long the Realtime Controller should continue trying to find a path if one cannot currently be found. -1 indicates an infinite timeout, and any non-zero floating point value specifies the time (in seconds) before a timeout response is sent. This timeout will also be used by SetAlternateLocation when mode: 1 or mode:0 and complete_move: true.
max_replans:OPTIONAL -1 or 0 to 1000. Default value of -1. This parameter specifies how many times a robot will attempt to find a path to the goal if it is blocked or interrupted during it’s motion. A value of 0 indicates the robot should not attempt to replan if blocked, a value of N indicates that the robot should attempt to replan a maximum of N times before returning failure, and -1 indicates an infinite number of replan attempts.

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: timeout = 30 and max_replans=10

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

robot_name: The name of the robot this command is for.
preset_name: Specifies which preset to switch to as defined in RPC.

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. Robot preset changes are only allowed while a robot is moving if using the queued Moves or a CombinedMove.

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.

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

object_name: Specifies which object this call pertains to.
state_name: Specifies which state of the object should be used as defined in RPC.

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 state_name.
When an object state is changed, current robot motions are not re-validated, but new move commands will respect the new active state.

When called, the selected object state is stored to disk so upon project reload, the last active state will be used.

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

robot_name: The name of the robot you would like to move.

goal: Where the robot will move to, either a target or pose. Goal is a placeholder key, and the acceptable keys are either pose or target. When additional axes are present, the goal does not include them. Unless the external axes value is provided as an argument, external axes will remain fixed during a move. Valid key value pairs are as follows, pose: [x,y,z,r,p,y] or target: target_name.

speed: The speed at which the robot will move on a scale from 0.01 to 1.0. This scales max velocity but not acceleration or jerk. For planning move types, the speed is capped at 0.1.

move_type: OPTIONAL The type of move the robot will make. Either direct, roadmap, or planning. Default move type is a roadmap move. The arguments are case insensitive or can use the assigned numeric value.

• 0 or direct

• 1 or roadmap

• 2 or planning

smoothing: OPTIONAL A value from 0.0 mm to 500 mm indicating how far from a node the robot should begin smoothing it’s trajectory. Default value is 0.0 mm.

interp: OPTIONAL Specifies the interpolation type for the robot when making a direct move, or any time it must leave the roadmap. Use the case insensitive string, or it’s integer equivalent to specify joint or linear interpolation. This parameter does not apply to a planning move. Default is joint space interpolation.

• 0 or J (default)

• 1 or L

collision_check: OPTIONAL This flag overrides collision checking against the static scene for Direct move types. Robot to robot collisions will always be checked regardless of this flag, but robot self collisions will not be checked. A value of 1 specifies collisions should be checked, and a value of 0 specifies collisions will not be checked. Default value is 1.

collision_check_dsm: OPTIONAL This flag overrides collision checking against the dynamic scene model for Direct move types. A value of 1 specifies collisions should be checked, and a value of 0 specifies collisions will not be checked. Default value is 1.

timeout: OPTIONAL This timeout only applies to planning move types when the interrupt behavior is not applicable. This value is the amount of time given to plan a path to the specified goal, in seconds. If not provided, the default value is 10 seconds. The minimum value is 0.01 seconds and the maximum value is 120.0 seconds.

relative: OPTIONAL A boolean flag indicating that a pose move should be performed relative to the last commanded robot pose. Default value is false.

ref_frame: OPTIONAL The name of a frame in the RPC project that should be used as a reference for relative moves. The default reference frame is world. Acceptable reference frames are world and tcp.

preset_name: OPTIONAL This argument specifies which preset the robot should switch to before executing the motion. Including this argument has the same effect as calling SetRobotPreset before the Move command. If included, the robot can have moves in it’s queue with a different robot TCP, but number of controlled axes shall stay the same. preset_name should be included in every queued Move command in case a robot’s preset switches in the queue.

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 Move command and the key value syntax, you can specify any of those moves with this one command.
A direct move moves the robot directly from it's current position to it's goal position with a given interpolation type. This command is efficient, but can easily be blocked by other robots. It is very useful for final motions, especially if collision checking needs to be disabled.
A roadmap move will follow the edges defined in the RPC project. This is expected to be the most common move type since the robots will use the roadmap to dynamically avoid obstacles. If pose is specified, and there is no target in the roadmap as that pose, the robot will leave the roadmap to reach the actual pose. The offroadmap portion will be collision checked, and will use the interpolation type specified (or joint interpolation by default).
A planning move calculates a path for the robot at runtime to reach the goal. This is primarily used to put a robot on the roadmap in the beginning of a task. When called, the requested robot must not be executing any current requests, otherwise it will immediately return an error. If any other robots are currently executing requests when this request is called, the other robots will pause their executions, allowing the given robot to plan and move, before automatically continuing their motion afterwards. If no collision free path to the hub can be found, the server will return an error by the end of the given timeout period.

Note: in 2.0 the supported Move type and goal combinations are:

• roadmap moves to: pose and target

• direct moves to: pose

• planning moves to: target

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>}}

If a path was found, the system will send a MoveResult message along with a response code to indicate when the move completes. The name of the robot that the move was for, and the unique sequence ID for that move will be returned in the message. If the move is interrupted, the delayed response will contain an appropriate error code.
If this command is part of a series of Move commands issued, and the motion sequence is canceled with CancelMove, every queued move is canceled simultaneously. The delayed response indicating this move is canceled is not guaranteed to be in queue order.

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

robot_name: The robot that this combined move is for. A combined move, can only included motions for one robot, and therefor the robot_name key from the individual move commands can be omitted. If the robot_name is included in the individual Move commands, it will be ignored.

moves: An array of up to 10 Move commands to be concatenated together. The move commands can only be direct or roadmap move types, and must adhere to the Move command specification. However, redundant keys from the Move command can optionally be omitted, since they are arguments of the CombinedMove.

preset_name:OPTIONAL This optional argument specifies which preset the robot should switch to before executing the combined move. All moves will then execute using this preset. Including this argument acts exactly like calling SetRobotPreset before the combined move. Note: if this argument is not included, then each move in the move array must specify the preset that should be used for it. Each move can use a different preset provided the TCP or number of controlled axes do not change.

CombinedMove allows multiple move commands to be executed as if it was one motion, and the individual segments can optionally be blended together to maintain a higher velocity.

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 CombinedMove is interrupted, an error will be returned in the delayed response. In order to resume the CombinedMove from its current position, it is expected that the user maintains a list of the completed individual moves and then send a new CombinedMove with the moves that didn’t complete.

If move queuing is being used, a CombinedMove can be added to the queue just like any other move.

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 CombinedMove responses. When a move in the sequence is completed, a Feedback response will be returned, and upon completion of the full move sequence, additionally a DelayedResponse will be send.

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

For every Move in the CombinedMove a feedback response will be sent to indicate that segment has completed. The feedback responses will include the same seq as the CombinedMove they are a part of, as well as a zero index index key to identify which segment the move result is for.

{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>}}

{
  topic: CombinedMove,
  data: {
   robot_name: robot_1,
    moves: [
      {move_type: roadmap,target: staging,speed: 1.0,smoothing: 0.25},
      {move_type: roadmap,target: pre_pick,speed: 1.0,smoothing: 0.1},
      {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.

robot_name: The name of the robot who’s move is being canceled.

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.

This command is only accepted when the RTR Controller is in OPERATION mode.

If a series of Move or CombinedMove commands are queued for the robot in question, they will all be canceled simultaneously. The delayed responses of these commands are not guaranteed to be in queue order.

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

target_name: Specifies the name of the new target to be created.
robot_name: This indicates which robot will be assigned to the new target.

This command creates a target in the active robot preset for the specified robot. The target will attempt to connect to all other targets assigned to the robot in the current preset with a joint space interpolation type.

The target is created using the robot’s current joint angles which means the controller must be in CONFIG mode and the robot state must be connected.

A target will only be created if it has at least one valid edge otherwise the command will fail. This could result from the new position being unreachable, the new position being in collision, or all motions to the new target resulting in a collision.

Only one target can be created at a time. While a target is generating, any subsequent CreateTarget commands will be rejected.

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

This command will also return a delayed response when the update has completed or failed.

target_name: Specifies which target will have its position updated.

robot_name: This specifies which robots TCP will be used at the new target location.

retrigger_autoconnect: OPTIONAL This boolean argument specifies if the auto-connect should be regenerated when updating the targets position. If the target is not part of an auto-connect, then this argument will have no effect. The default value is False.

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.
The target is created using the robot’s current joint angles which means the controller must be in CONFIG mode and the robot state must be connected.

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 EDGE_INVALIDATED. This could result from the new position being unreachable, the new position being in collision, or one of the motions to the new position resulting in a collision.

Only one target can be updated at a time. While a target is updating, any subsequent UpdateTarget commands will be rejected.

With the retrigger_autoconnect argument set to true, the targets position will be updated, and then the autoconnect will be re-run using the same parameters as set in RPC. With retrigger_autoconnect set to false, just the target’s position will change, and all via point locations will remain the same. The edges leading to the new target location will be validated against the constraints of the autoconnect, and the UpdateTarget command will fail if all constraints are not met.

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

This command will also return a delayed response when the update has completed or failed.

robot_name: Specifies the name of the robot to return the joint angles for.

Note: This command is being deprecated in favor of GetJointConfiguration since not all joints are represented as an angle.

This command retrieves the current joint angles of a specified robot. If the robot has additional axes, the will be included sorted by their driver index.

The values will be returned in the client’s units for both revolute and prismatic joints.

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 will include the position of external axes if present.

robot_name: Specifies the name of the robot to return the joint angles for.

This command retrieves the current joint angles of a specified robot. If the robot has additional axes, the will be included sorted by their driver index.

The values will be returned in the client’s units for both revolute and prismatic joints.

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 will include the position of external axes if present.

robot_name: Specifies which robot’s TCP pose will be returned. The TCP of the active robot preset will be used.

ref_frame: OPTIONAL The reference frame in which to return the TCP coordinates. Default is world.

This command returns the specified robot’s TCP coordinates in the world or user specified frame for the active robot preset. Acceptable frames are:

• <robot_name>_base: the base frame of the robot as defined in the robot model. This is a reserved frame name in RPC.

• <robot_name>_default_tcp: the default tcp as defined in the robot model. This is a reserved frame name in RPC.

• any user created frame in the RPC project

The coordinates are returned in the client’s unit and rotation convention.

​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.

frame_name: A name that will be associated with the frame being created. The name must be unique.

offset: OPTIONAL An array of 6 floats that specifies the offset between the parent frame and this frame. The offset uses the clients active units and rotation convention, or the default of millimeters, degrees, roll pitch yaw. The default offset is [0,0,0,0,0,0]

parent_frame: OPTIONAL Specifies the parent reference frame. Default value is the world frame. A parent frame must be static and not on a stateful object. Eg. a parent frame cannot be attached to a robot, or an object who’s parent mate has multiple states.

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:

• Dynamic Scene Model boxes and objects

• Other frames

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

frame_name: The name of the frame who’s position will be updated.

Mutually exclusive keys:

• offset: An array of 6 floats that specifies an offset that will be applied to the frame relative to it’s current position. The clients active units and rotation convention are used, or the default of millimeters, degrees, and roll pitch yaw.

• pose: An array of 6 floats that specifies the new position for the frame. The clients active units and rotation convention are used, or the default of millimeters, degrees, and roll pitch yaw.

reference_frame: OPTIONAL The name of the frame to be used as the reference frame for the pose or offset argument. The default value is world frame for a pose update. When offsetting a frame, the default is to reference itself.

This command updates the position of a frame and all of it’s children. A frame can be updated by applying an offset from it’s 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:

• Are static (eg. they are not attached to a robot)

• Are not attached to stateful objects (eg. none of the parent mates can have more than one state)

• Have no children aside from:

  • DSM Boxes

  • DSM Objects

  • Other frames

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

frame_names: OPTIONAL An array of the names of the frames that will be removed.

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.

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

box_name: A name that will be associated with the object being created. The name must be unique.

size: An array of 3 floats that specifies the XYZ size of the box relative to it’s origin which is at the corner of the box. The size uses the clients active units, or the default of millimeters. Values can be either positive or negative.

parent_frame:OPTIONAL Specifies the parent reference frame. Default value is the world frame. A parent frame must be static and not on a stateful object. Eg. a parent frame cannot be attached to a robot, or an object who’s parent mate has multiple states.

offset: OPTIONAL An array of 6 floats that specifies the offset between the parent frame and this box. Once added, the offset is fixed between the box and the parent frame. The offset uses the clients active units and rotation convention, or the default of millimetres, degrees, roll pitch yaw. The default offset is [0,0,0,0,0,0].

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.

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

object_name: A name that will be associated with the object being created. The name must be unique.

object_type: The name of the object type as defined in RPC.

parent_frame:OPTIONAL Specifies the parent reference frame. Default value is the world frame. A parent frame must be static and not on a stateful object. Eg. a parent frame cannot be attached to a robot, or an object who’s parent mate has multiple states.

offset: OPTIONAL An array of 6 floats that specifies the offset between the parent frame and this object. Once added, the offset is fixed between the object and the parent frame. The offset uses the clients active units and rotation convention, or the default of millimetres, degrees, roll pitch yaw. The default offset is [0,0,0,0,0,0].

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.

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

box_names: OPTIONAL An array specifying the name/s of the boxes that will be removed.

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.

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

object_name: OPTIONAL The name of the object that will be removed.

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.

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

box_name: The name of the box that will have it’s parent frame updated.

parent_frame: This argument specifies the new parent frame for the box. The frame must be a dynamic frame added with the AddFrame command, or a robot’s default TCP addressed as {robot_name}_default_tcp.

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 it’s 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.

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

response_format: OPTIONAL An optional argument specifying if the response should be in string format or integer format. The default response format is string.

• 0 or int to specify integer response format

• 1 or str to specify string response format

This command returns the status of various RTR subsystems.

This command will return a response containing the status of Rapidsense

rapidsense_version: The current version of Rapidsense in the form, major.minor.build

rapidsense_mode: IDLE or 0, CALIBRATING or 1, OPERATING or 2, FATAL or 3

pallet_id: The UUID of the current pallet (as returned in CreatePallet). If no pallet exists, the YAML response will omit this key and the CSV response will return null.

number_of_errors: The number of errors present. Note: only included in the CSV response type.

error_list: The list of current Rapidsense response codes.

None

This command must be run before any packages can be enqueued to be added to the pallet. If a pallet currently exists, this command will clear the existing pallet and replace it with a new one.

This command will return a response to acknowledge a pallet has been created successfully, and will return it’s UUID.

The arguments require the the conveyor ID (e.g., left/right), package ID, the package dimensions, package attributes as provided by the build plan, and the expected place location.

conveyor: A string indicating upon which conveyor the package is placed. For example, whether it is on the left or right conveyor. The conveyor IDs must match the RapidSense’s configuration. This can be configured before deployment. Valid values are left and right.

package_id: A unique string corresponding to the item number or ID.

package_size: An array of 3 floats specifying the expected length, width, height of the product to be confirmed by RapidSense. The clients active units will be used or the default which is millimeters.

package_orientation: is the orientation of the package along the axis of motion on the conveyor. Supported values are: LENGTH_WIDTH, WIDTH_LENGTH

package_type: A string with one of the following values:

• CARTON_COR for corrugated cardboard

• CARTON_OPEN for cartons that are open (display side and top are open)

• CARTON_S for solid, rectangular shaped packages

• PAPER_WRAPPED for paper wrapped products

• SHRINK_WRAPPED for shrink wrapped products

• SHRINK_WRAPPED_PLATE for shrink wrapped items resting on a plate made of cardboard, for instance

• TOTE for closed plastic totes

• TOTE_COLLAPSE for collapsible totes

• TOTE_NESTABLE for nestable totes

• TOTE_TAPERED for tapered totes

• TRAY for items shrink wrapped together sitting in a shallow (e.g., short) tray

• TRAY_POLY for polystyrene trays made to support items nested within them

• TRAY_UPSIDE for packaging in which the tray is on the top of the products instead of the typically on the bottom

content_type: A string indicating the material properties of the items in the package. This information is particularly useful for adjusting camera parameters to improve object detection. Values are strings and the possible values are (roundness is determined in conjunction with edge-reduce values):

• AEROSOL for aerosol products

• BLISTER this could be bubble wrapped items (need to confirm with Marius)

• BOTTLE_GLASS for glass bottles

• BOTTLE_METAL for metal bottles

• BOTTLE_PLASTIC for plastic bottles

• BOX for boxed items

• CANISTER_METAL for metal canisters

• CANISTER_PLASTIC for plastic canisters

• CAN_GLASS for glass cans

• CAN_METAL for metal cans

• CAN_PLASTIC for plastic cans

• COMPOSITE for composite materials

• CUP for cups

• POUCH for items in pouches

• TUBE for tubed items

edge_reduce_top_size: An array of 3 floats specifying the length, width, height of the top of the package if it is tapered from the point at which it would be flush with the package sides. The clients active units will be used or the default which is millimeters.

edge_reduce_bottom_size: An array of 3 floats specifying the length, width, height of the bottom of the package if it is tapered from the point at which it would be flush with the package sides. The clients active units will be used or the default which is millimeters.

place_location: An array of 3 floats specifying the X,Y,Z position of the bottom-left-origin for the place location of the package. The position is the the pallet frame created with CreatePallet. The clients active units will be used or the default which is millimeters.

place_orientation: The orientation of the package upon placement. Supported values are: LENGTH_WIDTH, WIDTH_LENGTH

This command has 2 purposes: it informs RapidSense of a prospective candidate for palletizing as well as corroborating the build plan expectations.

The response contains a pass or fail for the check against the build plan AND the package orientation. Upon failure, the failure reasons (wrong dimensions, missing package, etc) are returned to the caller along with the package orientation in the case of wrong orientation.

package_orientation: is the orientation of the package along the axis of motion on the conveyor.

• 0 which represents LENGTH_WIDTH

• 1 which represents WIDTH_LENGTH

package_id: The ID of the package to place.

RapidSense computes the average maximum height for a placement location to allow dynamic adjustment of the z-height during placing. NOTE: objects that are to be placed with significant overhang will bias the measurements so care should be taken in computing this value to allow overhangs but not bias the calculations to negatively impact system operations. This command can be run at any time while RapidSense is in OPERATING state.

The response contains a status for the operation and the clearance if the operation status was successful (i.e., 0). Upon failure, the error code is returned. The clearance value will use the clients active units or the default which is millimeters.

Status indicates whether the query command was successful or whether an error was encountered. A status of 0 indicates the operation was a success. Otherwise, the error code is returned. If an error code is encountered, the clearance is not returned.

package_id: The placed package ID.

This command is run after a package is added to the pallet.

The response contains the status of the operation and the package_id provided in the request. A status of 0 indicates the operation was successful, otherwise an error code corresponding to the failure mode is returned and the appliance shall take appropriate action (halting the system when necessary). Remediation strategies differ based on the error encountered.

state: The current state of the elevator. Either a case insensitive string, or it’s integer map.

• MOVING or 0

• STATIONARY or 1

offset: A float specifying how far the elevator has moved. The clients active units will be used or the default which is millimeters.

This command is run once when the elevator begins moving and another time when the elevator stops moving. The destination offset will use the client specific settings, or millimeters by default.

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

None

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

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

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

• The controller will enter “Fault”.

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

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

message: A string to be written to the RapidPlan logs. Must be less than 500 characters and may not contain characters {}[]'"

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

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

None

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

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

None

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

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

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

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

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

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

• For each sequence_number an interlock list is provided.

  • Each interlock is given a unique name.

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

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

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

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

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

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

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

package_id: The package ID of the package, in error, to override.

This command is valid anytime an inspection call is made that fails during inbound or pallet inspection. The command will “promote” a package on inbound from failed to ready for placement on the pallet. If the package is on the pallet, that package is marked OK.

If the package ID invalid, BAD_PARAMS (5015) is returned, otherwise, if the operation is successful, OK (0), is returned.

speed_scaling_factor: OPTIONAL The scaling factor to limit all active robots' speed. If not specified, the default value is 0.1.

This command toggles whether monitor faults cause the controller to fault and sets the scaling factor for all active robots' motions. Valid values are between 0.001 and 1.0. Use 1.0 to enable the entire range of speeds. These values are percentages, for instance, 0.1 is 10%.

Whether the command was successful in toggling the flag allowing monitor failures to cause controller faults along with the new value of speed scaling factor that was set for the system speed limit.

sensor_location: Valid values are:

• Inbound camera = 0

• Pallet left camera = 1

• Pallet right camera = 2

This command initiates the calibration of a sensor.

Whether the system successfully transitioned into calibration mode.