Learning

Click on the following link to see Team AMORE's Technical Paper for the Roboboat 2023 Competition:

Design and Development of an Autonomous Kayak for the 2023 Roboboat Competition

Click on the following link to see Team AMORE's Team Introduction Video for the Roboboat 2023 Competition:

Team AMORE Introduction Video

Click on the following link to see Team AMORE's Design Presentation for the 2022 RobotX Competition:

Team AMORE: RobotX 2022

Click on the following link to see Team AMORE's Technical Paper for the RobotX Competition:

Development of an Autonomous Maritime System for the 2022 RobotX Challenge

Click on the following link to see Team AMORE's Team Introduction Video for the RobotX 2022 Competition:

Team AMORE Introduction Video

VRX User Manual

1.0 General Information

Before beginning the VRX tutorials, make sure you have a linux system that can run ROS (robot operating system) on your host machine. To do this go to the following website: http://wiki.ros.org/ROS/Installation and install the latest version of ROS. For the 2022 VRX competition, we used ROS Noetic. For future competitions, the recommended ROS version may be something different, so check with the VRX staff. A recommended video for dual booting a windows 10 system can be found at: https://www.youtube.com/watch?v=-iSAyiicyQY. This is just an example video that some of the group members followed; there are many others available on youtube.

1.1 System Setup 

To begin, go to the following link: https://github.com/osrf/vrx/wiki. Select tutorials, system setup, and Option A: Configure Your Host Machine. You could also use a docker image, but this is not recommended. Continue following the tutorial by running all the commands in your terminal window.

1.2 VRX Interfaces and Customization

The VRX community gives some tutorials of methods on how to drive the boat, which can be found at: https://github.com/osrf/vrx/wiki/vrx_api_tutorials. There are also tutorials on how to customize vrx, by creating a custom WAM-V which is useful for the final submission. It also allows you to test with different WAM-V configurations. To do this, follow the instructions on the following webpage: https://github.com/osrf/vrx/wiki/customizing_vrx_tutorials. 

1.3 Setting up Team AMORE’s 2022 VRX workspace 

By now, you should have ROS installed and be able to run gazebo with some example environments. The team’s github can be found at: https://github.com/lssuamore/vrx_amore. If you are logged in on another account you will need to sign out and sign into the teams account To login into github, use the following username: amore@lssu.edu and password: robotx2022. Follow the README.md file to clone the package and get it up and running. A common error that is encountered is when a ROS custom message can not be found. 

This occurs when the ROS compiler tries to compile a code file before the ROS custom messages. To eliminate this, comment out all of the (add_executable) and (target_link_libraries) files in the CMakeLists.txt file and catkin_make again. After this is completed, uncomment the same files and catkin_make once again and everything should build. 

Video: Repo Setup VRX.mp4

1.4 Repository Structure 

See below all of the ROS nodes within the programs that were used for the VRX 2022 competition tasks 1-4.

The setup of the code uses one ROS .launch file to launch the geonav_transform package, and 5 .cpp executables. The geonav_transform package is used for converting ECEF latitude longitude coordinates to a local NED fixed frame to work out of. The 5 .cpp executables include mission_control, path_planner, navigation_array, perception_array, and propulsion_system. The mission_control monitors the state of the current VRX task and sets the states of the other executables. path_planner was designed to handle computing trajectories and feeding them to the propulsion_system. navigation_array publishes ECEF states to nav_odom so that geonav_transform is able to subscribe and publish its conversion to a local ENU frame to "geonav_odom". navigation_array subscribes to all the VRX task topics because the units of objects and poses given by VRX are in ECEF units and need conversion to the local NED working frame. All conversions happen in navigation_array because conversions have to be done by publishing to the "nav_odom" node, and this can't be done from multiple executables unless perhaps different namespaces are used. perception_array uses OpenCV to do image processing through the use of two singular lense cameras placed on the USV payload tray. propulsion_system handles outputting the angles and thrusts to the motors. Currently, the propulsion_system is only using a station-keeping controller designed for a dual-azimuthing controller.

1.4.1 Launching 

