Table of Contents

• Prerequisites
• Build Steps
  • DigiMesh Library
    • Build
    • Environment Variables
  • MACE
    • Tools libraries
    • Environment Variables
    • Build
  • MACE GUI
• (Optional) ROS Setup
• Running MACE

Prerequisites

Prior to building on Linux, you should make sure that your distribution is up to date. Run sudo apt-get update && sudo apt-get upgrade prior to running anything of the following steps.

Build tools

To clone the repository, you will need to install git command line interface. Once installed, test that the installation was successful by typing git --version in a terminal window.

To install various third party libraries needed for MACE, you will also need to install CMake. Once installed, test that the installation was successful by typing cmake --version in a terminal window.

MACE software prerequisites

Before compiling MACE from source, you will need a few things. First, you will need Qt (Download installer from HERE) and the Qt Creator IDE that comes with it. MACE currently depends on minimal libraries from Qt, however the easiest way to install MACE is still to use the Qt Creator IDE. Download the default installer and follow the steps. When you get the the components screen, make sure you select gcc under the Qt version you prefer (other build options such as Android build components are not required). For most users, the latest version of Qt is sufficient. The screenshot below shows an example of the components menu--note that the version numbers of Qt and gcc may not be up to date, this is just an example:

If you choose to install Qt using a method other than the online installer, you may need to install other build tools. However, this installation has not been tested without using the default Qt installation steps.

MACE User Interface

If you wish to use the packaged user interface, you will need to install NodeJS for your platform as well as Yarn. For NodeJS, download the recommended installer and follow the default steps. Do the same for Yarn.

ArduPilot SITL Simulation

If you wish to use a MAVLink simulated vehicle, the ArduPilot simulation has been used extensively with MACE. To install, follow the instructions HERE.

Build Steps

Digimesh Library

Clone the Digimesh library distributed by Heron Systems by navigating to wherever you wish to clone the repository. An example would be /_code. In a command prompt:

$ cd /_code
$ git clone https://github.com/heronsystems/OpenMACEDigiWrapper

In the directory where the wrapper was cloned, create three new directories: MACEDigiWrapper/lib, MACEDigiWrapper/bin, and MACEDigiWrapper/include.

Building the Digimesh Wrapper

There are two options when building the Digimesh wrapper. Follow the instructions for your preferred method:

• Qt Creator IDE build
• Command line build

Qt Creator IDE build

Using the Qt Creator IDE, open the MACEDigiWrapper.pro file, making sure to configure the project using a MinGW enabled kit. Go to the Projects tab and select Build.

Add a build step using the dropdown and select Make.

In the Make arguments: box, add install. Generated headers and libraries should install to the /include and /lib directories off the root of the project made prior to building.

Command line build

Navigate to /MACEDigiWrapper and use qmake to generate Makefiles. Then make the libraries and install header files with the following commands:

$ cd /_code/MACEDigiWrapper
$ qmake
$ make
$ make install

To make library installs easier, we first want to add *.conf file that points to MACEDigiWrapper/lib directories. In the example below, MACEDigiWrapper was cloned in the /_code directory. Make sure to replace this with the appropriate path. This will allow us to "install" MACE libraries in order to run MACE via the command line.

$ echo "/_code/MACEDigiWrapper/lib" > /etc/ld.so.conf.d/MACEDigiWrapper.conf

After building any changes in the MACEDigiWrapper libraries, run the following command:

$ sudo ldconfig

Digimesh Environment Variables

To build MACE later, you will need to set environment variables for the MACEDigiWrapper. Open the ~/.bashrc file with your preferred text editor and add the following lines to the end of the file:

export MACE_DIGIMESH_WRAPPER="/_code/MACEDigiWrapper"
export PATH=$PATH:/home/puffin/_code/MACEDigiWrapper/lib

Make sure to change the paths to where you cloned MACE (i.e. replace /home/puffin/_code with your directory structure).

