Tutorial: Using the ROB 102 Navigation Web App

Before you start, make sure you have followed the Setup Instructions. You will need to have VSCode, Docker and Git installed (if using Windows, you will also need Git Bash) in order to complete this tutorial.

You will need to have accepted the assignment and cloned the Autonomous Navigation template code to follow this tutorial.

This page has the following parts:

Using the web app

Running the web app

For Projects 2 and 3, you will be running your code in a Docker container. The web app will run in the same Docker container. The Docker image includes all the dependencies you need to write your code and run the app, so you only need to have Docker installed to get started.

Open VSCode, and open the directory that you cloned using "File" > "Open Folder...". Navigate to where you cloned your repository, and select it. You should see your folder and all the files it contains the VSCode's Explorer . Open a terminal using "Terminal" > "New Terminal". The terminal should open in the root of your code directory. If you are using Windows, make sure you are using a Bash terminal (the VSCode setup instructions explained to how make Bash your default terminal). Now, build the Docker image by running the script provided in your VSCode terminal:

./docker_build.sh
  • Hint: If you see an error that says E: Release file for <ADDRESS> is not valid yet [...] when building the image, your system clock might be mismatched with Docker's clock. Try restarting Docker, and if that doesn't work, restart your computer.

To run the Docker container, in your VSCode terminal, do:

./docker_run.sh

You should see a container called rob102-navigation running under "Docker Containers" in VSCode's Explorer, if you have installed the Docker extensions for VSCode.

  • Hint: If you want to update the web app, for example, if you have added new map files under the data/ directory or you want to update the version of the web app code, you must stop the container and build it again, using ./docker_build.sh. You do not need to rebuild the image if you change the code in the autonomous_navigation/ directory of the repository.

How to use the web app

When Docker is running, you should see the app, as shown below, when you navigate to http://localhost:8000 in your browser.

The webapp has the following features:

  • Upload a map: Use the "Choose File" button to navigate to a map file. The app supports any file with the .map extension, but the C++ server only supports the ones in the data folder in the code template. Make sure you pick a file with the .map extension, not an image. The Upload Map button loads the map for visualization. If the C++ server is connected, it also sends the map to the server, which will load the map and call potential field functions.
  • Algorithm selection: Use the dropdown menu to select the algorithm you would like to use for path planning. If the code for that algorithm isn't implemented, no path will be planned.
  • Plan a path: The Plan! button calls your path planning functions for the chosen algorithm. You can set the goal location by clicking on the map, which will turn that cell yellow. You can drag the robot to change the start location. When you click on Plan! the goal cell will turn green if it is valid and your path planning function will be triggered. If the goal is not valid, the cell will turn red. The Plan! button only works if a map is loaded, a valid goal is selected, and the backend is connected. Otherwise, it won't do anything.

Stopping the web app

You can stop the container by right-clicking on the running container under "Docker Containers" in the file explorer and selecting "Stop".

Writing & running your code

You will be writing code in the autonomous_navigation directory in your repository. This directory is mounted in the Docker container. When you modify the files in VSCode from your computer, those changes will be reflected in the Docker container as well.

To use the web app to test your code, you will compile and execute your code in the Docker container. To do this, you will open a terminal inside the container. Right-click on the running docker image under "Docker Containers" in VSCode and select "Execute in bash." This will open up a terminal which you can use to interact with the container.

To compile the code, inside the VSCode terminal in the container, first enter into the build directory for this project, where we will be storing all the binaries and build files:

cd /code/build

We will use CMake to compile the code, which will help find the dependencies and link them to our code during compilation. This is a two step process:

cmake ..
make

The cmake command sets up our project for compilation by finding all the libraries and compilers we need. The argument .. points to the directory one folder back from the current folder (in this case, /code/), where the file CMakeLists.txt is stored. This gives CMake instructions about how to compile the code. The make command performs the compilation. Generally, you only have to run cmake once. The make command needs to be rerun every time you modify the code.

The build folder is also mounted from your computer into the Docker container. This allows the build files to be saved to your computer so you don't need to rerun the cmake command every time you restart the container.

We have provided code in web_server.cpp which communicates with the app and calls the functions that you will be writing in Projects 2 and 3. It opens up a websocket that connects to the app. When you upload a map and send a planning goal, the server will load the map and call the planning functions for you. When the plan is found, the server will send the plan to the app to display. To run the server, in the Docker container, within the build directory, do:

./nav_app_server

You should see a message when the connection is open, and the status message on the app should turn green and say "Connected." Right now, we haven't written any code so the app won't do much. You are now ready to complete Project 2 and Project 3!