ICAROUS (Independent Configurable Architecture for Reliable Operations of Unmanned Systems) is a software architecture that enables the robust integration of mission specific software modules and highly assured core software modules for building safety-centric autonomous unmanned aircraft applications. The set of core software modules includes formally verified algorithms that detect, monitor, and control conformance to safety criteria; avoid stationary obstacles and maintain a safe distance from other users of the airspace; and compute resolution and recovery maneuvers, autonomously executed by the autopilot, when safety criteria are violated or about to be violated. ICAROUS is implemented using the NASA's core Flight Systems (cFS) middleware. The aforementioned functionalities are implemented as cFS applications which interact via a publish/subscribe messaging service provided by the cFS Software Bus.
https://nasa.github.io/icarous/
- ICAROUS V-2.0 - January 31, 2018
The code in this repository is released under NASA's Open Source
Agreement. See the directory LICENSES; see also the copyright notice at the end of this file.
César A. Muñoz (cesar.a.munoz@nasa.gov), NASA Langley Research Center.
The following repositories are required to run (or support software-in-the-loop tests for) ICAROUS (You will also have to update the submodules in these repositories if available)
- Ardupilot (Only required for software in the loop simulations)
- mavlink
- MAVProxy
- NLOPT (required only if using splines based path planner)
$git submodule update --init --recursive
ICAROUS makes use of the cmake build system. In order to setup a build, the following environment variables must be defined. These can be added to you ~/.bashrc script.
- PLEXIL_HOME= absolute path to the C++/Modules/Plexil folder found in the Icarous repository.
- OSAL_HOME= absolute path to the CFS/osal folder found in the Icarous repository.
- JAVA_HOME= absolute path to the Java installation directory. Typically located under
/usr/lib/jvm/java-* - NLOPT_PATH = absolute path to the nlopt library location (libnlopt.a) [Optional-only required if splines based planner is being used].
$cd CFS
$mkdir build
$cd build && cmake ..
$make cpu1-install
Run cmake with -DSITL=ON option to compile for software-in-the-loop simulations. Use -DSPLINES=ON to compile splines planner (This requires the nlopt library).
For compilation and linking errors related to missing libraries, check Modules/README.md.
The generated executable file is installed under cFS/bin/cpu1. Launch Icarous using the following command:
$sudo ./core-cpu1
Note that you need root previleges. When running ICAROUS on an embedded platform, one can make use of the nohup or screen command to avoid termination when a terminal is closed.
The intf_tbl.c located under cFS/apps/interface/fsw/tables defines parameters required to configure the serial port settings to connect to an autopilot.
The various parameters that control the behavior of ICAROUS can be found in cFS/bin/ram/icarous.txt. The default parameters found in icarous.txt were selected after several flight tests to yield acceptable performances.
We strongly recommend using MAVProxy as a ground station to communicate with ICAROUS. The custom MAVProxy modules provided in Python/CustomModules help upload geofence and visualize track bands.
- Install the custom modules provided as part of the ICAROUS repository:
$cd Python/CustomModules
$bash SetuMavProxy.sh <Location of MAVProxy/>
The MAVProxy ground station can be lauched using the run script located under the Scripts folder:
$./runGS.sh
Waypoints can be uploaded from MAVProxy using the wp command, e.g.,
wp load Examples/InputData/flightplan.txt
Geofence can be uploaded from MAVProxy using the geofence command, e.g.,
geofence load Examples/InputData/geofence.xml
Once waypoints and geofence are uploaded, the mission can be started from MAVProxy as follows:
long MISSION_START
Setup and launch the ardupilot SITL as described in http://ardupilot.org/dev/docs/setting-up-sitl-on-linux.html. By default, the ardupilot SITL is configured to output packets to udp port 14551. To interface Icarous with the ardupilot SITL, generate the SITL build and compile as follows:
$cd CFS
$mkdir build-stil
$cd build-sitl && cmake .. -DSITL=ON
$make cpu1-install
ICAROUS provides an application to communicate using OpenSplice DDS. Enable this application as follows:
-
Download and install an OpenSplice DDS 32bit version
-
Create an OpenSplice configuration file (.xml) with domain id 100. Follow the examples provided in the OpenSplice DDS distribution directory within
etc/conf. -
Add
dds_interfaceto theTGT1_APPLISTin the filecFS/apps/Icarous_defs/targets.cmaketo compile the dds application: -
Define the following environment variable for building:
OSPL_HOME: the path of the OpenSplice local installation; for example,/opt/OpenSplice/HDE/x86.linux
-
Define the following environment variables before executing ICAROUS:
OSPL_URI: the URI of the OpenSplice*.xmlconfiguration file for domain id 100 (the one of Step 2); for example,file:///opt/OpenSplice/HDE/x86.linux/etc/icarous-ospl.xml(note the three initial slashes)OSPL_HOME: the path of the OpenSplice local installation; for example,/opt/OpenSplice/HDE/x86.linuxLD_LIBRARY_PATH: it has to include the library path of the OpenSplice local installation in order for ICAROUS to find them; for example,/opt/OpenSplice/HDE/x86.linux/lib
An example command could look like this:
OSPL_URI="file:///opt/OpenSplice/HDE/x86.linux/etc/icarous-ospl.xml" \
OSPL_HOME="/opt/OpenSplice/HDE/x86.linux" \
LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/opt/OpenSplice/HDE/x86.linux/lib" \
sudo ./core-cpu1
ICAROUS integrates NASA's open source software packages DAIDALUS (Detect and Avoid Alerting Logic for Unmanned Systems) and PolyCARP (Algorithms and Software for Computations with Polygons). DAIDALUS provides detect and avoid capabilities, while PolyCARP provides geofencing capabilities.
The ICAROUS logo was designed by Mahyar Malekpour, NASA Langley Research Center.
Copyright 2016 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.
No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT "AS IS."
Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT'S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT.