Page Comparison

...

2022/03/14: Initial 2.0 API documentation; motion and setup commands.
2022/03/21: Preset name argument added to Move and Combined move. Collision checking against DSM has been moved to an explicit new argument in Move command. Combined move structure row clarifications.
2022/03/30: GetTCPPose description added (formerly duplicated GetJointAngles). DSM command descriptions added. Additional desctiption added to SetAlternateLocation’s “mode” argument. Moved SetServos location for better organization.
2022/04/08: SetResponseType and SetUnits can now be stored per IP address rather than per client. Example CSV responses added to DSM commands. Robot Presets and Object states are now stored to disk so project reload will have the last set values. SetInterruptBehavior timeout value is now used as the timeout for the alternate location mode: 0 with complete_move: 1, and mode: 1. UpdateTarget can now optionally re-generate the autoconnects associated with that target.
2022/04/14: Initial RSM command documentation. AddBox description updated to include box origin and offset argument. AddFrame description updated to note that frames are not saved to disk.
2022/04/21: API specs for enabling a subset of a project added (Activate, Deactivate, UpdateInactiveRobotSettings).
2022/04/28: GetRapidSenseStatus now returns the pallet_id if one exists. InspectPallet no longer returns the package_id. QueryClearance argument description and response details corrected to state that the clients active units will be used for the clearance value. Fixed minor typos in AddFrame and InspectInboundPackage.
2022/05/02: InspectInboundPackage now returns the package_orientation. Interlock generation and report commands added.
2022/05/03: InspectPallet now returns the package_id.
2022/05/04: SetUnits and SetResponseType descriptions updated to make it clear that only new connections will be affected by set_ip_default.
2022/05/12: GetTCPPose YAML response corrected, the key is pose, not tcp_pose. CreateTarget CSV response delayed response corrected from CreateTarget to CreateTargetResult. Added a note to the SetRobotPreset description that ReleaseControl must be called first, if the number of axes on the robot is changing. Added to the UpdateTarget description to indicate that auto connect constraints will be maintained at the targets new location. Updated CancelMove description to note that it is only accepted in OPERATION mode.
2022/05/31: Preset argument description updated in Move and CombinedMove. GetJointAngles is being renamed to GetJointConfiguration, but both are supported currently.
2022/06/01: Added acceptable string characters to the formation rules section.
2022/06/08: Added SetMaxLinearSpeed and SetMaxLinearAcceleration descriptions.
2022/06/14: More SetAlternateLocation examples added. Clarified the behavior of the reset flag for SetMaxLinearSpeeds and SetMaxLinearAcceleration.
2022/06/17: Corrected SetMaxLinearAcceleration’s max value.
2022/07/01: Updated spec for Move with supported move type and goal combinations.
2022/08/08: Clarified the effect CancelMove has on queued Move and CombinedMove commands.
2022/08/30: Added OverrideInspectError, ToggleMonitorFaults, Calibrate descriptions.
2022/08/31: Updated Queuing Moves when a robot preset changes. Updated Queuing Moves with smoothing support. Updated Move spec that supports robot preset changes. Updated SetRobotPreset spec.
2022/10/03: Updated spec for DeactivateRobots.
2022/12/03: (2.2)Updated spec for CreateTarget to add a new target without connections.
2022/12/03: (2.2)Added RenameTarget command.
2022/12/03: (2.2)Added RemoveTarget command.
2022/12/03: (2.2)Added AddConnection command.
2022/12/03: (2.2)Added RemoveConnection command.
2022/12/03: (2.2)Updated spec for Move with support for external axes and triggers.
2022/12/03: (2.2)Updated spec for CombinedMove with support for external axes and triggers.
2022/12/03: (2.2)Updated spec for CancelMove with ramp-down speed at a fixed 80%.
2022/12/03: (2.2)Updated spec for SetDefaultProject to clear the default project if project name input is not specified.
2022/12/03: (2.2)Added GetLoadedProject command.
2022/12/03: (2.2)Added GetRobotPresets command.
2022/12/03: (2.2)Updated spec for UserLog with allowed characters in a user log.
2022/12/04: (2.2)Danger/risk of interleaving RTR with non-RTR move commands is documented in the Move command.
2022/12/05: (2.2)GetJointAngles command is deprecated and replaced by GetJointConfiguration.
2022/12/05: (2.2)Added move type and target type support matrix.
2022/12/05: (2.2)Added 2 cautionary statements regarding mixing RTR with non-RTR moves and robot off-roadmap behaviors for Move command.
2022/12/09: (2.2)Added 1 cautionary statement regarding mixing RTR-controlled moves with non-RTR stop commands.
2023/01/04: (2.2)SetServos command is removed.
2023/01/13: (2.2)Move command and queued move smoothing behavior description is updated.
2023/01/18: (2.2)API command string size limit is specified.
2023/01/30: (2.2)Move command trigger behavior description is updated.

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.

