Running the Navigation Stack with Isaac AMR Cloud Services

This section will guide you through the process of running the Isaac AMR Cloud Services with Isaac AMR cloud Services, which is an intelligent platform that organizes a fleet of autonomous mobile robots to function robustly and safely in large, dynamic, unstructured environments among humans.

To run the navigation app with Isaac AMR Cloud Services, you will need the following:

• A cuOpt client ID and secret to access cuOpt Connect. For more information, refer to instructions on the Isaac AMR Software Page.

• An occupancy map and an optional semantic map. One of the following is required:

• Access to NVIDIA NGC to download containers. Please refer to the documentation on NGC and API keys for more information.

• A server/workstation to run the Isaac AMR Cloud Services software that has Docker installed.

  • Some services run unencrypted and unauthenticated. Depending on your organization’s security policies, you may need to network isolate the Isaac AMR Cloud Services software.

1. Download the tutorial assets from NGC.

   This can be done via web browser on https://ngc.nvidia.com by searching “Isaac Cloud Tutorial” in the “Resources” section of the NGC private registry. You can also use the NGC CLI:

   Copy

   Copied!

               
   
               
   ngc registry resource download-version <your_staging_area>/isaac_cloud_tutorial_1:4
           

   Unzip the folder and cd into tutorials.

   Note

   Replace <your_staging_area> with your assigned NGC Registry staging area code.

2. Verify the robot name.

   In defaults.yaml, update the name of the robot in the robots section.

   Copy

   Copied!

               
   
               
   robots:
     - name: "your_robot_name"
       labels: ["test", "carter", "gxf"]
       heartbeat_timeout: 30
           

3. Set the cuOpt and DeepMap credentials using one of the following methods.

4. Set the source of the map.

   In defaults.yaml, update the map section according to the source of the map:

   • If a URI will be used to locate the map, set map_uri to the URI and update the metadata section according to your map. Ensure the map is the same map that the navigation app will be loading.

     Copy

     Copied!

                 
     
                 
     map:
       # A map URI uniquely identifies the location of the map on the internet.
       map_uri: https://your.server.com/your/map/image.png
       metadata:
         # Unique ID of the map
         map_id: "your_map_id"
         # Resolution is pixels per meter and should match the occupancy map you use
         resolution: 0.05          # required for occupancy map
         # The occupancy threshold used to identify if a cell is occupied or not.
         # If the pixel value is less than this threshold, it is occupied; otherwise, it is free
         occupancy_threshold: 129  # range between [0 to 255]
         # Translation in the form "x,y,z"
         translation: "0,0,0"
         # Rotation in quaternion, in the form "x,y,z,w"
         rotation: "0,0,0,1"
             

   • If the map will be served by DeepMap, update the map section as follows:

     Copy

     Copied!

                 
     
                 
     map:
        map_server:
        NVIDIA_DEEPMAP:
           # Map cache directory
           map_dir: "/tmp/config/data"
           # Map server config directory
           config_dir: "/tmp/config/etc"
           # Unique identifier of the map tile
           tile_identifier:
              # Unique ID of the map
              map_id: "your-map-id"
              # Available types: TILE_TYPE_UNKNOWN, TILE_TYPE_OCCUPANCY_2D, TILE_TYPE_SEMANTIC
              tile_type: TILE_TYPE_OCCUPANCY_2D
              # ID of the tile in the form "x,y,z"
              tile_id: "0,0,0"
           # Map server query interval
           query_interval: 100  # seconds
             

   If DeepMap is used, in /etc/vehicle_info.pb.txt, update the customer_id and vehicle_id with the data that will be sent by NVIDIA Isaac DeepMap team after the mapping process is completed.