How to launch the code used for the vrx competition is shown step by step below as well as in a video. By this point in the tutorial you should have a working repository that catkin_makes without any errors. If not please follow section 1.3 on how to set up team AMORE’s 2022 VRX workspace.

1. Since the code uses a certain topic that it subscribes to vrx/task/info , you will need to launch the example world for each task. If you try to launch the general vrx world using roslaunch vrx_gazebo vrx.launch, the code won’t do anything because the topic vrx/task/info isn't present in that world.

2. See below the list of commands to launch each of the separate task worlds. Once launched, gazebo should open and you should see the appropriate task that you launched. 

   1. roslaunch vrx_gazebo station_keeping.launch

   2. roslaunch vrx_gazebo wayfinding.launch

   3. roslaunch vrx_gazebo perception_task.launch

   4. roslaunch vrx_gazebo wildlife.launch

   5. roslaunch vrx_gazebo gymkhana.launch

   6. roslaunch vrx_gazebo scan_dock_deliver.launch

3. Once gazebo is open and the task is shown, the code can be launched. To do this, see the command below.

   1. roslaunch amore VRX_AMORE.launch

Video: VRX Launch.mp4

1.5 Docker submission

The VRX docker tutorials can be found at the following link: https://github.com/osrf/vrx/wiki/tutorials-vrx_make_competitor_image. Following tutorial will cover how to do option 1. Some important commands that the team used during submission are as follows:

• docker cp <your_local_file> <container_name>:/path/to/file/in/container/ 

  • Copies files from your local machine into the docker container 

• docker run -it --entrypoint /bin/bash ${USERNAME}/${IMAGE_NAME}:${TAG}

  • This commands lets you access the inside of your container to make edits

  • Since the entrypoint will be set to ros_entrypoint.sh everytime you run your container, it will just run the .sh file. This command will bypass that and bring up the bash script.

• docker commit --change='ENTRYPOINT ["/ros_entrypoint.sh"]' {container_id} ${USERNAME}/${IMAGE_NAME}:${TAG}

  • This commits the container updates and sets /ros_entrypoint.sh back to the entrypoint of the container

  • Example run_my_system.bash file 

• docker history imagename

• docker tag 2844 imagename #

• docker exec -it containername bash

  • Follow the above commands if you need to revert your image due to crashing

1.5.1 Docker Step by Step

First, start with a clean container with ros noetic as a base by typing the following command in the terminal window.

1. docker run --name my_container -it ros:noetic-ros-base

my_container is the name of your container and you can choose what you want.

Your terminal prompt should change to an interactive bash session like below. Then, install your text editor of choice

1. apt update && apt install -y nano

Replace nano with your text editor of choice, but for now we used nano.

Use the text editor to edit the ros_entrypoint.sh file

1. nano /ros_entrypoint.sh

Copy the file below– yours should look exactly the same as shown.

Open the run_my_system.bash file

1. nano /run_my_system.bash

See the example below of what the team used. Your source might be something different depending on what your repository is called. Your launch file also might be something different, but it should resemble the same command you would use to launch from the command line.

Run to make the file executable

1. chmod +x /run_my_system.bash

Before exiting the bash shell, we need to copy the repository from the host machine onto the docker container. To do this use:

1. docker cp <your_local_file> <container_name>:/path/to/file/in/container/

  For the team we used:

1. docker cp vrx_amore my_container:/

Where my_container is the name of the container and to find this use:

1. docker container ls

Don’t exit just yet. Now, you have to catkin make the repository exactly how you would on your linux machine. This will be shown more explicitly in the video.

 After that you can now exit the container

You will now need to commit and then push your container to your docker account by following the commands below with your container information.

1. docker login 

2. docker commit -m "<Write your commit message here.>" -a ${AUTHOR_NAME} ${CONTAINER_ID} ${USERNAME}/${IMAGE_NAME}:${TAG}

3. docker push ${USERNAME}/${IMAGE_NAME}:${TAG}

AUTHOR_NAME is your name.

USERNAME must match the username of your Dockerhub account.

CONTAINER_ID must be the container id. You would have seen this when using “docker container ls”.

