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.
2023/03/06: SetRobotPreset command description is updated

Goal

The ASCII API is a fundamental component of how a user interacts with the Realtime Controller and ultimately controls a robot. In order to effectively complete a task, the user must be able to retrieve information from the Rapidplan Create project, set behavioral characteristics of the robots, and move the robots either following the offline motion plans or with conventional move types.

...

Command strings will be terminated with CR+LF line endings. The length of the command strings should be less then 2KB. Commands that exceed the 2KB size limit are not forwarded out of the networking layer. They’re simply discarded and the connection is closed.

Requests

Requests sent to the Realtime controller will be formatted according to the inline YAML spec. The function type is set by the topic key and then arguments are passed as key value pairs.

...

Structure

Code Block
{topic: SetRobotPreset,data: {robot_name: <value>,preset_name: <value>}}

Argument Description

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

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

Code Block
{topic: SetRobotPreset,data: {robot_name: robot_1,preset_name: open_gripper}}

Example YAML Responses

Code Block
{topic: SetRobotPreset,type: Response}

Example CSV Responses

Code Block
SetRobotPreset,0

...

Only Direct and Roadmap move types can be added to the queue.
A maximum of 100 moves can be added to the queue.
If received in time, the robot will smooth it's current motion into the next in the queue using it's smoothing argument.
The move queue for a given robot is cleared when:
- A Move fails
- A Move is cancelled
While a robot is executing a motion, the next move in the queue is planned
- A robot reserves the swept volume of it’s current motion and the next move in the queue.
- A Move is only added to the queue, if a path could be found.
- Initial responses will be sent for move requests when planning has finished.
Delayed responses will be sent when queued move segments terminate (due to completion, cancelling, or interruption).
Canceling a robot’s motion with CancelMove will clear the move queue and cancel all moves simultaneously. The delayed responses of these moves are not guaranteed to be in queue order.
Queued motions will use the interrupt settings when planning in the background.
Queued motions will use the alternate location, if enabled.
A robot’s preset can be changed when Moves are queued. The number of controlled axes shall stay the same. The robot TCP could change when a robot’s preset switches in the queue.
It is highly recommended to include preset_name in every queued Move command in case a robot’s preset switches in the queue.
Smoothing is supported in queue moves. If the new motion is received in time, the robot will use the current motions smoothing value to blend into the new motion.

Move

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:

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. 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 objectfields, specifies an output based on the timing of a move or a move segment of a combined move. trigger is an object with 3 A trigger argument has the following fields:

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

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.

Function Description

- If partial execution is used(mode=1 in SetAlternateLocation), for time-after triggers:
  - if robot is blocked for a duration > time, trigger will be activated at the specified time value.
  - if robot is unblocked before timeexpires, trigger will be activated at the distance corresponding to the trigger timevalue of the original non-blocked move.
- If partial execution is used(mode=1 in SetAlternateLocation), for time-before triggers:
  - Before reaching the final goal, if time is less than the duration from the partial execution position to the final goal, trigger will be activated at the specified time as normal.
  - If the specified trigger time is more than the duration from the partial execution position to the final goal, trigger will be activated immediately after the robot is unblocked.

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

...

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.

SetObjectState

Structure

Code Block
{topic: SetObjectState,data: {object_name: <value>,state_name: <value>}}

Argument Description

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

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

Response Details

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

Example Request

Code Block
{topic: SetObjectState,data: {object_name: jig,state_name: open}}

Example YAML Responses

Code Block
{topic: SetObjectState,type: Response}

Example CSV Responses

Code Block
SetObjectState,0

...

Structure

Code Block
{topic: RemoveObject,data: {object_name: <value>}}

Argument Description

object_name:

Status

colour	Yellow
title	optional

The name of the object that will be removed.

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

Code Block
{topic: RemoveObject,data: {object_name: case_1}}

Example YAML Response

Code Block
{topic: RemoveObject,type: Response}

Example CSV Response

Code Block
RemoveObject,0

Reparent

CreatePallet

...

Structure

...

Code Block
{topic: CreatePallet}

...

Argument Description

...

None

...

Function Description

...

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.

...

Response Details

...

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

...

Example Request

...

Code Block
{topic: CreatePallet}

...

Example YAML Responses