5. Pull the latest containers from NGC and then run the Docker compose file.

   Copy

   Copied!

               
   
               
   docker login nvcr.io
   docker compose -f bringup_isaac_cloud.yaml pull
   docker compose -f bringup_isaac_cloud.yaml up
           

   You have now launched the Isaac AMR Cloud Services. For additional usage, please refer to Mission Control API.

   Note

   If you have other services running locally and need to adjust ports, you can edit .env to customize your execution.

6. To bring down the Isaac AMR Cloud Services, you can press Ctrl+C in the terminal where you ran docker compose -f bringup_isaac_cloud.yaml up or run docker compose -f bringup_isaac_cloud.yaml down in a separate terminal from the tutorials directory.

The navigation app will need to access tutorials/etc to connect to the Isaac AMR Cloud Services, whether it is running on Carter or in simulation. If you are running the navigation app on Carter, copy all the files from tutorials/etc to it.

            

            
scp -r tutorials/etc nvidia@<ROBOT IP>:<path/to/tutorials/etc>
        

Add and update the following fields in your navigation app configuration.

            

            
robot_name: <your_robot_name>
cloud_host: <ip_to_isaac_amr_cloud_services>
route_planner: cloud
        

Set the value of physics_engine to match your needs.

Note that the robot_name refers to the specific name of your robot, while the robot field is the type of robot being used with the navigation stack. For additional arguments, you can refer to NAV stack CLI.

If the map will be loaded from the disk, set omap_path, omap_cell_size and semantic_map_path (if needed) to your desired value. If the map will be downloaded from DeepMap, add the following to your navigation app configuration.

            

            
tile_config:
  map_dir: /tmp  # or your desired location to store cached data
  config_dir: <path/to/tutorials/etc>
        

omap_path and semantic_map_path are ignored when tile_config is present. The map will only be loaded when the robot is connected to the cloud.

The following are example configurations:

• Using real robot with deepmap server

  Copy

  Copied!

              
  
              
  robot_name: robot_a
  physics_engine: real-world
  cloud_host: localhost
  route_planner: cloud
  tile_config:
    map_dir: /tmp/etc
    config_dir: /tmp/etc
          

• Using real robot with an occupancy map file

  Copy

  Copied!

              
  
              
  robot_name: robot_a
  physics_engine: real-world
  cloud_host: localhost
  route_planner: cloud
  omap_path: /tmp/map.png
  omap_cell_size: 0.05
          

Follow the tutorial according to your platform (Flatsim, Isaac Sim, or Carter) to run the navigation Docker container. Here is an example command if you are running the app on Carter:

            

            
docker run -it --gpus all --rm --network=host --privileged \
  -v /dev:/dev \
  -v /sys:/sys \
  -v /tmp:/tmp \
  -v <path/to/tutorials/etc>:<path/to/tutorials/etc> \
  -e DEEPMAP_VEHICLE_TOKEN=<YOUR_DEEPMAP_SECRET_TOKEN> \
  nvcr.io/<your_staging_area>/navigation_stack:isaac_2.0-aarch64 \
  -c /tmp/navigation_stack_configuration.yaml
        

If the map is served on the DeepMap server, make sure you set the DEEPMAP_VEHICLE_TOKEN environment variable when starting up the navigation docker container by passing an additional -e DEEPMAP_VEHICLE_TOKEN=<YOUR_DEEPMAP_SECRET_TOKEN> to the docker run command.

Navigate to http://localhost:8050/api/v1/docs (adjust the URL for your setup). Use the /mission/submitMission endpoint to submit missions.

The mission samples are shown below:

            

            
mission_id = "Sample Mission1"
mission_template = "simple_navigation_mission"
Request Body:
{"route": [{"x":21.5, "y":8.9}]}
        

            

            
mission_id = "Sample Mission2"
mission_template = "simple_navigation_mission"
Request Body:
{
   "start_location": {"x":20.3, "y":10.1},
   "end_location" : {"x":20.3, "y":10.1},
   "route" : [{"x":21.5, "y":8.9},
               {"x":20.3, "y":10.1},
               {"x":29,   "y":20.9}
            ],
   "iterations": 3
}
        

