NOTE: This is an unreleased beta feature and its functionality will be extended significantly in the future with path editors, simplified usage and rendered path visualizations.

It is very easy to save waypoint and path commands for the pilot view in a few clicks by copying the current pose of your robot or navigation waypoint and pasting it into a pilot command. Operators can then access this command when they are piloting a robot by pressing C then 1, 2, 3, 4, ... or clicking in the bottom right corner of the screen.

Overview of Steps

1. Copy pose - In the map view, press P to copy the current pose to the clipboard as a PoseStamped json message.
2. Format message - In SETTINGS -> PILOT, create a new command and paste in the body and format it correctly for either a waypoint pose or a path of multiple poses.
3. Run command - When you press C to show commands when you are piloting, you will see waypoint and path commands in the list.

Detailed Steps

Below are specific details on the different ways to create poses and paths as commands.

Find the Robot's Location

The robot's pose is always in the bottom right corner of the pilot map screen and can be copied to the clipboard as a geometry_msgs/PoseStamped JSON payload by pressing P.

Robot's Pose

The robot's pose is represented by a linear position and angular orientation for the robot. You will usually want to use a PoseStamped message, which also includes timing information and, importantly, a frame_id, so you can specify which frame of reference in the transform tree the position is relative to.

{
    "header": {
        "stamp": {
            "secs": 0,
            "nsecs": 0
        },
        "frame_id": "map",
        "seq": 1
    },
    "pose": {
        "position": {
            "y": 3.824737,
            "x": 6.249238,
            "z": -0.004999
        },
        "orientation": {
            "y": 0,
            "x": 0,
            "z": -0.703663,
            "w": -0.707578
        }
    }
}

{
    "pose": {
        "position": {
            "y": 3.824737,
            "x": 6.249238,
            "z": -0.004999
        },
        "orientation": {
            "y": 0,
            "x": 0,
            "z": -0.703663,
            "w": -0.707578
        }
    }
}

Details:

• For PoseStamped messages, secs and nsecs as 0 are defaults to specify that time doesn't matter.
• Choose the frame_id which is the base frame the measurements are taken against. Currently, the numbers you receive are relative to the world frame, so "map" is a good one to use if you have it in your transform tree. (In the future this will allow arbitrary TF base frames)
• Set seq to 1.

Paths - An array of Poses

You can also use a slightly larger message where you specify an array of poses you want the robot to go through. This allows you to set multiple waypoints for the robot to navigate between, such as driving to each room in an office or heading back to a location on a farm by driving on the road through 10 turns, not the fields.

{
    "header": {
        "stamp": {
            "secs": 0,
            "nsecs": 0
        },
        "frame_id": "map",
        "seq": 1
    },
    "poses": [
        {
          "position": {
            "y": 3.824737,
            "x": 6.249238,
            "z": -0.004999
          },
          "orientation": {
            "y": 0,
            "x": 0,
            "z": -0.703663,
            "w": -0.707578
          }
        },
        {
          "position": {
            "y": 3.824737,
            "x": 1.312322,
            "z": -0.004999
          },
          "orientation": {
            "y": 0,
            "x": 0,
            "z": -0.703663,
            "w": -0.707578
          }
        }
    ]
}

A PoseArray message is very similar to a PoseStamped message, just with an array of poses where you can specify one or more pose elements.

Saving a Waypoint or Path Command

1. Position the robot

The easiest way to create a waypoint or path is to have the robot drive to that location, with you controlling it. Once there, you have the exact coordinates and orientation you need.

Remember to align the robot correctly, so if you have a future pose at a different location, this pose is pointing in the correct direction.

2. Copy Pose to clipboard

To save a new command, first, either position the robot in the correct location and orientation or click the waypoint button when piloting in a new location while piloting and then press P to copy the robot's or waypoint's current pose to the clipboard.

3. Create a new Command

Now, go to the device's SETTINGS -> PILOT then click ADD NEW COMMAND. Choose the topic name and set a topic type of geometry_msgs/Pose, geometry_msgs/PoseStamped, geometry_msgs/PoseArray and then paste in the payload.

geometry_msgs/Pose

Just paste in and delete the header element from the JSON in the clipboard.

geometry_msgs/PoseStamped

Paste in exactly as it is.

geometry_msgs/PoseArray

We recommend pasting this into a code editor to format it before pasting in to the Edit Command dialog. You should keep the header the same as it is in the clipboard, but add a "poses": [ ] section where you paste in the current pose without any header.

You can then either move the robot or the navigation waypoint to a new location, copy that location and paste in just the pose as a subsection of the "poses" element.

You can see an example of this formatting above.

4. Order the command in the list correctly

The first 10 commands all have keyboard shortcuts and we recommend specifying your most important commands with the lowest numbers, so they stay with the same shortcut, allowing operators to easily remember what to press or where to click.

Triggering a Path Command

Now, when an operator takes over a robot then presses C, they will see the commands with their shortcuts and the waypoints will show with an additional icon.