| Table of Contents |
|---|
Revisions
...
2023/07/14: (2.5) Added
validationargument to UpdateTarget command2023/07/19: (2.5) Added BlockMove + ContinueMove commands (more details to come), also updated CombinedMove with new optional blockMove argument
2023/08/02: (2.5) Updated Move command with a new argument
constraint.2023/08/09: (2.5) Correction of the preset-switching behavior in a CombinedMove command.
2023/08/10: (2.5) Updated name of HoldMove and ResumeMove commands (prev. block/continue)
2023/08/11: (2.5) Added MultiRobotMove command and updated SetAlternateLocation with a new mode
multirobot.2023/09/22: (2.5) Replaced Move command argument
constraintwithconstraints.2023/09/28: (2.5) Add documentation about yaml parsing per RAPID-38095
2023/11/14: (2.6) Added IsOnTarget command
2023/11/29: (2.6) Removed MultiRobotMove command
2023/11/29: (2.6) Added support for roadmap + planning moves to configs
2023/11/29: (2.6) Added Move command optional parameter
roadmap_modeto define how the robot should use the roadmap + off-roadmap motions for roadmap moves to a pose or joint config
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 |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | If a robot error/fault state occurs for one of the robots in the currently loaded deconfliction group, the Realtime Controller will enter a fault state. Examples of reasons may be: lost connection to a robot due to an E-stop, or the robot entering a fault state due to excessive speed or force. The ClearFaults command will attempt to recover any faults that the OEM controller allows allows to be cleared programmatically, and transition the Controller back into Config mode if possible. It will fail if there are still active, unresolvable faults. If | ||
Response Details | This command will return a single response code as a result value. | ||
Example Request |
| ||
Example Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This function loads an RPC project. A load result will be returned once the process has finished and then RapidPlan will be in configuration mode. | ||
Response Details | This command will return a response code to acknowledge the command has been received.
| ||
Delayed Response Details | Once the load is completed, the system will send a delayed response to indicate the project has finished loading.
| ||
Example Request |
| ||
Example YAML Responses |
| ||
Example CSV Responses |
|
...
Structure |
| ||||
|---|---|---|---|---|---|
Argument Description |
| ||||
Function Description | This command is used to define which project is the Default project that will automatically be loaded when RapidPlan powers on or is otherwise not in Operation Mode. Sending a SetDefaultProject command without specifying the | ||||
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. | ||||
Example Request |
or
| ||||
Example YAML Responses |
| ||||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This command indicates that the project is ready to begin operation. This call is blocking, until all active robots have been connected. Once all participating robots have indicated readiness, return messages will be sent, and subsequent Move calls will be accepted. | ||
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. | ||
Example Request |
| ||
Example YAML Responses |
| ||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This command will re-activate a robot. After this command, when Connect is called, the activated robot will be connected to, and when in OPERATION mode this robot will be controlled by RTR. | ||
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. | ||
Example Request |
| ||
Example YAML Response |
| ||
Example CSV Response |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This command ‘deactivates’ a robot which means the RTR controller will ignore it when connecting to the robots within a project. Subsequent | ||
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. | ||
Example Request |
| ||
Example YAML Response |
| ||
Example CSV Response |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This command is used to enable and set the alternate location for a robot. With this feature enabled, in the event a Move command fails or is interrupted, the Realtime Controller will not return a response code immediately, and will instead automatically plan to the specified alternate position. Depending on the behavior of complete move the Realtime Controller will either return a response Error code indicating the robot reached the alternate location, or continue to plan to the location that was first specified in the move command. | ||
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. | ||
Example Request |
| ||
Example Responses |
| ||
Example CSV Responses |
|
...
Structure |
| ||||
|---|---|---|---|---|---|
Argument Description |
A
If a robot's external axes remain fixed during a move, or switch to different setpoint values defined by a target,
Robot pose value plus
| ||||
Function Description | With this new generic A A A | ||||
Response Details | When a Move request is received, path planning occurs before a response is sent. If a path is found, this command will return a response code to acknowledge the command has been received, the name of the robot that this move is for, and a unique sequence ID for this specific move. If planning fails, an appropriate error code will be returned, and no delayed response will be sent.
| ||||
Delayed Response Details | If a path was found, the system will send a
or, for a
| ||||
Example Request |
| ||||
Example YAML Responses |
| ||||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This function tells the Realtime Controller to abort planning and motion for the specified robot. After calling this, a robot may be left in an off roadmap location and will require a planning move command. If If a move is canceled mid-motion after a | ||
Response Details | This command will return a response to acknowledge the command has been received and executed successfully. | ||
Example Request |
| ||
Example YAML Responses |
| ||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | ResumeMove: This command continues robot the through combined or pre-set moves for a defined robot. | ||
Response Details | |||
Example Request | ResumeMove: | ||
Example YAML Responses | ResumeMove: | ||
Example CSV Responses | ResumeMove: |
MultiRobotMove
Structure
| Code Block |
|---|
{topic: MultiRobotMove, data: { moves: [{robot_name: <value>, target: <value>, ...}, ...]}} |
Argument Description
moves: An array of move commands for different robots. The move commands must adhere to the Move command specification.
For now, MultiRobotMoves only support moves of type Roadmap. At most one move is allowed per robot.
Function Description
MultiRobotMove allows planning for multiple robots to occur at once if, for instance, you’d like robots to purposefully avoid blocking each other when trying to reach their target destinations. This is compared to normal motions where one robot motion is received at a time and is planned without consideration for what other robots may need to do. Note that normal motions will avoid colliding with other robots but cannot take into account the desired motions of robots whose paths have not yet been planned.
Response Details
The command will return an initial response to indicate that the command has been processed and a collision free path has been found.
A unique sequence number will be included to identify the MultiRobotMove responses. The response will also include a list of robots that were unable to plan motions if the mode flag indicated that the motion should succeed anyway.
| Code Block |
|---|
{topic: MultiRobotMove, type: Response, data: {seq: <value>, failed: <value>}} |
Delayed Response Details
For every Move in the MultiRobotMove, a feedback response will be sent when that robot completes its motion.
| Code Block |
|---|
{topic: MultiRobotMove, type: Feedback, data: {robot_name: <value>, seq: <value>}}
{topic: MultiRobotMove, type: Feedback, data: {robot_name: <value>, seq: <value>}}
.. additional feedback messages
{topic: MultiRobotMove, type: DelayedResponse, data: {seq: <value>}} |
Example Request
| Code Block |
|---|
{
topic: MultiRobotMove
data: {
moves: [
{robot_name: robot_1, target: target_1, speed: 1},
{robot_name: robot_2, target: target_2, speed: 0.5, move_type: direct},
{robot_name: robot_3, pose: [1,2,3,4,5,6], speed: 0.1, smoothing: 0.0}
]
}
} |
Example YAML Responses
| Code Block |
|---|
{topic: MultiRobotMove, type: Response, data: {robot_names: [robot_1, robot_2, robot_3], seq: 23}}
{topic: MultiRobotMove, type: Feedback, data: {robot_name: robot_2, seq: 23}}
{topic: MultiRobotMove, type: Feedback, data: {robot_name: robot_3, seq: 23}}
{topic: MultiRobotMove, type: Feedback, data: {robot_name: robot_1, seq: 23}}
{topic: MultiRobotMove, type: DelayedResponse, data: {seq: 23}} |
Example CSV Responses
| Code Block |
|---|
MultiRobotMove,0,23,1,robot_1,robot_2,robot_3
MultiRobotMoveFeedback,0,robot_2,23
MultiRobotMoveFeedback,0,robot_3,23
MultiRobotMoveFeedback,0,robot_1,23
MultiRobotMoveResult,0,23 |
Example Task Planner integration
The following example shows how MultiRobotMove can be used to resolve a deadlock at runtime.
In the case of a deadlock, normal Move commands will return failure. Using MultiRobotMove combining the targets of the deadlocked robots will resolve the deadlock and move the robots to their targets.
GetTargets
Structure |
| ||||||
|---|---|---|---|---|---|---|---|
Argument Description |
| ||||||
Function Description | This command retrieves the targets for a given robot in a specific preset in the loaded project. The default behavior is to return the targets in the active robot preset, but a different preset can be specified. | ||||||
Response Details | This command will return a response code, followed by a comma separated array of the target names. | ||||||
Example Request |
| ||||||
Example YAML Responses |
| ||||||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
If
| ||
Function Description | This command updates the specified targets position to be at the specified robot TCP location in its current preset, or using an optional pose value. The target’s new position will be used for all assigned robots. A target’s position will only be updated, if all of its connections remain valid, otherwise the command fails and returns an error code Only one target can be updated at a time. While a target is updating, any subsequent UpdateTarget commands will be rejected. With the | ||
Response Details | This command will return an acknowledgement with a status code indicating the command was received and is being executed. | ||
Delayed Response Details | This command will also return a delayed response when the update has completed or failed. | ||
Example Request |
| ||
Example YAML Responses |
| ||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description | This command retrieves the current joint angles of a specified robot. If the robot has additional axes, they will be included sorted by their driver index. The values will be returned in the client’s units for both revolute and prismatic joints. | ||
Response Details | This command will return a response code, followed by the current joint angles in a comma separated array. This command will always include the robot axes, and by default will include the position of external axes if present. | ||
Example Request |
| ||
Example YAML Responses |
| ||
Example CSV Responses |
|
...
Structure |
| ||
|---|---|---|---|
Argument Description |
| ||
Function Description |
| ||
Response Details |
| ||
Example Request |
| ||
Example YAML Responses |
| ||
Example CSV Responses |
|
...