<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=Lab.2S01Lab05HITLSims}
\wikidoc{auth=supun@mit.edu}
\helplevelsubsec

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 5 - Software and Hardware in the Loop Simulations}
\vspace{0.2in}
\labcourse{2.S01 Introduction to Autonomous Underwater Vehicles}
\vspace{0.5in}
\labpng{0.8}{figures/HITL.png}
\vspace{0.25in}
\labdate{Spring 2024}
\vspace{0.23in}
\labauth{Supun Randeni, supun@mit.edu}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Mike Sacarny, msacarny@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{scriptsize}
\labtocdepth{2}
\end{labcover}

%===================================================================
\blankpage

%===================================================================
% Begin the body of the text
%===================================================================
\section{Objectives}
%===================================================================

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Setting up your topside computer - downloading and building the latest versions of MITFrontseat, MITFrontseat-drivers, VECTORS, missions-seabeaver and pablo-common software trees.
\item Setting up the Raspberry Pi in your training-kit - updating and rebuilding MITFrontseat, MITFrontseat-drivers, VECTORS, missions-seabeaver and pablo-common software trees.
\item Setting up the PocketBeagle in your training-kit - updating and rebuilding MITFrontseat, MITFrontseat-drivers, VECTORS, missions-seabeaver and pablo-common software trees.
\item Learning how to run software-in-the-loop simulations on your topside computer.
\item Learning how to run hardware-in-the-loop simulations using the training-kit and topside computer.
\end{packed_itemize}
\end{labinfo}


%===================================================================
\section{Building the software stack on the topside computer}
%===================================================================

First, we need to download and build the following MIT software projects on our topside as well as embedded computers, which are used in SeaBeaver II architecture. 
\begin{enumerate}
    \item {\bf moos-ivp}: This project contains our middleware, \cmd{MOOS}, and our autonomy helm software, \cmd{pHelmIvP}. It also includes a number of utility tools such as \cmd{uXMS}, \cmd{uPokeDB}, \cmd{pMarineViewer}, \cmd{alogview}, etc., that we will use throughout this class. We will build \cmd{moos-ivp} from its source-code, downloaded from an subversion (SVN) repository.  
    
    \item {\bf VECTORS}: This is our virtual ocean environment software. While this software is not used in runtime (i.e. when the vehicle is deployed in-water), we will use \cmd{VECTORS} for our software and hardware in the loop simulations. In 2.S01, we will not download the source-code repository of VECTORS. Instead, we will install it from a linux package distribution.
    
    \item {\bf MITFrontseat}: This is our primary embedded software stack, which contains mission planning (\cmd{pMITFS\_MissionScript}), mission commanding (\cmd{pMITFS\_MissionManager}), underwater navigation (\cmd{pMITFS\_HydroMANLite})  and control (\cmd{pMITFS\_ControlEngine}) software. We will build \cmd{MITFrontseat} from its source-code, downloaded from a git repository.
    
    \item {\bf MITFrontseat-drivers}: This contains the low-level software drivers that interfaces with hardware components of the SeaBeaver AUVs; for example the AHRS driver \cmd{iXsensMTi3}, actuator driver \cmd{iActuatorsPWM}, GPS driver \cmd{iMITFS\_GPSReadSerial}, etc. We will build \cmd{MITFrontseat-drivers} from its source-code, downloaded from a git repository.
    
    \item {\bf missions-seabeaver}: This is our mission launch framework. This repository primarily contains the configuration parameters of various MOOS apps that we use; and a number of shell scripts, carefully designed for seamless mission execution. This does not contain c++ code, hence building is not necessary. We download \cmd{missions-seabeaver} from a git repository.
    
    \item {\bf pablo-common}: This is very small software project that contains some configuration parameters in the operating system level (e.g. the software that assigns the vehicle names for your training-kit, based on the MAC address of the computer). It is downloaded from a subversion (SVN) repository.
\end{enumerate}

Some of these software projects have their own dependencies (for example, \cmd{MITFrontseat} depends on the Google Protocol Buffers and Boost C++ libraries, and \cmd{MITFrontseat-drivers} depends on the Robot Control Library). 


%===========================
\subsection{Building \cmd{moos-ivp}}
%===========================

