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 afrl.rq.opensource@us.af.mil.
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.
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.
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:
Expected file system layout:
./
OpenAMASE
LcmpGen
OpenUxASgit clone https://github.com/afrl-rq/OpenUxAS.gitgit clone https://github.com/afrl-rq/LmcpGen.gitcd LmcpGen; ant jar; cd ..cd OpenUxAS; bash RunLmcpGen.sh; cd ..cd OpenUxAS; ./prepare; cd ..git clone https://github.com/afrl-rq/OpenAMASE.gitcd 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.
cd OpenUxAS)meson build --buildtype=releasemeson build_debug --buildtype=debugninja -C build allmake all. Note that the name of ninja may differ by distro. On Fedora, for example,
it's ninja-build.clean target at the end of your ninja
command: ninja -C build cleanninja -C build testAvailable Plugins tab, search for C++C/C++ and click InstallC/C++ Project with Existing Sources and click NextOpenUxAS folderCustom option under Select Configuration Mode and click NextPre-Build Action, click NextClean Command to ninja -C build_debug cleanBuild Command to ninja -C build_debug uxas and click NextSource Files, click NextCode Assistance Configuration, click NextProject Name to UxAS and click FinishFor Linux systems, Netbeans will automatically use the gdb debugger. On Mac OS X,
gdb must be installed and signed (see Neil Traft's guide).
OpenUxASsudo -H python3 setup.py installexamples/02_Example_WaterwaySearchexamples/03_Example_DistributedCooperationThe 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.
bash build_documentation.sh) OR cd to your git cloned OpenUxAS directorybash build_documentation.shNote that this will pop open two html files in your webbrowser and also the pdf manual when run.
If you'd like to do this process manually, then:
pdflatex UxAS_UserManual.tex in the folder doc/reference/UserManual/doc/doxygensh RunDoxygen.shhtml folder, open index.htmlExtraLineToFixLatex.txt into doc/doxygen/latex/refman.tex just above the line %===== C O N T E N T S =====doc/doxygen/latex run the command pdflatex refman.texdoc/doxygen/latex/refman.pdfIn 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.
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.
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: NOIf you have a system-provided Boost but this message still does not go away, open an issue with details of your system configuration.
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.
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.
The install prerequisities script (bash install_prerequisites.sh) will automate the following steps.
sudo apt-get install pkg-configgit: in terminal
sudo apt-get install gitsudo apt-get install gitksudo apt-get install libglu1-mesa-devsudo apt-get install uuid-devsudo apt-get install libbsd-devsudo apt-get install libboost-filesystem-dev libboost-regex-dev libboost-system-devsudo apt-get install doxygensudo apt-get install graphvizsudo apt-get install texlivesudo apt-get install texlive-latex-extrasudo apt install python3-pipsudo -H pip3 install --upgrade pipsudo -H pip3 install ninjasudo -H pip3 install meson==0.42.1sudo apt install python3-tksudo -H pip3 install matplotlibsudo -H pip3 install pandascd ~/Downloads; sh jdk-8u131-nb-8_w-linux-x64.shNext three times, then InstallNetBeans)Available Plugins tab, search for C++C/C++ and click Installsudo add-apt-repository ppa:webupd8team/javasudo apt update; sudo apt install oracle-java9-installersudo apt install oracle-java9-set-defaultant for command line build of java programs: in terminal
sudo apt install antThe install prerequisities script will automate the following steps.
xcode-select --installhomebrew (must be administrator): in terminal
sudo ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"homebrew to path: in terminal echo $(export PATH="/usr/local/bin:$PATH") >> ~/.bash_profilegit: in terminal brew install gitbrew install ossp-uuidbrew install boostecho 'export BOOST_ROOT=/usr/local' >> ~/.bash_profilebashdoxygen and related packages (optional): in terminal
brew install doxygenbrew install graphvizbrew cask install mactexbrew install python3brew install cmakebrew install pkg-configsudo -H pip3 install scikit-buildsudo -H pip3 install ninjasudo -H pip3 install meson==0.42.1sudo -H pip3 install matplotlibsudo -H pip3 install pandasant for command line build of java programs: in terminal
brew install antAvailable Plugins tab, search for C++C/C++ and click InstallWorkloads tabGit for Windows is selected in Individual components tabAdd Python 3.7 to PATHInstall Now, requires admin)python --version in cmd promptpip --version in cmd promptC:\Users\[user]\AppData\Local\Programs\Python\Python37-32\git -c http.sslVerify=false clone https://github.com/derekkingston/meson.gitcd meson; python setup.py installC:\local\boost_1_67_0git -c http.sslVerify=false clone https://github.com/afrl-rq/OpenUxAS.gitgit -c http.sslVerify=false clone https://github.com/afrl-rq/LmcpGen.gitgit -c https://github.com/afrl-rq/OpenAMASE.gitOpenAMASE\OpenAMASE\dist directory
BuildLmcpGen.jar in LmcpGen/dist folderbash RunLmcpGen.shDeveloper Command Prompt for VS 2017 application and switching the working directory to the root OpenUxAS directorypython preparemeson.py build --backend=vsUxAS.sln will be in the build folderUxAS.sln in the OpenUxAS/build directoryREGEN, RUN_INSTALL, and RUN_TESTS projects from the solutionSolution Explorer, right-click the uxas project, and select Build from the context menumeson.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.