Human operator interface for SOA simulator

cd into Downloads directory and clone the soa_interface repository
https://github.com/mhaque3/soa_interface.git

This document serves as a setup guide for the operator interface. Screenshots that accompany this guide can be found in ~/Downloads/screenshots.

%=============

1 Components

%=============

~/Downloads/screenshots/00

1. The interface code lives in ~/Downloads/soa_sample_app. Setup instructions are in Section 6.
   
2. Qt Creator IDE since the interface is built using the Qt framework. Setup instructions are in Section 4.
   
3. The simulator lives in ~/Downloads/soa_sim. Setup instructions are in Section 5.
   
4. Google Protocol Buffers since the sim utilizes these for messaging. Setup instructions are in Section 3.
   

%=============

2 System

%=============

1. Ubuntu 14.04 LTS
   
2. If autoreconf, boost, cmake, etc not installed:
   $ sudo apt-get install autoconf boost libboost cmake
   
3. If cmake already installed, make sure version at least 3.8.0
   

%=============

3 Google protobuf

%=============

First, replace old protobuf-3.0.0-alpha-2

1. Delete directory ~/Downloads/soa_sample_app/protobuf-3.0.0-aplha-2
   
2. Do NOT delete directory ~/Downloads/soa_sample_app/proto_buff
   
3. Go to
   https://github.com/google/protobuf
   
4. Click on the "Branch: master" dropdown button, select the "Tags" tab, and scroll through the list and select v3.0.0-alpha-2
   
5. Click on the "Clone or download" and "Download ZIP"
   
6. Unzip /Downloads/protobuf-3.0.0-alpha-2.zip
   
7. Move the unzipped directory "protobuf-3.0.0-alpha-2" into directory ~/Downloads/soa_sample_app
   

Next, install new protobuf-3.0.0-alpha-2

12. Open a terminal, cd into ~/Downloads/protobuf-3.0.0-alpha-2 and run:
    ~/Downloads/protobuf-3.0.0-alpha-2$ ./autogen.sh
    ~/Downloads/protobuf-3.0.0-alpha-2$ ./configure
    ~/Downloads/protobuf-3.0.0-alpha-2$ make
    ~/Downloads/protobuf-3.0.0-alpha-2$ make check
    ~/Downloads/protobuf-3.0.0-alpha-2$ sudo make install
    

%=============

4 Qt creator

%=============

1. Download Qt Creator here:
   https://www.qt.io/ide/
   
2. Click on the "Start for Free" button on the image banner
   
3. The next window asks about deployment
   Select the radio button "In-house deployment, private use, or student use"
   
4. The next window asks about distribution
   Select the "No" radio button
   
5. The next window asks about compliance
   Select the "Yes" radio button
   
6. Click on the "Get Started" button
   
7. The next window detects the OS
   Click on the "Download Now" button
   

%=============

5 Simulator
~/Downloads/soa_sim/

%=============

~/Downloads/screenshots/01

1. Right click "Soav1.7_Linux.x86_64.exe"
   Permissions tab >> enable "Allow executing file as program"
   
2. Double click the "Soav1.7_Linux.x86_64.exe"
   Enable "Windowed"
   Select "Screen resolution" and the "Graphics quality"
   Ignore the "Input" Tab
   

~/Downloads/screenshots/02

3. (Optional) Simulator parameters can be found in "SoaSimConfig.xml"
   
4. (Optional) Request JHU/APL for access to "Sharepoint" in order to download future releases
   

%=============

6 Interface
~/Downloads/soa_sample_app

%=============

~/Downloads/screenshots/03

1. Launch Qt Creator
   
2. Click on "Open Project"
   
3. Select "interface_20JUN16.pro" located here:
   ~/Downloads/soa_sample_app/interface_20JUN16/interface_20Jun16.pro
   

~/Downloads/screenshots/04
~/Downloads/screenshots/05
~/Downloads/screenshots/06
~/Downloads/screenshots/07

4. Replace "haquema1" with appropriate username (QUrl not happy with relative path) in the following location:
   

~Downloads/soa_sample_app/blarg2/mapWdiget/webview.cpp Line 24:
load(QUrl::fromLocalFile("/home/haquema1/Downloads/soa_sample_app/blarg2/mapWidget/Scripts/RVA_derived.htm"));

5. Build project
   Build >> Build Project "interface20JUN16"
   
6. Run project
   Build >> Run
   

~/Downloads/screenshots/08

%=============

7 Notes

%=============

1. Entry point is main.cpp
   Instantiating an InterfaceWindow object
   Calling method show() since InterfaceWindow inherits QWidget
   http://doc.qt.io/qt-4.8/qwidget.html#show
   Rest of code here is standard Qt code to create a QApplication
   
2. Lab convention is member pointers are "m_p" prefixed
   
3. InterfaceWindow contains the three widgets -- LogicWidget, TabPanel2, and TaskPanel
   
4. LogicWidget responsible for map area
   
5. TaskPanelWidget responsible for tasking the simulator
   
6. TabPanel2 displays information regarding actors and tasks
   
7. Comments often refer to "JS." JS code is in ~Downloads/soa_sample_app/blarg2/mapWidget/Scripts and LogicWidget via WebView and MapWidget talks to the JS code to place icons on the map. The JS code utilizes a Google Maps API.
   

~/Downloads/screenshots/09

8. interfacewindow and taskpanelwidget come with .ui files in addition to the .h and .cpp pair. You can directly interact with the taskpanelwidget.ui, but not the interfacewindow.ui. To make changes to the layout of the interfacewindow, edit the interfacewindow.cpp's layout pointer.
   

9. HMT lab's class modules (can generally be ignored):
   borderlayout
   bytaskpanel
   bytasksidepanelcontainer
   qclicklabel
   qsidepanel
   qsidepanelcontainer
   qsidepanelcontainertabwidget
   

~/Downloads/screenshots/05

10. JHU/APL files that allow the interface to talk to the sim, or API to the sim (do NOT edit):
    Belief_Actor.h
    SoaAutonomy.h
    WorldDataManager.h
    WorldLocation.h
    List not exhaustive -- only included items that can be seen in the Active Project View
    

%=============

8 API Notes

%=============

1. ~/Downloads/soa_sample_app/include/SoaAutonomy.h is the JHU/APL provided API to the sim.
   
2. LogicWidget::taskSOA makes use of API to task the sim, (choice of task comes from TaskPanelWidget).
   
3. Currently, the sim's agents are individually tasked.
   

Current API: Interface asks sim to task agent with ID 103 to "Move to Location" by calling

m_pSoaAutonomy->sendWaypointPathCommand(103, waypointsToLocation); // in LogicWidget::taskSOA

Future API: Interface asks sim to task 3 agents to "Move to Location" by calling

m_pSoaAutonomy->sendWaypointPathCommand(3, waypointsToLocation); // coming soon...

4. The interface is one step ahead of the API at this point as it has been designed to task by a swarm size (scroll bars in TabpanelWidget), and not by swarm agent IDs. Interface is developed without waiting for API to catch up by faking what happens after the TabPanelWidget goes through setting up a task (see LogicWidget::tasksForVideo).
   

%=============

End Document

%=============