Code Block
{topic: CreatePallet, type: Response, data: {UUID: 1234-5678-9101-abcd}}

...

Example CSV Responses

...

Code Block
CreatePallet,0,1234-5678-9101-abcd

InspectInboundPackage

...

Structure

...

Code Block

{topic: InspectInboundPackage, data: {conveyor: <value>, package_id: <value>, package_size: [<value>,<value>,<value>], package_orientation: <value>, package_type: <value>, content_type: <value>, edge_reduce_top_size: [<value>,<value>,<value>], edge_reduce_bottom_size: [<value>,<value>,<value>], place_location: [<value>,<value>,<value>], place_orientation: <value>}}

...

Argument Description

...

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

...

Function Description

...

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

...

Response Details

...

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

...

Example Request

...

Code Block

{topic: InspectInboundPackage, data: {conveyor: left, package_id: 11213, package_size: [400,320,360], package_orientation: LENGTH_WIDTH, package_type: CARTON_COR, content_type: BOX, edge_reduce_top_size: [0,0,0], edge_reduce_bottom_size: [0,0,0], place_location: [900,1100,700], place_orientation: LENGTH_WIDTH}}

...

Example YAML Response

...

Code Block
{topic: InspectInboundPackage, type: Response, data: {package_orientation: 1}} {topic: InspectInboundPackage, type: Response, error: {code: 5401, msg: <value>}}

...

Example CSV Response

...

Code Block
InspectInboundPackage,0,1 InspectInboundPackage,5401

QueryClearance

...

Structure

...

Code Block
{topic: QueryClearance, data: {package_id: <value>}}

...

Argument Description

...

package_id: The ID of the package to place.

...

Function Description

...

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.

...

Response Details

...

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.

...

Example Request

...

Code Block
{topic: QueryClearance, data: {package_id: 14}}

...

Example YAML Response

...

Code Block
{topic: QueryClearance, data:{clearance: 13}} {topic: QueryClearance, error: {code: 5001, msg: <value>}}

...

Example CSV Response

...

Code Block
QueryClearance,0,13 QueryClearance,5001

InspectPallet

...

Structure

...

Code Block
{topic: InspectPallet, data: {package_id: <value>}}

...

Argument Description

...

package_id: The placed package ID.

...

Function Description

...

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

...

Response Details

...

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.

...

Example Request

...

Code Block
{topic: InspectPallet, data: {package_id: 12345}}

...

Example YAML Response

...

Code Block
{topic: InspectPallet, data: {package_id: 12345}} {topic: InspectPallet, error: {code: 5401, msg: <value>}}

...

Example CSV Response

...

Code Block
InspectPallet,0,12345 InspectPallet,5401

SetElevatorState

...

Structure

...

Code Block
{topic: SetElevatorState, data: {state: <value>, offset: <value>}}

...

Argument Description

...

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.

...

Function Description

...

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.

...

Response Details

...

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

...

Example Request

...

Code Block
{topic: SetElevatorState, data: {state: MOVING, offset: 0}}

...

Example YAML Responses

...

Code Block
{topic: SetElevatorState, type: Response}

...

Example CSV Responses

...

Code Block
SetElevatorState,0

OverrideInspectError

...

Structure

...

Code Block
{topic: OverrideInspectError, data: {package_id: <value>}}

...

Argument Description

...

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

...

Function Description

...

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.

...

Response Details

...

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

...

Example Request

...

Code Block
{topic: OverrideInspectError, data: {package_id: <value>}}

...

Example YAML Response

...

Code Block

// Successfully executed
{topic: OverrideInspectError, type: Response, data: {}}
// Bad parameters provided
{topic: OverrideInspectError, type: Response, error: {code: 5015, msg: Bad parameters in function call.}}

...

Example CSV Response

...

Code Block
// Successfully executed OverrideInspectError,0 // Bad parameters provided OverrideInspectError,5015

ToggleMonitorFaults

...

Structure

...

