The Navigation Service

The navigation service is the stateful definition of Viam’s motion service. It uses GPS to autonomously navigate a rover base to user-defined endpoints called waypoints. Configure your base with a navigation service, add waypoints, and set the mode of the service to Waypoint to move your rover along a defined path at your desired motion configuration.

Used with

Base*

Movement Sensor*

Camera

* Required for use

Requirements

You must configure a base with movement sensors as part of your machine to configure a navigation service.

To use the navigation service, configure a stack of movement sensors that implement the following methods in their models' implementations of the movement sensor API:

• GetPosition()
• GetCompassHeading()
• GetProperties()

The base should implement the following:

• SetVelocity()
• GetGeometries()
• GetProperties()

See navigation concepts for more info on how to implement and use movement sensors taking these measurements.

Configuration

• Config Builder
• JSON Template
• JSON Example

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Service. Select the navigation type. Enter a name or use the suggested name for your service and click Create.

Edit the attributes as applicable to your machine, according to the table below.

"services": [
{
    "name": "your-navigation-service",
    "type": "navigation",
    "attributes": {
        "store": {
            "type": "<your-store-type>"
        },
        "movement_sensor": "<your-movement-sensor>",
        "base": "<your-base>",
        "obstacle_detectors": [
          {
          "vision_service": "<your-vision-service>",
          "camera": "<your-camera>"
          }
        ]
    }
}
    ... // Other services
]

{
  "name": "test_navigation",
  "type": "navigation",
  "attributes": {
    "store": {
      "type": "mongodb",
      // Remove "config": { ... } below if using "type": "memory"
      "config": {
        "uri": "mongodb://127.0.0.1:12345"
      }
    }
  },
  "movement_sensor": "your-movement-sensor",
  "obstacle_detectors": [
    {
      "vision_service": "your-vision-service",
      "camera": "your-camera"
    },
    {
      "vision_service": "your-vision-service-2",
      "camera": "your-camera-2"
    }
  ]
  "base": "your-base",
  "obstacles": [
    {
      "geometries": [
        {
          "label": "your-label-for-this-obstacle",
          "orientation": {
            "type": "ov_degrees",
            "value": {
              "x": 1,
              "y": 0,
              "z": 0,
              "th": 90
            }
          },
          "x": 10,
          "y": 10,
          "z": 10
        }
      ],
      "location": {
        "latitude": 1,
        "longitude": 1
      }
    }
  ]
}

Edit and fill in the attributes as applicable. The following attributes are available for Navigation services:

Configure and calibrate the frame system service for GPS navigation

To make sure your rover base’s autonomous GPS navigation with the navigation service is accurate, configure and calibrate the frame system service for the components of your machine.

Configure

Add a nested reference frame configuration to your rover base and movement sensor:

• Navigate to the CONFIGURE tab of your machine’s page in the Viam app and select the Frame mode.

• From the left-hand menu, select your base.

• Since you haven’t adjusted any parameters yet, the default reference frame will be shown for your base:

  

• Keep the parent frame as world. Select the Geometry dropdown menu.

• Configure a Geometry for the base that reflects its physical dimensions. Measure the physical dimensions of your base and use them to configure the size of your geometry. Units are in mm.

  For example, you would configure a box-shaped base with dimensions of 100mm x 100mm x 100mm (l x h x w) as follows:

  

• Next, select your movement sensor from the left-hand menu. Click on the Parent menu and select your base component.

• Give the movement sensor a Translation that reflects where it is mounted on your base, measuring the coordinates with respect to the origin of the base. In other words, designate the base origin as (0,0,0) and measure the distance between that and the origin of the sensor to obtain the coordinates.

  For example, you would configure a movement sensor mounted 200mm on top of your base as follows:

  

You can also adjust the Orientation and Geometry of your movement sensor or base, if necessary. See the frame system service for instructions.

Calibrate

Then, to calibrate your frame system for the most accurate autonomous GPS navigation with the navigation service:

• After configuring your machine, navigate to the CONTROL tab and select the card matching the name of your movement sensor.
• Monitor the readings displayed on the card, and verify that the compass or orientation readings from the movement sensor report 0 when the base is facing north.
• If you cannot verify this:
  • Navigate back to your machine’s CONFIGURE tab and Frame subtab. Scroll to the card with the name of your movement sensor. Adjust the Orientation of the frame to compensate for the mismatch.
  • Navigate back to the movement sensor card on your CONTROL page, and confirm that the compass or orientation readings from the movement sensor now report 0 when the base is facing north, confirming that you’ve successfully calibrated your machine to be oriented accurately within the frame system.
  • If you cannot verify this, repeat as necessary.