The request body contains information about the robot’s route, which includes a series of waypoints, and each waypoint is defined by x, y, and z coordinates. For 2D maps, the z coordinate is optional and defaults to 0.0.

Additionally, there are three optional parameters: start_location, iterations, and end_location. These parameters come into play when the robot needs to start from a specific point, execute multiple iterations within the environment, and ultimately end at a different point. For more in-depth information about the API and examples, refer to the Mission Control API Reference.

Once the request is submitted, you should see the robot following a route towards the goal.

Once the Navigation Stack is running, you can select positions on Isaac Sight to construct your mission:

1. Open Isaac Sight in your web browser. If you are using a Carter robot, go to https://<robot-ip>:3000. If using Isaac Sim or Flatsim, go to https://localhost:3000, or replace localhost with the IP address of the machine on which navigation stack app is running.

2. After the map is downloaded to the navigation stack, find the pose marker for #_<robot_name>/goal_frame in the “Global Map” window. The text shows up when you hover the marker. Click and drag it to a desired point on the map, and then click elsewhere for the new pose to be registered. If the pose marker is not displaying, follow these steps:

   1. Right click on the occupancy map image and select “Settings”.

   2. Click on the “Select marker” dropdown menu.

   3. Find and select #_<robot_name>/goal_frame (interactive).

   4. Click “Add marker”.

   5. Click “Update”.

   6. You should now see Marker: #_<robot_name>/goal_frame in the list of channel and marker names below the occupancy map image. The marker should also show up on the occupancy map image.

3. On the left panel, select “PoseTree”.

4. In the “Pose Tree” window, find “world” and “robot/goal_frame”. Click “world” and then “robot/goal_frame”. You will see a coordinate transform from the world to robot/goal_frame. This tells you the coordinates of the point you picked from Step 2 in the world frame. Keep the X and Y values in your notes.

5. Repeat Steps 2 to 4 until you construct your mission.

If you do not wish to launch the entire Isaac AMR Cloud Services, but still need to download the map from the DeepMap server with the navigation app, follow the steps below:

1. Follow the instruction from here to acquire DeepMap API client credentials.

2. Download the tutorial assets from NGC, and set DeepMap credentials. If you are running the navigation app on Carter, copy all the files from tutorials/etc to it.

   Copy

   Copied!

               
   
               
   scp -r tutorials/etc nvidia@<ROBOT IP>:<path/to/tutorials/etc>
           

3. Obtain the map ID, tile ID, and tile version of the map the navigation app will be using. The occupancy and semantic maps have different tile versions.

4. Add the following to your navigation configuration:

            

            
tile_config:
  map_dir: /tmp  # or your desired location to store cached data
  config_dir: <path/to/tutorials/etc>
  map_id: <map-id>
  tile_id: [<x>, <y>, <z>]  # x, y, z are integers
  occupancy_tile_version: <occupancy-tile-version>
  semantic_tile_version: <semantic-tile-version>
        

5. Launch the navigation container with an additional argument -e DEEPMAP_VEHICLE_TOKEN=<YOUR_DEEPMAP_SECRET_TOKEN> to the docker run command and start the navigation app.

   Copy

   Copied!

               
   
               
   docker run -it --gpus all --rm --network=host --privileged \
      -v /dev:/dev \
      -v /sys:/sys \
      -v /tmp:/tmp \
      -v <path/to/tutorials/etc>:<path/to/tutorials/etc> \
      -e DEEPMAP_VEHICLE_TOKEN=<YOUR_DEEPMAP_SECRET_TOKEN> \
      nvcr.io/<your_staging_area>/navigation_stack:isaac_2.0-<platform> \
      -c /tmp/navigation_stack_configuration.yaml
           

Refer to Troubleshooting Isaac AMR Cloud Services for more help with this tutorial.