IMAGE_NAME should describe your image. It will be used to find your image locally and on Docker Hub.

TAG can be anything, but we recommend you use it to store version information. Start with version 1 and so on.

If you want to make changes to your image use:

1. docker run -it --entrypoint /bin/bash ${USERNAME}/${IMAGE_NAME}:${TAG}

This commands lets you access the inside of your container to make edits. Since the entrypoint will be set to ros_entrypoint.sh everytime you run your container, it will just run the .sh file. This command will bypass that and bring up the bash shell.

This is an example of ${USERNAME}/${IMAGE_NAME}:${TAG} that the team used at one point: amore2122/amore_phase3_try:v3. It can also be found on your docker hub on the docker website. You should have set all this information while using the docker commit command. 

After you edit your file, you will have to exit the bash shell by typing exit. You will have to recommit your changes by using 

1. docker commit --change='ENTRYPOINT ["/ros_entrypoint.sh"]' {container_id} ${USERNAME}/${IMAGE_NAME}:${TAG}

You should know how to use this by doing the above. To find the container id you can use “docker ps -all” to locate the container. If it has a different name than you originally named it don't be alarmed, docker changes the names.

After committing, you will then need to push your changes to docker.

1. docker push ${USERNAME}/${IMAGE_NAME}:${TAG}

You should already know how to use this from above. Username is the docker username and image name is whatever you named your image like above. Tag is the version you're working on, so in this case, it would probably be v2 if you originally pushed v1.

To submit your docker image to vrx, please follow the instructions on the following link: https://github.com/osrf/vrx/wiki/submission_process. This is the tutorial that the team followed and it is very well done and easy to follow.

Video: Docker#1.mp4

Video: Docker#2.mp4

1.5.2 Docker Example Run

To run your docker image separately, use the following command:

1. docker run -it ${USERNAME}/${IMAGE_NAME}:${TAG}

Where username is your docker username and image name is whatever you called the image. Tag is the version you want to run. When executing this command, ros should launch something like this:

Where rosmaster should begin to launch followed by whatever your code output is.

At the following link, you will see vrx tutorials on how to troubleshoot and run the container: https://github.com/osrf/vrx/wiki/tutorials-vrx_docker_troubleshooting. 

The following tutorial will be covered in more detail below by a video: https://github.com/osrf/vrx/wiki/vrx_2022-testing. 

Video: Docker test.mp4

1.6 GitHub

At the highest level, github is a website and cloud-based service that helps code developers store and manage their code, as well as track and control changes to their code. Team Amore used it to share code with the University of Bolzano, as well as share code between team members. The push command is used to upload new changes to the local repository, and the pull command updates your local machine with the new changes. The following will show how to push/pull new existing code from github:

Push:

1. Switch branches using git checkout. The -b indicates we are creating a new branch.

   1. git checkout -b <your name>

2. The following command adds all changes to be tracked that you changed. The -A parameter is what specifically sets everything. You can also use git rm and other similar commands. As always, see the git --help command for specifics past the tutorial.

   1. git add -A

3. Commiting to the code as it should have made some change. This is not pushing any code github yet, this is just locally saved on your computer.

   1. git commit -m "Your message here"

4. The push command sends your code to the github servers. origin just indicates that it is going where we got it from. Lastly, you have to make sure you choose your branch to send it too. Again in this case the branch is your name, but if you ever forget what it is called, you can always use the git status or git branch command.

   1. git push origin <your name>

Pull requests: 

1. Now that you have developed all of this code (and tested), you would like it to be included in the master distribution. This is done using a pull request, and whoever maintains the repository will manage any conflicting issues. This is done by going to the repository itself, and clicking the pull request tab.

   1. git pull

Video: Git push.mp4

Video: Git pull.mp4

One problem the team ran into while trying to push and pull, is sometimes you will need to delete your build and devel folders if your first push/pull is unsuccessful. Also, if you update code while somebody else is updating code, you will have to pull the most recent changes before you push your new stuff. So make sure you save an extra copy of the changes you made because your changes on your local machine will get overwritten when pulling from master.