At this point, you have already completed {\em Lab A - Course Laptop Setup} (\urlx{https://oceanai.mit.edu/2.S01/labs}), so we assume that you have successfully built \cmd{moos-ivp} on your topside laptop, and you are able to run the alpha mission example. If this is not the case, please complete {\em Lab A - Course Laptop Setup}.

%===========================
\subsection{Installing \cmd{VECTORS} and building \cmd{MITFrontseat}}
%===========================

For the 2.S01 class, the \cmd{VECTORS} software package is provided to you with \cmd{MITFrontseat} repository; therefore, we need to download \cmd{MITFrontseat} first. Your topside and embedded computers are given permission to access \cmd{MITFrontseat} via \urlx{https://github.com/supun-randeni/MITFrontseat}. First you need to clone this repository to your home directory (e.g. \cmd{/home/sb-topside-4/})

\vspace{0.1in}
\begin{consoleverb}
$ cd ~
$ git clone git@github.com:supun-randeni/MITFrontseat.git
\end{consoleverb}
\vspace{0.1in}

\noindent If you successfully cloned \cmd{MITFrontseat} to your topside computer, you will see something similar to this. 

\vspace{0.1in}
\begin{consoleverb}
sb-topside-4@sb-topside-4:~$ git clone git@github.com:supun-randeni/MITFrontseat.git
Cloning into 'MITFrontseat'...
Warning: Permanently added the ECDSA host key for IP address '140.82.112.4' to 
the list of known hosts.
remote: Enumerating objects: 583, done.
remote: Counting objects: 100% (583/583), done.
remote: Compressing objects: 100% (282/282), done.
remote: Total 583 (delta 404), reused 477 (delta 298), pack-reused 0
Receiving objects: 100% (583/583), 16.47 MiB | 7.14 MiB/s, done.
Resolving deltas: 100% (404/404), done.
\end{consoleverb}
\vspace{0.1in}

\noindent However, if you get the following error message, your permission is not properly set. Please contact an instructor:

\vspace{0.1in}
\begin{consoleverb}
sb-topside-4@sb-topside-4:~$ git clone git@github.com:supun-randeni/MITFrontseat.git
Cloning into 'MITFrontseat'...
Warning: Permanently added the ECDSA host key for IP address '140.82.114.3' to 
the list of known hosts.
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
\end{consoleverb}
\vspace{0.1in}

\noindent Once you cloned successfully, if you use the \cmd{ls} command, you can see \cmd{MITFrontseat} in your home directory:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~
$ ls
Desktop Documents   Downloads   MITFrontseat    moos-ivp    
Music   Pictures    Public  snap    Templates   Videos
\end{consoleverb}
\vspace{0.1in}

\noindent Let's go to \cmd{MITFrontseat} and explore:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat/
$ ls
build.sh	cmake_modules		  README.md	     scripts
CMakeLists.txt	COPYING-MITFrontseat.txt  release-notes.txt  src
\end{consoleverb}
\vspace{0.1in}

\noindent The git version control system allows you to branch out your software, so that we can modify the code and create new features without affecting the main code in the \cmd{master} branch, and other people's workflow (we encourage you to read more about version control, git and git branching on your own time). \cmd{MITFrontseat} is currently used by several MIT and external programs. Therefore, we have created a branch called \cmd{2.s01} for this class, so that we don't interrupt those projects. You can check your current branch by using the \cmd{git branch} command. It will output something similar to this, which means you are currently in a branch called \cmd{master}:

\vspace{0.1in}
\begin{consoleverb}
$ git branch 
* master
\end{consoleverb}
\vspace{0.1in}

\noindent Let's switch to the \cmd{2.s01} branch by using the command \cmd{git checkout 2.s01}. If you successfully switched to the branch, you will see an output similar to this:

\vspace{0.1in}
\begin{consoleverb}
$ git checkout 2.s01 
Branch '2.s01' set up to track remote branch '2.s01' from 'origin'.
Switched to a new branch '2.s01'
\end{consoleverb}
\vspace{0.1in}

\noindent You can use the \cmd{git pull} command to update the repository (i.e. to get the latest version of the code).

\vspace{0.1in}
\begin{consoleverb}
$ git pull 
Already up to date.
\end{consoleverb}
\vspace{0.1in}

\noindent Now that we are in \cmd{2.s01} branch with the most up-to-date code, we need to build \cmd{MITFrontseat}. However, we need to install the dependencies first, including \cmd{VECTORS}. To make things easier for you, we have created an automated script to do that. This script is located in \cmd{MITFrontseat/scripts} directory. Let's go there and execute this script:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat/scripts/
$ sudo ./dependencies.sh
[sudo] password for sb-topside-4: 
\end{consoleverb}
\vspace{0.1in}

\noindent Please enter the password of the topside computer when you are asked to do so. The dependency installation might take a several minutes. When it is done, you can check if VECTORS is successfully installed by using the command \cmd{which iVECTORS\_Gateway}. It should give an output similar to follows. If you get a blank response, please talk to an instructor.

\vspace{0.1in}
\begin{consoleverb}
$ which iVECTORS_Gateway 
/usr/local/bin/iVECTORS_Gateway
\end{consoleverb}
\vspace{0.1in}

\noindent Now you have installed all the dependencies. It is time to build \cmd{MITFrontseat}:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat/
$ ./build.sh
\end{consoleverb}
\vspace{0.1in}

\noindent Let it build.. While it is building, check if it exits with errors. 


%===========================
\subsection{Building \cmd{MITFrontseat-drivers}}
%===========================

Your topside and embedded computers are given permission to access \cmd{MITFrontseat-drivers} via \urlx{https://github.com/supun-randeni/MITFrontseat-drivers}. Similar to \cmd{MITFrontseat}, first you need to clone this repository to your home directory (e.g. \cmd{/home/sb-topside-4/})

\vspace{0.1in}
\begin{consoleverb}
$ cd ~
$ git clone git@github.com:supun-randeni/MITFrontseat-drivers.git
\end{consoleverb}
\vspace{0.1in}

\noindent If you successfully cloned \cmd{MITFrontseat-drivers} to your topside computer, you will see it in your home directory:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~
$ ls
Desktop    Downloads    MITFrontseat-drivers  Music   Public  Templates
Documents  MITFrontseat  moos-ivp   Pictures  snap  Videos
\end{consoleverb}
\vspace{0.1in}

\noindent Let's go to \cmd{MITFrontseat-drivers} and explore:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat-drivers/
$ ls
build.sh    cmake_modules   README.md   scripts
CMakeLists.txt  COPYING-MITFrontseat-drivers.txt  release-notes.txt  src
\end{consoleverb}
\vspace{0.1in}

\noindent Similar to \cmd{MITFrontseat}, we need to switch to the \cmd{2.s01} branch of \cmd{MITFrontseat-drivers} by using the command \cmd{git checkout 2.s01}. If you successfully switched to the branch, you will see an output similar to this:

\vspace{0.1in}
\begin{consoleverb}
$ git checkout 2.s01 
Branch '2.s01' set up to track remote branch '2.s01' from 'origin'.
Switched to a new branch '2.s01'
\end{consoleverb}
\vspace{0.1in}

\noindent You can use the \cmd{git pull} command to update the repository (i.e. to get the latest version of the code).

\vspace{0.1in}
\begin{consoleverb}
$ git pull 
Already up to date.
\end{consoleverb}
\vspace{0.1in}

\noindent Let's install the dependency software packages of \cmd{MITFrontseat-drivers} by running the \cmd{dependencies.sh} script located in in \cmd{MITFrontseat-drivers/scripts} directory:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat-drivers/scripts/
$ sudo ./dependencies.sh 
[sudo] password for sb-topside-4: 
\end{consoleverb}
\vspace{0.1in}

\noindent Please enter the password of the topside computer when you are asked to do so. The dependency installation might take a several minutes. The screen shown in Figure \ref{fig_librc} might pop-up when the robot control library is being installed. Please select the option \cmd{none}.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=0.6\textwidth]{figures/librobotcontrol_installation.png}
\caption{Configuring librobotcontrol pop-up window}
\label{fig_librc}
\end{figure}

\noindent When it is done, you can check if librobotcontrol is successfully installed by using the command \cmd{which rc\_test\_drivers}. It should give an output similar to follows. If you get a blank response, please talk to an instructor.

\vspace{0.1in}
\begin{consoleverb}
$ which rc_test_drivers 
/usr/bin/rc_test_drivers
\end{consoleverb}
\vspace{0.1in}

\noindent Now you have installed all the dependencies. It is time to build \cmd{MITFrontseat-drivers}:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat-drivers/
$ ./build.sh
\end{consoleverb}
\vspace{0.1in}

\noindent Let it build.. While it is building, check if it exits with errors. 


%===========================
\subsection{Downloading \cmd{missions-seabeaver}}
%===========================

Your topside and embedded computers are given permission to access \cmd{missions-seabeaver} via \urlx{https://github.com/supun-randeni/missions-seabeaver}. This repository only contains shell scripts and MOOS configuration files; therefore, it is not necessary to build the code. You only need to clone the repository to the home directory (e.g. \cmd{/home/sb-topside-4/})

\vspace{0.1in}
\begin{consoleverb}
$ cd ~
$ git clone git@github.com:supun-randeni/missions-seabeaver.git
\end{consoleverb}
\vspace{0.1in}

\noindent If you successfully cloned \cmd{missions-seabeaver} to your topside computer, you will see it in your home directory:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~
$ ls
Desktop Downloads    MITFrontseat   moos-ivp    Pictures    snap    Videos
Documents   missions-seabeaver   MITFrontseat-drivers Music  Public   Templates
\end{consoleverb}
\vspace{0.1in}

\noindent Let's go inside \cmd{missions-seabeaver} directory and explore:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/missions-seabeaver/
$ ls
architecture  clean_logs.sh  clean.sh  cruise  launch_scripts  meta
plugs  README.md  release-notes.txt  vehicle
\end{consoleverb}
\vspace{0.1in}

\noindent Finally, let's switch to the \cmd{2.s01} branch by using the command \cmd{git checkout 2.s01}. If you successfully switched to the branch, you will see an output similar to this:

\vspace{0.1in}
\begin{consoleverb}
$ git checkout 2.s01 
Branch '2.s01' set up to track remote branch '2.s01' from 'origin'.
Switched to a new branch '2.s01'
\end{consoleverb}
\vspace{0.1in}

\noindent You can use the \cmd{git pull} command to update the repository (i.e. to get the latest version of the code).

\vspace{0.1in}
\begin{consoleverb}
$ git pull 
Already up to date.
\end{consoleverb}
\vspace{0.1in} 


%===========================
\subsection{Adding to shell path}
%===========================

The locations of \cmd{MITFrontseat} and \cmd{MITFrontseat-drivers} binaries are required to be added to your shell path. In addition, we need to tell the locations of \cmd{MITFrontseat} and \cmd{MITFrontseat-drivers} libraries to the dynamic link loader by adding them to the \cmd{LD\_LIBRARY\_PATH}. To make your life easier, we have created a text file with these necessary information: \cmd{MITFrontseat-drivers/scripts/dot\_bash\_seabeaver}. We just need to call this text file from your \cmd{.bashrc} file, and \cmd{dot\_bash\_seabeaver} will take care of the rest.

Edit your \cmd{.bashrc} file using your favorite text editor, and append the following lines to the end of the file:

\vspace{0.1in}
\begin{consoleverb}
if [ -f $HOME/MITFrontseat-drivers/scripts/dot_bash_seabeaver ]; then
    . $HOME/MITFrontseat-drivers/scripts/dot_bash_seabeaver
fi
\end{consoleverb}
\vspace{0.1in}

\noindent Don't forget to source the \cmd{.bashrc} file using the command:

\vspace{0.1in}
\begin{consoleverb}
$ source ~/.bashrc
\end{consoleverb}
\vspace{0.1in}


%===========================
\subsection{Self checkoff assessment}
%===========================

The following should be checked off:

\begin{enumerate}
    \item Ensure that \cmd{MITFrontseat} is built properly, and its binaries are in your shell path by running the following command:
    
    \vspace{0.1in}
    \begin{consoleverb}
    $ which iVECTORS_MITFS pMITFS_ControlEngine pMITFS_HydroMANLite pMITFS_MissionManager 
    pMITFS_MissionScript
    \end{consoleverb}
    \vspace{0.1in}

    It should output something similar to this:

    \vspace{0.1in}
    \begin{consoleverb}
    $ which iVECTORS_MITFS pMITFS_ControlEngine pMITFS_HydroMANLite pMITFS_MissionManager
    pMITFS_MissionScript
    
    /home/sb-topside-4/MITFrontseat/bin/iVECTORS_MITFS
    /home/sb-topside-4/MITFrontseat/bin/pMITFS_ControlEngine
    /home/sb-topside-4/MITFrontseat/bin/pMITFS_HydroMANLite
    /home/sb-topside-4/MITFrontseat/bin/pMITFS_MissionManager
    /home/sb-topside-4/MITFrontseat/bin/pMITFS_MissionScript
    \end{consoleverb}
    \vspace{0.1in}

    \item Ensure that \cmd{MITFrontseat-drivers} is built properly, and its binaries are in your shell path by running the following command:

    \vspace{0.1in}
    \begin{consoleverb}
    $ which calibrate_xsens_mti3 iMITFS_GPSReadSerial pMOOSLink test_br_thruster
    iActuatorsPWM iXsensMTi3 test_control_surfaces iMITFS_BR_Depth mitfs_safety_daemon
    \end{consoleverb}
    \vspace{0.1in}

    It should output something similar to this:

    \vspace{0.1in}
    \begin{consoleverb}
    $ which calibrate_xsens_mti3 iMITFS_GPSReadSerial pMOOSLink test_br_thruster 
    iActuatorsPWM iXsensMTi3 test_control_surfaces iMITFS_BR_Depth mitfs_safety_daemon
    
    /home/sb-topside-4/MITFrontseat-drivers/bin/calibrate_xsens_mti3
    /home/sb-topside-4/MITFrontseat-drivers/bin/iMITFS_GPSReadSerial
    /home/sb-topside-4/MITFrontseat-drivers/bin/pMOOSLink
    /home/sb-topside-4/MITFrontseat-drivers/bin/test_br_thruster
    /home/sb-topside-4/MITFrontseat-drivers/bin/iActuatorsPWM
    /home/sb-topside-4/MITFrontseat-drivers/bin/iXsensMTi3
    /home/sb-topside-4/MITFrontseat-drivers/bin/test_control_surfaces
    /home/sb-topside-4/MITFrontseat-drivers/bin/iMITFS_BR_Depth
    /home/sb-topside-4/MITFrontseat-drivers/bin/mitfs_safety_daemon
    \end{consoleverb}
    \vspace{0.1in}
\end{enumerate}


%===================================================================
\section{Software-in-the-loop (SITL) simulations}
%===================================================================

The \cmd{missions-seabeaver} launch framework is designed in a way that we are able to simulate the mission, either software-in-the-loop (i.e. in the topside laptop) or hardware-in-the-loop (i.e. on the vehicle itself) fashion; and deploy the same mission in the field in runtime mode. This way we can ensure that the mission has been setup correctly and the hardware is working properly, before deploying a vehicle in the field. In SITL simulations, as shown in Figure \ref{fig_sitl}, the frontseat, backseat and VECTORS MOOS communities are all launched in the topside computer.

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=1\textwidth]{figures/SITL.png}
\caption{In software-in-the-loop simulations, frontseat, backseat and VECTORS MOOS communities are all launched on the topside computer}
\label{fig_sitl}
\end{figure}

\noindent Before launching a mission using  \cmd{missions-seabeaver}, you need to configure three things: 

\begin{enumerate}
    \item {\bf The vehicle architecture}: This is the vehicle
      class; SeaBeaver II in our case.
    \item {\bf The vehicle name}: Sometimes each vehicle
      has have slightly unique parameters. So we need to define what
      our vehicle is.
    \item {\bf The cruise (or mission)}: This is will tell the mission-specific parameters.
\end{enumerate}

\noindent Configuring and launching is done in the \cmd{launch\_scripts} directory. So let's go there:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/missions-seabeaver/launch_scripts/
\end{consoleverb}
\vspace{0.1in}

%===========================
\subsection{Defining the vehicle architecture}
%===========================

First, configure the vehicle architecture. Run the following command to list all the available architectures, and you should get a similar output:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_architecture.sh 
usage: ./architecture_config.sh {architecture-name}

current architecture is set to: 
(not set)

available architectures include: 
seabeaver_ii.def
template_architecture.def
\end{consoleverb}
\vspace{0.1in}

\noindent As you can see, there are two available architectures (1) \cmd{seabeaver\_ii}, and (2) \cmd{template\_architecture}. Let's select our vehicle architecture; i.e. \cmd{seabeaver\_ii}:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_architecture.sh seabeaver_ii
\end{consoleverb}
\vspace{0.1in}

\noindent note: make sure that you exclude the suffix [.def]. I.e. do NOT configure like this: \cmd{./configure\_architecture.sh seabeaver\_ii.def}


%===========================
\subsection{Defining the vehicle}
%===========================

Now let's configure the vehicle name. Run the \cmd{./configure\_vehicle.sh} script to list all the available vehicles, and you should get a similar output:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_vehicle.sh
\end{consoleverb}
\vspace{0.1in}

\noindent It will give you an output similar to this:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_vehicle.sh 
usage: ./vehicle_config.sh {vehicle-name}

current vehicle is set to: 
(not set)

current sensor_config.txt is set to: 
(not set)

available vehicles include: 
sb2_alpha.def
template_uuv.def
\end{consoleverb}
\vspace{0.1in}

\noindent At a minimum, there will be two vehicles: (1) \cmd{sb2\_alpha}, and (2) \cmd{template\_uuv}. In later sessions, you will create a definition file for your own vehicle. But for now, let's use the \cmd{sb2\_alpha} AUV's definition. Configure the vehicle:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_vehicle.sh sb2_alpha
\end{consoleverb}
\vspace{0.1in}


%===========================
\subsection{Defining the cruise}
%===========================

Finally, we will configure the cruise, or the mission, that we need to run. Run the \cmd{./configure\_cruise.sh} script to list all the available cruises:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_cruise.sh 
usage: ./cruiseconfig.sh {cruisename}

current cruise definition is set to: 
b_zigzag.def

current pMITFS_MissionScript plug is set to: 
b_zigzag_pMITFS_MissionScript.plug

available cruise names include: 
a_confidence.def
bench_test.def
b_zigzag.def
lab_4_do_nothing_log_data.def
shipwreck_search.def
template_cruise.def
\end{consoleverb}
\vspace{0.1in}

\noindent In this lab, we are going to simulate the \cmd{shipwreck\_search} mission. Let's select that:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_cruise.sh shipwreck_search
Successfully configured the cruise to shipwreck_search in sb-topside-4!
\end{consoleverb}
\vspace{0.1in}


%===========================
\subsection{Launching a software-in-the-loop simulated mission}
%===========================

Now we can launch the mission as a software-in-the-loop simulation by executing \cmd{launch\_simulation.sh} script:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch_simulation.sh 
\end{consoleverb}
\vspace{0.1in}

\noindent On the terminal, you will see an output similar to this:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch_simulation.sh 

Launching Frontseat-Backseat mode.. 
SITL launch in process..
Launching mode is: FRONTBACK_FRONT
Part 3: Assembling targ_ Frontseat .moos ... Done
Part 3: Assembling targ_ Frontseat .bhv ... Done
Launching Frontseat MOOS Community. WARP is 1
Done
SITL launch in process..
Launching mode is: FRONTBACK_BACK
Part 3: Assembling targ_ Backseat .moos ... Done
Part 3: Assembling targ_ Backseat .bhv ... Done
Part 3: Assembling targ_ VECTORS .moos ... Done
Launching Backseat MOOS Community. WARP is 1
Done
Launching VECTORS MOOS Community. WARP is 1
Done
uMAC launching as uMAC_5881

uMAC_5881 thread spawned
starting uMAC_5881 thread
1713245491.3322 140123404248832-                           disabling nagle

-------------- moos connect ----------------------
  contacting a MOOS server localhost:9250 -  try 00001 
  Handshaking as uMAC_5881              [ok]
  DB reports async support is           [on]
  DB is running on                      sb-topside-4
  Timing skew estimation is             [off] (not needed)
--------------------------------------------------

uMAC_5881 is Running:
 |-Baseline AppTick   @ 5.0 Hz
 |--Comms is Full Duplex and Asynchronous
 -Iterate Mode 0 :
   |-Regular iterate and message delivery at 5 Hz

==================================================
uMAC_5881:  Nodes (0)                   (1) EVENTS
==================================================
AppCasts Recd: 0

ID  Node  HMode  Recd  CWarns  RWarns
--  ----  -----  ----  ------  ------

==================================================
uMAC_5881:  Nodes (1)                   (2) EVENTS
==================================================

\end{consoleverb}
\vspace{0.1in}

\noindent The \cmd{pMarineViewer} window will come up shortly. The mission will automatically start after 30 seconds, and will run for 7 minutes total. The mission is to go to the middle of the river, conduct a short zig-zag pattern search mission, and loiter until the 7 minute runtime is complete. Observe the followings:

\begin{itemize}
    \item You will see two vehicle icons; one with the name \cmd{SB2\_ALPHA}, and the other \cmd{SB2\_ALPHA\_GT}. The two vehicles will start at the same location, and then diverge. GT stands for the {\em ground truth}; that is, the actual position of the simulated vehicle. The \cmd{SB2\_ALPHA} is the navigation solution computed by onboard navigation system; i.e. \cmd{pMITFS\_HydroMANLite} application. During our underwater navigation session, we discuss the reasons for this divergence, and how to minimize it.

    \item You will also note that the vehicle is not able to conduct a clear zig-zag pattern, and it wiggles. During our controls session, we will discuss the reasons for this, and how to minimize it.

    \item Observe the heading, speed and depth values of the vehicle displayed on the bottom-side on the \cmd{pMarineViewer} window.
\end{itemize}

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=1\textwidth]{figures/search.png}
\caption{\cmd{pMarineViewer} window for the \cmd{shipwreck\_search} mission}
\label{fig_pMV}
\end{figure}


The software-in-the-loop simulations can be sped-up by time warping. That is, we can simulate missions faster than real time by appending the time warp factor at the end of \cmd{./launch\_simulation.sh} command. For example, if you want to run the simulation 5 times faster than real time:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch_simulation.sh 5
\end{consoleverb}
\vspace{0.1in}

\noindent {\bf Please do NOT time warp hardware-in-the-loop simulations since the servo motors and the thruster can be damaged.}

%===========================
\subsection{Killing the mission}
%===========================

You can press ctrl+c on the terminal to kill the mission. To be safe, you can also use \cmd{ktm} command (kill-the-moos) and kill all the MOOS processes.


%===========================
\subsection{Self checkoff assessment}
%===========================

Ensure that:

\begin{itemize}
    \item Are you able to run the software-in-the-loop simulated mission on your topside computer?
    \item Does your simulated vehicle behave similar to the track shown in Figure \ref{fig_pMV}?
    \item Can you run the same simulated mission in higher time warps?
\end{itemize}


%===================================================================
\section{Building the software stack on the Raspberry Pi}
%===================================================================

The Raspberry Pi computer of your training kit already has \cmd{moos-ivp}, \cmd{MITFrontseat}, \cmd{MITFrontseat-drivers}, \cmd{missions-seabeaver} and \cmd{pablo-common} downloaded and built. However, you will need to update these repositories to the latest version, and re-build the code. In addition, you will need to install \cmd{VECTORS}.  First, log into your training kit's Raspberry Pi embedded computer using either wired or wireless approach. 


%===========================
\subsection{Updating \cmd{pablo-common}}
%===========================

We need to update the \cmd{pablo-common} SVN repository in order to obtain the latest configuration parameters:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/pablo-common/
$ svn update
\end{consoleverb}
\vspace{0.1in}

\noindent You will see an output similar to this:

\vspace{0.1in}
\begin{consoleverb}
$ svn update
Updating '.':
A    bin/path_bhv.sh
A    bin/path_shell.sh
A    bin/mypath.sh
Updated to revision 721.
\end{consoleverb}
\vspace{0.1in}

\noindent After updating \cmd{pablo-common}, please source the \cmd{.bashrc} file using the command:

\vspace{0.1in}
\begin{consoleverb}
$ source ~/.bashrc
\end{consoleverb}
\vspace{0.1in}


%===========================
\subsection{Updating \cmd{MITFrontseat} and installing \cmd{VECTORS}}
%===========================

We need to switch to the \cmd{2.s01} branch of \cmd{MITFrontseat} and update it. However, the local repository on the Rapsberry Pi does not know about the new \cmd{2.s01} branch on the \urlx{https://github.com/supun-randeni/MITFrontseat} server. So we need to fetch the latest updates first:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat
$ git fetch
\end{consoleverb}
\vspace{0.1in}

\noindent Now we can switch to the \cmd{2.s01} branch:


\vspace{0.1in}
\begin{consoleverb}
$ git checkout 2.s01 
Branch '2.s01' set up to track remote branch '2.s01' from 'origin'.
Switched to a new branch '2.s01'
\end{consoleverb}
\vspace{0.1in}

\noindent You can use the \cmd{git pull} command to update the repository (i.e. to get the latest version of the code).

\vspace{0.1in}
\begin{consoleverb}
$ git pull 
Already up to date.
\end{consoleverb}
\vspace{0.1in}

\noindent Now that we are in \cmd{2.s01} branch with the most up-to-date code, we need to install \cmd{VECTORS} by running the \cmd{dependencies.sh} script:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat/scripts/
$ sudo ./dependencies.sh
[sudo] password for seabeaver-raspi: 
\end{consoleverb}
\vspace{0.1in}

\noindent Please enter the password of your training-kit's Raspberry Pi computer when you are asked to do so. The dependency installation might take a several minutes. When it is done, you can check if VECTORS is successfully installed by using the command \cmd{which iVECTORS\_Gateway}. It should give an output similar to follows. If you get a blank response, please talk to an instructor.

\vspace{0.1in}
\begin{consoleverb}
$ which iVECTORS_Gateway 
/usr/local/bin/iVECTORS_Gateway
\end{consoleverb}
\vspace{0.1in}

\noindent Now you have installed all the dependencies. It is time to build \cmd{MITFrontseat}:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat/
$ ./build.sh
\end{consoleverb}
\vspace{0.1in}

\noindent Let it build.. While it is building, check if it exits with errors. 


%===========================
\subsection{Updating \cmd{MITFrontseat-drivers}}
%===========================

Similar to \cmd{MITFrontseat}, you will need to switch to the \cmd{2.s01} branch of \cmd{MITFrontseat-drivers} and update it. Let's fetch the latest updates first:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat-drivers
$ git fetch
\end{consoleverb}
\vspace{0.1in}

\noindent Now we can switch to the \cmd{2.s01} branch and pull the latest version of the code:

\vspace{0.1in}
\begin{consoleverb}
$ git checkout 2.s01 
Branch '2.s01' set up to track remote branch '2.s01' from 'origin'.
Switched to a new branch '2.s01'

$ git pull 
Already up to date.
\end{consoleverb}
\vspace{0.1in}

\noindent Now that we are in \cmd{2.s01} branch with the most up-to-date code, we can build \cmd{MITFrontseat-drivers}:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat-drivers/
$ ./build.sh
\end{consoleverb}
\vspace{0.1in}

\noindent It will first (re)build \cmd{MITFrontseat}, and then continue to build \cmd{MITFrontseat-drivers}. This is since \cmd{MITFrontseat-drivers} depends on \cmd{MITFrontseat}; and we want to make sure that \cmd{MITFrontseat} builds before we attempt to build \cmd{MITFrontseat-drivers}. 
Let it build.. While it is building, check if it exits with errors.


%===========================
\subsection{Updating \cmd{missions-seabeaver}}
%===========================

Similar to \cmd{MITFrontseat}, you will need to switch to the \cmd{2.s01} branch of \cmd{missions-seabeaver} and update it. Let's fetch the latest updates first:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/missions-seabeaver
$ git fetch
\end{consoleverb}
\vspace{0.1in}

\noindent Now we can switch to the \cmd{2.s01} branch and pull the latest version of the code:

\vspace{0.1in}
\begin{consoleverb}
$ git checkout 2.s01 
Branch '2.s01' set up to track remote branch '2.s01' from 'origin'.
Switched to a new branch '2.s01'

$ git pull 
Already up to date.
\end{consoleverb}
\vspace{0.1in}


%===========================
\subsection{Self checkoff assessment}
%===========================

The following should be checked off:

\begin{enumerate}
    \item Ensure that \cmd{MITFrontseat} is built properly, and its binaries are in your shell path by running the following which command:

    \vspace{0.1in}
    \begin{consoleverb}
    $ which iVECTORS_MITFS pMITFS_ControlEngine pMITFS_HydroMANLite pMITFS_MissionManager
    pMITFS_MissionScript
    
    /home/seabeaver-raspi/MITFrontseat/bin/iVECTORS_MITFS
    /home/seabeaver-raspi/MITFrontseat/bin/pMITFS_ControlEngine
    /home/seabeaver-raspi/MITFrontseat/bin/pMITFS_HydroMANLite
    /home/seabeaver-raspi/MITFrontseat/bin/pMITFS_MissionManager
    /home/seabeaver-raspi/MITFrontseat/bin/pMITFS_MissionScript
    \end{consoleverb}
    \vspace{0.1in}

    \item Ensure that \cmd{MITFrontseat-drivers} is built properly, and its binaries are in your shell path by running the following which command:

    \vspace{0.1in}
    \begin{consoleverb}
    $ which calibrate_xsens_mti3 iMITFS_GPSReadSerial pMOOSLink test_br_thruster 
    iActuatorsPWM iXsensMTi3 test_control_surfaces iMITFS_BR_Depth mitfs_safety_daemon
    
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/calibrate_xsens_mti3
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/iMITFS_GPSReadSerial
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/pMOOSLink
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/test_br_thruster
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/iActuatorsPWM
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/iXsensMTi3
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/test_control_surfaces
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/iMITFS_BR_Depth
    /home/seabeaver-raspi/MITFrontseat-drivers/bin/mitfs_safety_daemon
    \end{consoleverb}
    \vspace{0.1in}
\end{enumerate}


%===================================================================
\section{Building the software stack on the PocketBeagle}
%===================================================================


%===========================
\subsection{Updating the software repositories}
%===========================

Similar to the Raspberry Pi, we need to update and build \cmd{MITFrontseat}, \cmd{MITFrontseat-drivers}, \cmd{missions-seabeaver} and \cmd{pablo-common} repositories on the PocketBeagle. However there is a slight difference when building \cmd{MITFrontseat-drivers}. You should use the \cmd{./build.sh} command with the \cmd{--vehicle} flag:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/MITFrontseat-drivers/
$ ./build.sh --vehicle
\end{consoleverb}
\vspace{0.1in}

Let it build.. At the end of the build, you will be asked to enter the password of the PocketBeagle to provide root privileges to some of the hardware driver apps; e.g. \cmd{iActuatorsPWM}, \cmd{test\_control\_surfaces} and \cmd{test\_br\_thruster}. This is in order to allow these drivers to access the PocketBeagle's hardware modules.


%===========================
\subsection{Self checkoff assessment}
%===========================

The following should be checked off:

\begin{enumerate}
    \item Ensure that \cmd{MITFrontseat} is built properly, and its binaries are in your shell path.

    \item Ensure that \cmd{MITFrontseat-drivers} is built properly, and its binaries are in your shell path.

    \item Our latest update to \cmd{pablo-common} adds the Raspberry Pi's public SSH key to the PocketBeagle's authorized devices list. This should allow you to SSH from the Raspberry Pi to the PocketBeagle without having to type the password! This is a requirement for the SeaBeaver mission launch framework. Please ensure that you can login to the PocketBeagle without having the type the password. Exit from the current SSH session of the PocketBeagle, and try to re-login:

    \vspace{0.1in}
    \begin{consoleverb}
    $ exit
    logout
    Connection to 192.168.7.2 closed.

    $ ssh debian@192.168.7.2
    Debian GNU/Linux 10

    BeagleBoard.org Debian Buster IoT Image 2020-04-06
    
    Support: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian
    
    default username:password is [debian:temppwd]
    
    
    The programs included with the Debian GNU/Linux system are free software;
    the exact distribution terms for each program are described in the
    individual files in /usr/share/doc/*/copyright.
    
    Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
    permitted by applicable law.
    Last login: Tue Apr 16 03:50:10 2024 from 192.168.7.1
    debian@avi-PB:~$ 
    \end{consoleverb}
    \vspace{0.1in}
    

\end{enumerate}


%===================================================================
\section{Hardware-in-the-loop (HITL) simulations}
%===================================================================

Hardware-in-the-loop simulations allow us to test the majority of software and hardware components at a lower cost, minimizing the required in-water testing time and the risk of expensive failures. In SeaBeaver HITL simulations, we try to run the software in respective computers where they are supposed to run during in-water operation to minimize any deviations. That is:

\begin{itemize}
 \item Frontseat MOOS community runs in the PocketBeagle.
 \item Backseat MOOS community runs in the Raspberry Pi.
 \item Topside MOOS community runs in the topside computer.
 \item VECTORS MOOS community runs in the Raspberry Pi (this is the only deviation).
\end{itemize}

\vspace{0.1in}
\begin{figure}[H]
\centering
\includegraphics[width=1\textwidth]{figures/HITL.png}
\caption{Four MOOS communities are launched during hardware-in-the-loop simulations}
\label{fig_HITL}
\end{figure}


%===========================
\subsection{Defining the architecture, vehicle and cruise}
%===========================

To run frontseat and backseat MOOS communities in two different computers, we typically need to log into both computers and launch them separately. However, in SeaBeaver AUVs, if we configure the architecture, vehicle or cruise in the Raspberry Pi, the configuration script will automatically apply the same configuration on the PocketBeagle using remote SSH commands. Let's try it. 

Please log into both Raspberry Pi and PocketBeagle using two terminal windows. On both computers, change directory to \cmd{missions-seabeaver} and run the \cmd{clean.sh} script to clear off previous configurations and logs:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/missions-seabeaver
$ ./clean.sh
\end{consoleverb}
\vspace{0.1in}

\noindent On the PocketBeagle, go to the \cmd{launch\_scripts} directory and run the \cmd{configure\_architecture.sh} script. Observe that the architecture is currently not configured:

\vspace{0.1in}
\begin{consoleverb}
$ cd launch_scripts/
$ ./configure_architecture.sh 
usage: ./architecture_config.sh {architecture-name}

current architecture is set to: 
(not set)

available architectures include: 
seabeaver_ii.def
template_architecture.def
\end{consoleverb}
\vspace{0.1in}

\noindent On the Raspberry Pi, configure the architecture to \cmd{seabeaver\_ii} by using the following command:

\vspace{0.1in}
\begin{consoleverb}
$ cd launch_scripts/
$ ./configure_architecture.sh seabeaver_ii
Successfully configured the architecture to seabeaver_ii in seabeaver-raspi!
Configuring the architecture on the PocketBeagle. Architecture name: seabeaver_ii
Debian GNU/Linux 10

BeagleBoard.org Debian Buster IoT Image 2020-04-06

Support: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian

default username:password is [debian:temppwd]

Successfully configured the architecture to seabeaver_ii in debian!
\end{consoleverb}
\vspace{0.1in}

\noindent As you see, the script also configured the architecture on the PocketBeagle. You can verify this by running \cmd{configure\_architecture.sh} script on the PocketBeagle:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_architecture.sh 
usage: ./architecture_config.sh {architecture-name}

current architecture is set to: 
seabeaver_ii.def

available architectures include: 
seabeaver_ii.def
template_architecture.def
\end{consoleverb}
\vspace{0.1in}

\noindent Similarly, configure the vehicle to \cmd{sb2\_alpha} and cruise to \cmd{shipwreck\_search} on the Raspberry Pi:

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_vehicle.sh sb2_alpha
Successfully configured the vehicle to sb2_alpha in seabeaver-raspi!
Configuring the vehicle on the PocketBeagle. Vehicle name: sb2_alpha
Debian GNU/Linux 10

BeagleBoard.org Debian Buster IoT Image 2020-04-06

Support: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian

default username:password is [debian:temppwd]

Successfully configured the vehicle to sb2_alpha in debian!

$ ./configure_cruise.sh shipwreck_search
Successfully configured the cruise to shipwreck_search in seabeaver-raspi!
Configuring the cruise on the PocketBeagle. Cruise name: shipwreck_search
Debian GNU/Linux 10

BeagleBoard.org Debian Buster IoT Image 2020-04-06

Support: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian

default username:password is [debian:temppwd]

Successfully configured the cruise to shipwreck_search in debian!
\end{consoleverb}
\vspace{0.1in}


%===========================
\subsection{Launching the topside}
%===========================

We typically launch the topside MOOS community before launching the backseat or frontseat MOOS communities. Before launching the topside, we need to configure the architecture, vehicle and cruise on the topside computer as well:

\vspace{0.1in}
\begin{consoleverb}
$ cd ~/missions-seabeaver/launch_scripts/
$ ./configure_architecture.sh seabeaver_ii
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_vehicle.sh sb2_alpha
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{consoleverb}
$ ./configure_cruise.sh shipwreck_search
\end{consoleverb}
\vspace{0.1in}

\noindent Now we can launch the topside:

\vspace{0.1in}
\begin{consoleverb}
$ ./launch_topside.sh
\end{consoleverb}
\vspace{0.1in}

\noindent the \cmd{pMarineViewer} window should open. However, you will not see any vehicles until you launch the backseat and frontseat.

%===========================
\subsection{Launching the hardware-in-the-loop simulation mission}
%===========================

Similar to the configurations, if you launch the mission on the Raspberry Pi (i.e. backseat), it will automatically launch the frontseat on the PocketBeagle. We can use the \cmd{./launch\_hitl.sh} script to launch the mission. However, we do need to let the backseat MOOS community know the IP address of the designated topside laptop by using \cmd{--topside=} flag; for example: 

\vspace{0.1in}
\begin{consoleverb}
$ ./launch_hitl.sh --topside=10.42.0.1
\end{consoleverb}
\vspace{0.1in}

Now the two vehicle icons (i.e., \cmd{SB2\_ALPHA}, and \cmd{SB2\_ALPHA\_GT}) should appear, and they should start the same \cmd{shipwreck\_search} mission that we can in SITL mode. However, this time the mock-up control surfaces and thruster on your training-kit should move.

Observe the followings:

\begin{itemize}
    \item Movement of the rudder with heading changes.
    \item Movement of the elevators with heading changes.
    \item Movement of the elevators with depth (note that the mission expects to run the vehicle at 1m depth).
\end{itemize}

\noindent {\bf Please do NOT time warp hardware-in-the-loop simulations since the servo motors and the thruster can be damaged.}


%===========================
\subsection{Killing the mission}
%===========================

You can press ctrl+c on the Raspberry Pi terminal to kill both the backseat. It should then automatically kill the frontseat on the PocketBeagle. However, if the servo motors did not stop, please log into the PocketBeagle and use \cmd{ktm} command (kill-the-moos) and kill all the MOOS processes. Press ctrl+c on the topside terminal to kill the topside MOOS community.


%===========================
\subsection{Self checkoff assessment}
%===========================

The following should be checked off:

\begin{itemize}
    \item Are you able to run the hardware-in-the-loop simulated mission successfully?
    \item Do you see vehicle on your topside \cmd{pMarineViewer} window?
    \item Do you see the servo movements in your training-kit's mock-up tailcone?
    \item Are you able to kill the mission?
\end{itemize}


\end{document}

</pre></body></html>