Make sure to run source ~/.bashrc to have the changes take effect. This edit to the .bashrc file will have the MACE_DIGIMESH_WRAPPER set in every terminal and add the library directory to the path. The above path (i.e. /_code/MACEDigiWrapper) is an example, however this path should reflect wherever the root directory of the MACEDigiWrapper repository is. The MACE_DIGIMESH_WRAPPER environment variable should be set such that %MACE_DIGIMESH_WRAPPER%/include and %MACE_DIGIMESH_WRAPPER%/lib resolves to the appropriate directories.

---

MACE

Clone the MACE repository distributed by Heron Systems by navigating to wherever you wish to clone the repository. An example would be /_code. In a command prompt:

$ cd /_code
$ git clone https://github.com/heronsystems/OpenMACE

MACE Environment variables

Similar to the MACEDigiWrapper, we must add an environment variable to build MACE (see the Digimesh Environment Variables section above). Add an environment variable MACE_ROOT set to that root such that %MACE_ROOT%/include and %MACE_ROOT%/lib resolves to the appropriate directories. Add the following lines to your ~/.bashrc file:

export MACE_ROOT=/home/puffin/_code/MACE
export PATH=$PATH:/home/puffin/_code/MACE/lib

Make sure to change the paths to where you cloned MACE (i.e. replace /home/puffin/_code with your directory structure). Also, run source ~/.bashrc for the changes to take effect.

Tools libraries

Prior to building MACE, there are third party Tools libraries that must be installed. Follow the instructions on the wiki to install each library (Installing Tools Libraries);

Building the MACE application

Similar to the MACEDigiWrapper build steps above, you will need to add MACE/bin, MACE/include, and MACE/lib directories.

There are two options when building the MACE application. Follow the instructions for your preferred method:

• Qt Creator IDE build
• Command line build

Building with Qt Creator IDE

After making those directories, go to the Projects tab and select Build. Add a build step using the dropdown and select Make. In the Make arguments: box, add install. Generated headers and libraries should install to the /include and /lib directories off the root of the project made prior to building (See the screenshots above in the Build steps -> Digimesh Library section for more detail).

Using the Qt Creator IDE, open the MACE/src.pro file, making sure to configure the project using a gcc enabled kit. Next, right click on the top level src directory and run QMake. Once this finishes, right click and run Build on the entire project. Note that this may take a while.

Building with Command Line

Next, change directory into the MACE root directory and build the project:

$ cd /_code/MACE
$ mkdir build
$ cd build
$ qmake ../src/src.pro
$ make
$ make install

To make library installs easier, we first want to add a *.conf file that points to MACE/lib directories. In the example below, MACE was cloned in the /_code directory. Make sure to replace this with the appropriate path. This will allow us to "install" MACE libraries in order to run MACE via the command line.

$ echo "/_code/MACE/lib" > /etc/ld.so.conf.d/MACE.conf

After building any changes in the MACE libraries, run the following command:

$ sudo ldconfig

MACE GUI

To run the MACE GUI, you will need NodeJS installed and configured as well as Yarn. Once configured, navigate to MACE/ElectronGUI/ and run yarn install. Once the installer installs the required Node packages, run the following commands.

Open a terminal and run:

$ yarn run watch

In a second terminal, run:

$ yarn run start

If successful, the MACE GUI will run, and you should see a blank map similar to the one below. Note that the start command above may take a few moments to actually start the GUI while it waits for the watch command to finish, and you may see a white screen while the command finishes.

(Optional) ROS Setup

ROS can be used to simulate worlds and sensors. Steps to set up ROS and configure various vehicles can be found in the ROS Setup wiki page.

MACE Living and Breathing test

To test your installation, you can run a simple test with a simulated vehicle connected to a MACE instance, which can be displayed and controlled via the MACE GUI. This test is outlined in the MACE Living and Breathing Test wiki page.