Code Block
{topic: ToggleMonitorFaults, data: {speed_scaling_factor: <value>}

...

Argument Description

...

speed_scaling_factor

Status

colour	Yellow
title	optional

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

...

Function Description

...

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

...

Response Details

...

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.

...

Example Request

...

Code Block
{topic : ToggleMonitorFaults, data : { speed_scaling_factor : 0.1}}

...

Example YAML Response

...

Code Block
// Succesfully executed {topic: ToggleMonitorFaults, type: Response, data: {}}

...

Example CSV Response

...

Code Block
// Successfully executed ToggleMonitorFaults,0

Calibrate

Structure

Code Block
{topic: Calibrate, data: {sensor_location: <value>}}

Argument Description

sensor_location: Valid values are:

Inbound camera = 0
Pallet left camera = 1
Pallet right camera = 2

Function Description

This command initiates the calibration of a sensor.

Response Details

Whether the system successfully transitioned into calibration mode

Structure

Code Block
{topic: Reparent,data: {box_name: <value>, parent_frame: <value>}}

Argument Description

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.

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

Response Details

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

Example Request

Code Block
{topic: Reparent,data: {box_name: case_1, parent_frame: Robot1_default_tcp}}

Example YAML Response

Code Block
{topic: Reparent,type: Response}

Example CSV Response

Code Block
Reparent,0

API Endpoints - RapidSense and RapidSenseMonitor

GetRapidSenseStatus

...

Structure

...

Code Block
{topic: GetRapidSenseStatus, data: {response_format: <value>}}

...

Argument Description

response_format:

Status

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

...

Function Description

...

This command returns the status of various RTR subsystems.

...

Response Details

...

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.

...

Example Request

...

Code Block
{topic: GetRapidSenseStatus, data: {response_format: 0}} {topic: GetRapidSenseStatus, data: {response_format: 1}}

...

Example YAML Responses

...

Code Block

{topic: GetRapidSenseStatus, type: Response, data: {rapidsense_version: 2.0.0,rapidsense_mode: 2,pallet_id: 1234-5678-9101-abcd,error_list: [5001]}}
{topic: GetRapidSenseStatus, type: Response, data: {rapidsense_version: 2.0.0,rapidsense_mode: OPERATING,pallet_id: 1234-5678-9101-abcd,error_list: [5001]}}

{topic: GetRapidSenseStatus, type: Response, data: {rapidsense_version: 2.0.0,rapidsense_mode: 0,error_list: [5001]}}
{topic: GetRapidSenseStatus, type: Response, data: {rapidsense_version: 2.0.0,rapidsense_mode: IDLE,error_list: [5001]}}

{topic: GetRapidSenseStatus, type: Response, data: {rapidsense_version: 2.0.0,rapidsense_mode: 1,error_list: [5102,5103]}}
{topic: GetRapidSenseStatus, type: Response, data: {rapidsense_version: 2.0.0,rapidsense_mode: CALIBRATING,error_list: [5102,5103]}}

...

Example CSV Responses

...

Code Block

GetRapidSenseStatus,0,2.0.0,2,1234-5678-9101-abcd,0
GetRapidSenseStatus,0,2.0.0,OPERATING,1234-5678-9101-abcd,0

GetRapidSenseStatus,0,2.0.0,0,null,1,5001
GetRapidSenseStatus,0,2.0.0,IDLE,null,1,5001

GetRapidSenseStatus,0,2.0.0,1,null,2,5102,5103
GetRapidSenseStatus,0,2.0.0,CALIBRATING,null,2,5102,5103

_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

Code Block
{topic:

Calibrate

Reparent,

data: {

sensor

box_

location

name: case_1, parent_frame: Robot1_default_tcp}}

Example YAML Response

Code Block

// Successfully executed

{topic:

Calibrate

Reparent,

type: Response

, data: {}} // Camera hardware failure {topic: Calibrate, type: Response, error: {code: 5102, msg: Camera hardware failure.}

Example CSV Response

Code Block

// Successfully executed Calibrate,0 // Camera hardware failure Calibrate,5102

Reparent,0

Version	Old Version 6	New Version Current
Changes made by	Shun Gao	Shun Gao
Saved on	Jan 12, 2023	Mar 06, 2023

Versions Compared

Key

Goal

Requests

Move

API Endpoints - Scene Modeling

SetObjectState

Reparent

CreatePallet

InspectInboundPackage

QueryClearance

InspectPallet

SetElevatorState

OverrideInspectError

ToggleMonitorFaults

Calibrate

API Endpoints - RapidSense and RapidSenseMonitor

GetRapidSenseStatus