...

Structure

Code Block

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

Argument Description

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 robot axes are present, the goal does not include them. Unless the external axes value is provided as an argument, external axes will either remain fixed during a move, or switch to different setpoint values defined by roadmap moves. Valid key values are as following, 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.

external_axes:

Status

colour	Yellow
title	OPTIONAL

This argument, including all the related parameters that are defined within this object, specifies the names of the external axes, the external axes position value to for moving to a goal pose, or whether the external axis should be used by RapidPlan software when solving a move to a goal pose.

If a robot's external axes remain fixed during a move, or switch to different setpoint values defined by a target, external_axes should be left unspecified.

external_axes is defined as {<axis name>: active} or {<axis name>: <value>}. The names of the external axes must match what is already defined in the RapidPlan Create project.
use {<axis name>: active} if an external axis is used by RapidPlan software when solving a move to a goal pose.
use {<axis name>: <value>} if an external axis is used for a move to a goal pose with a specific external axis position value.

move_type:

Status

colour	Yellow
title	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:

Status

colour	Yellow
title	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. The smoothing argument will be applied to via points between the start and end joint configurations for a roadmap move type, and will be used to blend into queued motions for roadmap and direct move types.

interp:

Status

colour	Yellow
title	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:

Status

colour	Yellow
title	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:

Status

colour	Yellow
title	OPTIONAL

This flag overrides collision checking against the Dynamic Scene Model(https://realtimerobotics.atlassian.net/wiki/spaces/POUG/pages/2541618649/2.2+WIP+Glossary+of+RapidPlan+Create+and+Realtime+Controller+Terms#Dynamic-Scene-Model(DSM) ) 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:

Status

colour	Yellow
title	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:

Status

colour	Yellow
title	OPTIONAL

A boolean flag indicating that a pose move should be performed relative to the last commanded robot pose. Default value is false. The move type must be direct when using the relative flag. A reference frame can be specified as well for the pose to be in.

ref_frame:

Status

colour	Yellow
title	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.

preset_name:

Status

colour	Yellow
title	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 cannot have any moves in it’s queue with a different TCP or number of controlled axes.

trigger:

Status

colour	Yellow
title	OPTIONAL

This argument, including all the related parameters that are defined within this object, specifies an output based on the timing of a move or a move segment of a combined move. trigger is an object with 3 fields:

name: Only one trigger can be included for each move command, or each move segment of a combined move command. The trigger should have a user defined, stateless, globally unique name, to identify the signal for the receiver of the trigger.
output: The trigger output should be configured during runtime as part of a move command, to turn on or off the output signal as an 1-shot event, until the signal is overridden by either another Move command, or a different control device, e.g., a PLC. If the output key is not specified, this trigger is disabled and trigger time is ignored. If output is specified, trigger time must be defined and cannot be omitted.
- 0 or false: output is off
- 1 or true: output is on
time: Specifies the timing of the output, i.e. the time before the target position is reached, or after the move has started. The unit is in seconds and whose absolute value must be greater than 0.1.
- time must be a none-zero value, and should always be >= 0.1 or <= -0.1. The move command will return an error code if 0.1 < time < 0.1.
- A positive value ( time>=0.1) indicates the time after the move starts, ie., a "time-after trigger".
- A negative value (time<=-0.1) indicates the time before reaching the goal, ie., a “time-before trigger”.
- If time is longer than the actual move time, a time-before after trigger will turn on when reaching the goal, a time-after before trigger will turn on when the move starts. The MoveFeedback response message for the trigger will arrive before the MoveResult message for the move.
- If alternate location is used(mode=0 in SetAlternateLocation), and if complete_move = true:
  - Only a time-after trigger will apply to the move to the alternate location, a time-before trigger will take no effect to this move.
  - From the alternate location, only a time-before trigger will apply to the move that reaches the next goal, a time-after trigger will take no effect to this move.
- If alternate location is used(mode=0 in SetAlternateLocation), and if complete_move = false:
  - Only a time-after trigger will apply to the move to the alternate location, a time-before trigger will take no effect to this move.
- If partial execution is used(mode=1 in SetAlternateLocation), for time-after triggers:
  - if robot is blocked for a duration > computed trigger time, trigger will be activated at the computed trigger time.
  - if robot is unblocked before computed trigger time, trigger will be activated at the distance corresponding to the trigger time of the original move.

Function Description

Formerly there were blind moves, MoveToXXX, and OffroadtoXXX commands. We would end up with a minimum of 9 different move commands based on if you wanted to move to a target, coordinate (pose) or a joint configuration. With this new generic 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 off-roadmap 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.

Caution: There are risks involved with mixing RTR moves with non -RTR moves(for example, native moves from a robot teach pendant program). The user must make sure that a RTR move has completed successfully if the completion of that move is necessary for the next non-RTR move to be collision-free.

Caution: There are collision risks involved with stopping a robot from a robot teach pendant program when multi-robot moves are controlled by a RapidPlan controller. The user must make sure that all RTR move commands and stop signals from a different command source are programed and processed in a coordinated fashion, for collision-free operations in a multi-robot workcell.

Caution: When a roadmap move is issued, how far the robot can be away from the roadmap is defined as the distance tolerance to the roadmap node, offroad_tcp_tol. This parameter, in meters, is saved in ApplianceGraphSearchConfig.xml under /var/lib/rtr_appliance_app/appliance_data/<Project Name>/. The default value is 5.0 meters. This parameter can be modified by a user and will take effect after the xml file is saved and after the project is reloaded.

If a roadmap move to target command is issued when the robot is off the roadmap, and if the TCP distance between the current robot config and the closest node in the roadmap is greater than offroad_tcp_tol, then the roadmap move to target will return failure.
If a roadmap move to pose command is issued when the pose is off the roadmap, and if the distance between the goal pose and the closest node in the roadmap is greater than offroad_tcp_tol, then the roadmap move to pose will return failure.

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.

Code Block
{topic: Move,type: Response,data: {robot_name: <value>,seq: <value>}}

Delayed Response Details

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.

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

or, for a trigger a feedback response will be sent to indicate that trigger output is activated to on, or off. The trigger feedback responses will include the same seq as the Move it is a part of.

Code Block
{topic: Move,type: Feedback, data: {robot_name: <value>,seq: <value>, trigger: {name: <value>, output: <value>}}}

Example Request

Code Block
{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

Code Block

{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

Code Block
Move,0,robot_1,312 ... move executes ... MoveFeedback,0,robot_1,312,Output_1,1 ... 0.5s MoveResult,0,robot_1,312

...

Version	Old Version 13	New Version 14
Changes made by	Shun Gao	Shun Gao
Saved on	Jan 18, 2023	Jan 30, 2023

Versions Compared

Key

Goal