License

OpenUxAS is developed by the Air Force Research Laboratory, Aerospace System Directorate, Power and Control Division. The LMCP specification and all source code for OpenUxAS is publicaly released under the Air Force Open Source Agreement Version 1.0. See LICENSE.md for complete details. The Air Force Open Source Agreement closely follows the NASA Open Source Agreement Verion 1.3. NOTE the terms of the license include registering use of the software by emailing [email protected].

Introduction

UxAS consists of a collection of modular services that interact via a common message passing architecture. Similar in design to Robot Operating System (ROS), each service subscribes to messages in the system and responds to queries. UxAS uses the open-source library ZeroMQ to connect all services to each other. The content of each message conforms to the Light-weight Message Control Protocol (LMCP) format. Software classes providing LMCP message creation, access, and serialization/deserialization are automatically generated from simple XML description documents (see the LmcpGen project). These same XML descriptions detail the exact data fields, units, and default values for each message. Since all UxAS services communicate with LMCP formatted messages, a developer can quickly determine the input/output data for each service. In a very real sense, the message traffic in the system exposes the interaction of the services that are required to achieve autonomous behavior.

Consider a simple example: the automated construction of the flight pattern to conduct surveillance of geometric lines (e.g. perimeters, roads, coasts). A “line search task” message describes the line to be imaged and the desired camera angle. Using this input description, a line search service calculates the appropriate waypoints to achieve the proper view angle. When the UAV arrives at the first waypoint corresponding to the line search task, the line search service continuously updates the desired camera pointing location to smoothly step the camera along the intended route.

In addition to surveillance pattern automation, UxAS contains services that automate route planning, coordinate behavior among multiple vehicles, connect with external software, validate mission requests, log and diagram message traffic, and optimize task ordering. In all, UxAS has approximately 30 services.

A core functionality provided by UxAS is the mechanism to calculate near-optimal task allocation across teams of unmanned vehicles. With a collection of tasks that require servicing and a pool of vehicles available to service those tasks, UxAS is able to determine which vehicle should do which task in the proper order. This task assignment pipeline is carried out by a series of services working together in a complex sequence.

Supported Operating Systems

For an Ubuntu 16.04 or Mac OS X system with prerequisites installed, UxAS should build from source without issue. Support for Windows is available on Windows 7 and 10 using Visual Studio.

Configure System for UxAS Build

For Linux and Mac systems, the install prerequisities script from the OpenUxAS repository (bash install_prerequisites.sh) automates the installation of all the necessary tools for compilation of OpenUxAS. Note, on Mac XCode must first be installed before running the install script.

Complete manual step-by-step instructions for each operating system are included below:

• Linux
• Mac
• Windows

Build UxAS

Expected file system layout:

./
  OpenAMASE
  LcmpGen
  OpenUxAS

1. Checkout OpenUxAS: git clone https://github.com/afrl-rq/OpenUxAS.git
2. Checkout LmcpGen: git clone https://github.com/afrl-rq/LmcpGen.git
3. Build LmcpGen: cd LmcpGen; ant jar; cd ..
4. Auto-generate source code for LMCP libraries: cd OpenUxAS; bash RunLmcpGen.sh; cd ..
5. Prepare UxAS specific patches to external libraries: cd OpenUxAS; ./prepare; cd ..
6. (optional) Checkout OpenAMASE: git clone https://github.com/afrl-rq/OpenAMASE.git
7. (optional) Build OpenAMASE: cd OpenAMASE/OpenAMASE; ant jar; cd ../..