API

The navigation service supports the following methods:

Mode

Get the Mode the service is operating in.

There are two options for modes: MODE_MANUAL or MODE_WAYPOINT.

• MODE_WAYPOINT: Start to look for added waypoints and begin autonomous navigation.
• MODE_MANUAL: Stop autonomous navigation between waypoints and allow the base to be controlled manually.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get the Mode the service is operating in
await my_nav.get_mode()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Get the Mode the service is operating in
mode, err := myNav.Mode(context.Background(), nil)

SetMode

Set the Mode the service is operating in.

There are two options for modes: MODE_MANUAL or MODE_WAYPOINT.

• MODE_WAYPOINT: Start to look for added waypoints and begin autonomous navigation.
• MODE_MANUAL: Stop autonomous navigation between waypoints and allow the base to be controlled manually.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Set the Mode the service is operating in to MODE_WAYPOINT and begin
# navigation
await my_nav.set_mode(Mode.ValueType.MODE_WAYPOINT)

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Set the Mode the service is operating in to MODE_WAYPOINT and begin navigation
mode, err := myNav.SetMode(context.Background(), Mode.MODE_WAYPOINT, nil)

Location

Get the current location of the robot in the navigation service.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get the current location of the robot in the navigation service
location = await my_nav.get_location()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Get the current location of the robot in the navigation service
location, err := myNav.Location(context.Background(), nil)

Waypoints

Get an array of waypoints currently in the service’s data storage. These are locations designated within a path for the robot to navigate to.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get a list containing each waypoint stored by the navigation service
waypoints = await my_nav.get_waypoints()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Get an array containing each waypoint stored by the navigation service
waypoints, err := myNav.Waypoints(context.Background(), nil)

GetProperties

Get information about the navigation service.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get the properties of the current navigation service.
nav_properties = await my_nav.get_properties()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Get the properties of the current navigation service
navProperties, err := myNav.Properties(context.Background())

AddWaypoint

Add a waypoint to the service’s data storage.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Create a new waypoint with latitude and longitude values of 0 degrees
location = GeoPoint(latitude=0, longitude=0)


# Add your waypoint to the service's data storage
await my_nav.add_waypoint(point=location)

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Create a new waypoint with latitude and longitude values of 0 degrees
location = geo.NewPoint(0, 0)

// Add your waypoint to the service's data storage
err := myNav.AddWaypoint(context.Background(), location, nil)

RemoveWaypoint

Remove a waypoint from the service’s data storage. If the robot is currently navigating to this waypoint, the motion will be canceled, and the robot will proceed to the next waypoint.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Remove the waypoint matching that ObjectID from the service's data storage
await my_nav.remove_waypoint(waypoint_id)

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Create a new ObjectID
waypoint_id = primitive.NewObjectID()

// Remove the waypoint matching that ObjectID from the service's data storage
err := myNav.RemoveWaypoint(context.Background(), waypoint_id, nil)

Obstacles

Get an array or list of the obstacles currently in the service’s data storage. These are objects designated for the robot to avoid when navigating. These include all transient obstacles which are discovered by the vision services configured for the navigation service, in addition to the obstacles that are configured as a part of the service. See the motion service for more information.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get a list containing each obstacle stored by the navigation service
obstacles = await my_nav.get_obstacles()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Get an array containing each obstacle stored by the navigation service
obstacles, err := myNav.Obstacles(context.Background(), nil)

Paths

Get each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the machine’s motion planning.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get a list containing each path stored by the navigation service
paths = await my_nav.get_paths()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

// Get an array containing each path stored by the navigation service
paths, err := myNav.Paths(context.Background(), nil)

DoCommand

Execute model-specific commands that are not otherwise defined by the service API. For built-in service models, any model-specific commands available are covered with each model’s documentation. If you are implementing your own navigation service and add features that have no built-in API method, you can access them with DoCommand.

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

my_command = {
  "command": "dosomething",
  "someparameter": 52
}

await my_nav.do_command(my_command)

myNav, err := navigation.FromRobot(robot, "my_nav_service")

resp, err := myNav.DoCommand(ctx, map[string]interface{}{"command": "dosomething", "someparameter": 52})

Close

Safely shut down the resource and prevent further use.

my_nav = NavigationClient.from_robot(robot, "my_nav_service")

await my_nav.close()

myNav, err := navigation.FromRobot(robot, "my_nav_service")

err := myNav.Close(ctx)

Control tab usage

After configuring the navigation service for your machine, navigate to the CONTROL tab of the machine’s page in the Viam app and expand the card matching the name of your service to use an interface for rover navigation.