Note, ./prepare needs to be done prior to the first build and any time a file is modified in one of the /3rd/wrap_patches subdirectories or the /3rd/*.wrap.tmpl files.

This also needs to be done any time you move or rename your source tree.

Building at the Command Line

1. From the OpenUxAS local repository (i.e. cd OpenUxAS)
2. Configure for release build: in terminal
   • meson build --buildtype=release
3. Configure for debug build: in terminal
   • meson build_debug --buildtype=debug
   • These two steps only need to be done prior to the first build. If you modify the Meson files, just build as normal in step 3 and the changes will be automatically incorporated.
4. Build UxAS: in terminal
   • ninja -C build all
   • This step is the only step necessary in day-to-day development work. It's the Meson equivalent of make all. Note that the name of ninja may differ by distro. On Fedora, for example, it's ninja-build.
   • To clean the build, add the clean target at the end of your ninja command: ninja -C build clean
5. Run UxAS tests: in terminal
   • ninja -C build test
   • Confirm all tests passed

Compiling using NetBeans (Debug Mode)

1. Install NetBeans and Oracle Java JDK
2. Enable C/C++ plug-in in NetBeans
   • Choose Tools->Plugins from the top menu
   • In the Available Plugins tab, search for C++
   • Select C/C++ and click Install
3. Select File->New Project
4. Choose C/C++ Project with Existing Sources and click Next
5. Specify the OpenUxAS folder
6. Select the Custom option under Select Configuration Mode and click Next
7. No changes under Pre-Build Action, click Next
8. Set the Clean Command to ninja -C build_debug clean
9. Set the Build Command to ninja -C build_debug uxas and click Next
10. No changes under Source Files, click Next
11. No changes under Code Assistance Configuration, click Next
12. Change Project Name to UxAS and click Finish

For Linux systems, Netbeans will automatically use the gdb debugger. On Mac OS X, gdb must be installed and signed (see Neil Traft's guide).

Running the Examples

1. Assuming that in the file system, OpenAMASE is at the same level as OpenUxAS
2. Add python package for UxAS plotting (src/Utilities/localcoords)
   • sudo -H python3 setup.py install
3. Run examples
   • Example 2: Follow README.md in examples/02_Example_WaterwaySearch
   • Example 3: Follow README.md in examples/03_Example_DistributedCooperation

Building the Documentation

Building the Documentation on Ubuntu Linux / Bash on Ubuntu on Windows -or- Mac OS X (Partially-Automated)

The following is a bash script that helps to partially-automate the "building the documentation" processes that are documented in this README.md file below.

This has been tested-working on Ubuntu 16.04, as of 2017-05-23.

1. Download the script from the OpenUxAS repository (bash build_documentation.sh) OR cd to your git cloned OpenUxAS directory
2. Run the script at the terminal: bash build_documentation.sh
3. Follow the on-screen instructions

Note that this will pop open two html files in your webbrowser and also the pdf manual when run.

Building the Documentation Manually

If you'd like to do this process manually, then:

1. The User Manual can be generated by running: pdflatex UxAS_UserManual.tex in the folder doc/reference/UserManual/
2. Create HTML Doxygen reference documenation:
   • Open terminal in directory doc/doxygen
   • sh RunDoxygen.sh
   • In newly created html folder, open index.html
3. Doxygen PDF reference manual can be created by:
   • Copy the line from ExtraLineToFixLatex.txt into doc/doxygen/latex/refman.tex just above the line %===== C O N T E N T S =====
   • In the folder doc/doxygen/latex run the command pdflatex refman.tex
   • The complete reference manual can be found at doc/doxygen/latex/refman.pdf

About External Dependencies

In porting the UxAS build system to Meson/Ninja, we've taken advantage of wrap facility to import and build 3rd-party libraries. The advantage of this approach is that the main UxAS repo no longer needs to contain these libraries.

There are some rough edges. The wrap facility (as of April 2017) was designed to store the necessary metadata on a server operated by the Meson/Ninja maintainers. There's a very short list of wrapped projects available from this server. Worse, the wrap facility is not properly designed for project-local use: "patches" (often, only the necessary meson.build file) are downloaded by the wrap facility, which offers no provision for relative URLs.

Furthermore, the patch file must be in an archive format. This means that the wrapped project's meson.build file must be tarred (actually, the wrap facility will handle other archive formats) for reference from the project's wrap file, and the wrap file must contain a valid SHA256 hash of the patch archive file.

Clearly, this will complicate maintenance. On the plus side, once an external project is properly wrapped, it shouldn't require further work unless you require a different version of the project.

We've taken the approach of stashing valid meson.build files in the 3rd/wrap_patches directory. This is the place to store other patched files (if any) needed for the build of the external project. Note that "patch" does not refer to a context or unified diff, but rather to an archive containing new and changed files that overwrite the unzipped sources. The wrap facility is not able to patch using diff files.

About Boost

Boost is handled slightly differently from the other external dependencies, in that the build system attempts to use a system-provided version of Boost before falling back on the wrap facility as a last resort.

Boost uses a bespoke configuration and build system that is very difficult to replicate with a Meson-based wrap build, and so Meson itself handles Boost differently from other pkg-config-provided system dependencies.

System-provided Boost

We strongly recommend using a system-provided Boost from brew, apt-get, etc. If you have a system-provided boost, but during Meson's configuration phase, you see something like the following, try setting your BOOST_ROOT environment variable to the prefix of your system-installed packages (most likely /usr/local for MacOS with Homebrew):

Dependency Boost (filesystem, regex, system) found: NO

If you have a system-provided Boost but this message still does not go away, open an issue with details of your system configuration.

Boost via Meson wrap

If no system-provided Boost is available, Meson will fall back to using the wrap we maintain alongside the other external dependencies. This will probably work on 64-bit Linux systems, but unexpected trouble may arise on other platforms.

Removing External Dependencies

If you ever feel the need to refresh external dependencies, you'll need to remove both the downloaded files and the expanded directories:

./rm-external

This script depends upon the presence of the patch tarballs installed in the /3rd directory by ./prepare.

Detailed Prerequisite Steps

The install prerequisities script (bash install_prerequisites.sh) will automate the following steps.

Install Prerequisites on Ubuntu Linux

1. Ensure dependency search is supported: in terminal
   • sudo apt-get install pkg-config
2. Install git: in terminal
   • sudo apt-get install git
   • sudo apt-get install gitk
3. Install OpenGL development headers: in terminal
   • sudo apt-get install libglu1-mesa-dev
4. Install unique ID creation library: in terminal
   • sudo apt-get install uuid-dev
5. Install BSD development library: in terminal
   • sudo apt-get install libbsd-dev
6. Install Boost libraries (optional but recommended; see external dependencies section): in terminal
   • sudo apt-get install libboost-filesystem-dev libboost-regex-dev libboost-system-dev
7. Install doxygen and related packages (optional): in terminal
   • sudo apt-get install doxygen
   • sudo apt-get install graphviz
   • sudo apt-get install texlive
   • sudo apt-get install texlive-latex-extra
8. Install pip3: in terminal
   • sudo apt install python3-pip
   • sudo -H pip3 install --upgrade pip
9. Install ninja build system: in terminal
   • sudo -H pip3 install ninja
10. Install meson build configuration: in terminal
    • sudo -H pip3 install meson==0.42.1
11. Install python plotting capabilities (optional): in terminal
    • sudo apt install python3-tk
    • sudo -H pip3 install matplotlib
    • sudo -H pip3 install pandas
12. Install NetBeans and Oracle Java JDK (optional)
    • Download the Linux x64 version
    • Run downloaded install script: in terminal
    • cd ~/Downloads; sh jdk-8u131-nb-8_w-linux-x64.sh
    • Click Next three times, then Install
13. Enable C/C++ plug-in in NetBeans (optional)
    • Open NetBeans (in Ubuntu search, type NetBeans)
    • Choose Tools->Plugins from the top menu
    • In the Available Plugins tab, search for C++
    • Select C/C++ and click Install
14. Install Oracle Java run-time (required for LmcpGen): in terminal
    • sudo add-apt-repository ppa:webupd8team/java
    • sudo apt update; sudo apt install oracle-java9-installer
    • sudo apt install oracle-java9-set-default
15. Install ant for command line build of java programs: in terminal
    • sudo apt install ant
16. Remove any previously installed versions of ZMQ - They're likely to cause compile errors which, if fixed, will leave you with a seg-fault.
17. Build

Install Prerequisites on Mac OS X

The install prerequisities script will automate the following steps.

1. Install XCode
2. Enable commandline tools: in terminal xcode-select --install
3. Install homebrew (must be administrator): in terminal sudo ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
4. Add homebrew to path: in terminal echo $(export PATH="/usr/local/bin:$PATH") >> ~/.bash_profile
5. Install git: in terminal brew install git
6. Install unique ID library: in terminal brew install ossp-uuid
7. Install Boost library and configure it in a fresh shell: in terminal
   • brew install boost
   • echo 'export BOOST_ROOT=/usr/local' >> ~/.bash_profile
   • bash
8. Install doxygen and related packages (optional): in terminal
   • brew install doxygen
   • brew install graphviz
   • brew cask install mactex
9. Install pip3: in terminal
   • brew install python3
10. Install ninja build system: in terminal
    • brew install cmake
    • brew install pkg-config
    • sudo -H pip3 install scikit-build
    • sudo -H pip3 install ninja
11. Install meson build configuration: in terminal
    • sudo -H pip3 install meson==0.42.1
12. Install python plotting capabilities (optional): in terminal
    • sudo -H pip3 install matplotlib
    • sudo -H pip3 install pandas
13. Install Oracle Java run-time (required for LmcpGen)
14. Install ant for command line build of java programs: in terminal
    • brew install ant
15. Install NetBeans and Oracle Java JDK (optional)
    • Download the Mac OSX version
    • Install .dmg
16. Enable C/C++ plug-in in NetBeans (optional)
    • Open NetBeans
    • Choose Tools->Plugins from the top menu
    • In the Available Plugins tab, search for C++
    • Select C/C++ and click Install
17. Build

Prep and Build on Windows

1. Install Visual Studio 2017 Community Edition
   • Ensure C++ selected in Workloads tab
   • Ensure Git for Windows is selected in Individual components tab
2. Install Git with Bash shell
3. Install Python 3
   • Make sure to check Add Python 3.7 to PATH
   • Choose standard install (Install Now, requires admin)
   • Verify installation by: python --version in cmd prompt
   • Verify pip is also installed: pip --version in cmd prompt
   • If unable to get python on path, follow this answer using location C:\Users\[user]\AppData\Local\Programs\Python\Python37-32\
4. Install meson (due to Boost linking difficulty, a patched version of meson is required)
   • In Git Bash shell: git -c http.sslVerify=false clone https://github.com/derekkingston/meson.git
   • Install meson in Git Bash shell: cd meson; python setup.py install
5. Install Boost 1.67
   • Note: the above link is for VS2017 pre-compiled libraries. To compile from source, you must install at the location: C:\local\boost_1_67_0
6. Pull UxAS repositories (from Git Bash shell)
   • git -c http.sslVerify=false clone https://github.com/afrl-rq/OpenUxAS.git
   • git -c http.sslVerify=false clone https://github.com/afrl-rq/LmcpGen.git
   • git -c https://github.com/afrl-rq/OpenAMASE.git
7. (optional) Build OpenAMASE or download and place in the OpenAMASE\OpenAMASE\dist directory
   • Load the OpenAMASE project in NetBeans and click Build
8. Auto-create the UxAS messaging library
   • Download released executable from GitHub
   • Place LmcpGen.jar in LmcpGen/dist folder
   • From the Git Bash shell in the root UxAS directory, run bash RunLmcpGen.sh
   • Note: For simplicity, make sure the LMCPGen, OpenUxAS, and OpenAMASE repositories follow the folder structure labeled in the Build UxAS section.
9. Prepare build
   • Open VS command prompt (Tools -> Visual Studio Command Prompt)
   • Note: If the Visual Studio Command Prompt is absent from Visual Studio, it is also possible to perform the following actions by searching for the Developer Command Prompt for VS 2017 application and switching the working directory to the root OpenUxAS directory
   • python prepare
   • meson.py build --backend=vs
   • A Visual Studio solution named UxAS.sln will be in the build folder
10. Build project with Visual Studio
    • Open project file UxAS.sln in the OpenUxAS/build directory
    • (optional) Remove REGEN, RUN_INSTALL, and RUN_TESTS projects from the solution
    • In the Solution Explorer, right-click the uxas project, and select Build from the context menu

Caveats

• The Visual Studio backend for Meson mostly works, but will fail when regenerating build files. If you modify one of the meson.build files, delete the build directory and run meson.py build --backend=vs again. The steps following the meson.build command must also be performed.
• The UxAS test suite uses some hardcoded POSIX-style paths, and so does not currently work on Windows.