Here, you can toggle the mode of the service between Manual and Waypoint to start and stop navigation, add waypoints and obstacles, and view the position of your rover base on a map:

Navigation concepts

The following concepts are important to understand when utilizing the navigation service. Each concept is a type of relative or absolute measurement, taken by a movement sensor, which can then be utilized by your machine to navigate across space.

Here’s how to make use of the following types of measurements:

• Compass Heading
• Orientation
• Angular Velocity
• Position
• Linear Acceleration
• Linear Velocity

Compass heading

The following models of movement sensor take compass heading measurements:

• gps-nmea - some GPS hardware only report heading while moving.
• gps-nmea-rtk-pmtk - some GPS hardware only report heading while moving.
• gps-nmea-rtk-serial - some GPS hardware only report heading while moving.
• imu-wit

An example of a CompassHeading reading:

// heading is a float64 between 0-360
heading, err := gps.CompassHeading(context.Background, nil)

Use compass heading readings to determine the bearing of your machine, or, the cardinal direction that your machine is facing.

To read compass headings, configure a capable movement sensor on your machine. Then use the movement sensor API’s GetCompassHeading() method to get readings from the sensor.

Orientation

The following models of movement sensor take orientation measurements:

• imu-wit
• wheeled-odometry

An example of an Orientation reading:

// orientation is a OrientationVector struct with OX, OY, OZ denoting the coordinates of the vector and rotation about z-axis, Theta
orientation, err := imuwit.Orientation(context.Background, nil)

Use orientation readings to determine the orientation of an object in 3D space as an orientation vector. An orientation vector indicates how it is rotated relative to an origin coordinate system around the x, y, and z axes. You can choose the origin reference frame by configuring it using Viam’s frame system. The GetOrientation readings will report orientations relative to that initial frame.

To read orientation, first configure a capable movement sensor on your machine. Additionally, follow these instructions to configure the geometries of each component of your machine within the frame system. Then use the movement sensor API’s GetOrientation() method to get orientation readings.

Angular velocity

The following models of the movement sensor component take angular velocity measurements:

• imu-wit
• wheeled-odometry
• gyro-mpu6050

An example of an AngularVelocity reading:

// angularVelocity is an AngularVelocity r3 Vector with X, Y, and Z magnitudes
angularVelocity, err := imu.AngularVelocity(context.Background, nil)

Use angular velocity readings to determine the speed and direction at which your machine is rotating.

To get an angular velocity reading, first configure a capable movement sensor on your machine. Then use the movement sensor API’s GetAngularVelocity() method to get angular velocity readings from the sensor.

Position

The following models of the movement sensor component take position measurements:

• gps-nmea
• gps-nmea-rtk-pmtk
• gps-nmea-rtk-serial
• wheeled-odometry

An example of a Position reading:

// position is a geo.Point consisting  of Lat and Long: -73.98 and an altitude in float64
position, altitude, err:= imu.Position(context.Background, nil)

Use position readings to determine the GPS coordinates of an object in 3D space or its position in the geographic coordinate system (GCS). These position readings reflect the absolute position of components.

To get a position, configure a capable movement sensor on your machine. Then use the movement sensor API’s GetPosition() method to get position readings from the sensor.

Linear velocity

The following models of movement sensor take linear velocity measurements:

• gps-nmea
• gps-nmea-rtk-pmtk
• gps-nmea-rtk-serial
• wheeled-odometry (provides a relative estimate only based on where the base component has started)

An example of a LinearVelocity reading:

// linearVelocity is an r3.Vector with X, Y, and Z magnitudes
linearVelocity, err := imu.LinearVelocity(context.Background, nil)

Use linear velocity readings to determine the speed at which your machine is moving through space.

To get linear velocity, configure a capable movement sensor on your machine. Then use the movement sensor API’s GetLinearVelocity() method to get linear velocity readings from the sensor.

Linear acceleration

The following models of movement sensor take linear acceleration measurements:

• accel-adxl345
• imu-wit
• gyro-mpu6050

An example of a LinearAcceleration reading:

// linearAcceleration is an r3.Vector with X, Y, and Z magnitudes
linearAcceleration, err := imu.LinearAcceleration(context.Background, nil)

You can use linear acceleration readings to determine the rate of change of the linear velocity of your machine, or, the acceleration at which your machine is moving through space.

To get linear acceleration, configure a capable movement sensor on your machine. Then use the movement sensor API’s GetLinearAcceleration() method to get linear acceleration readings from the sensor.

Next steps

If you would like to see the navigation service in action, check out this tutorial: