The ACSObjects package contains a set of classes that allow the user to organize and analyze data gathered from Pixhawk flash logs in a meaningful way. This code was written with a very specific use case in mind. While many tools exist to analyze single pixhawk logs, there is not much in the way of software to analyze the performance of many pixhawk-using vehicles simultaneously. The ARSENL UAV swarm project that this code was written for has had 50 UAVs flying simultaneously. This package provides tools for working with data from projects like these. To easily support this paradigm, the data files must be stored in a very specific way as will be described (see "Preconditions for Using ACSObjects").
A "Sortie" is defined as a single aircraft's flight, from launch to landing. These Sortie objects will include data from before and after the flight as well (they contain all data from the log file generated during flight).
Note: The data that ACSObjects uses has been downsampled to 5 Hz, even if the originally logged data was recorded at a higher frequency.
A "Mission" is defined as the collection of aircraft that flew simultaneously. The Mission is composed of the Sortie objects that made up the Mission.
An "Event" is used to group all of the Missions and Sorties that occurred at a single field event.
The objects in this library provide a fairly robust graphing capability. However, for more fine-grained control of graph appearance, we recommend generating your graph in a separate script and using these objects to get the data to be graphed.
Currently, some of the features of the package rely on storing the data files in a certain way. For most calculations, ACSObjects relies on .csv files generated from the sdlog2dump.py script. The .csv files generated by this script downsample the data to 5 Hz. Here is the currently assumed file structure:
Tree Structure:
--YYYY-MM-DD --- Mission1 ------- Sortie1-UAV4 --- FX#-M01-S01-UAV4.BIN
| | |- FX#-M01-S01-UAV4.csv
Event#----| |
| -- Sortie2-UAV5 --- FX#-M01-S02-UAV05.BIN
| | |- FX#-M01-S02-UAV05.csv
|
--YYYY-MM-DD --- Mission2 ------- Sortie1-UAV10 --- FX#-M02-S01-UAV10.BIN
| |- FX#-M02-S01-UAV10.csv
|
|
-- Sortie1-UAV11 --- FX#-M02-S02-UAV11.BIN
|- FX#-M02-S02-UAV11.csv
.
Before use, ACSObjects must be built and installed using the following (for installation to the user's local path):
python setup.py build install --user
Any of the objects in this module are instantiated with a path to the corresponding part of the data tree. A Sortie object should be given a Sortie folder path, a Mission object should be given a Mission folder path, and an Event object should be given an Event folder path.
from ACSObjects.Event import Event
from ACSObjects.Mission import Mission
from ACSObjects.Sortie import Sortie
# Instantiate a Sortie:
my_sortie = Sortie('/home/<user>/Event23/2015-07-13/Mission1/Sortie1-UAV4')
# Instantiate a Mission:
my_mission = Mission('/home/<user>/Event23/2015-07-13/Mission1')
# Instantiate an Event:
my_event = Event('/home/<user>/Event23')
When an Event or Mission object is instantiated, it will automatically load the lower-level parts of the hierarchy. Thus, instantiating a Mission will create Sortie objects for all Sorties in the Mission, and instantiating an Event object will create Mission objects for all Missions in the event (which in turn generate Sortie objects). These children objects can be selected from dictionaries stored in the Event and Mission objects.
from ACSObjects.Event import Event
from ACSObjects.Mission import Mission
from ACSObjects.Sortie import Sortie
my_event = Event('/home/<user>/Event23')
my_mission = my_event.mission_list[1]
my_sortie = my_mission.sortie_list[1]
Note that the three objects created here are identical to those created in the previous example. Mission.mission_list and Sortie.sortie_list are actually dictionaries. The key (index) corresponds to the number of the Mission or Sortie.
For most uses, the analyze method should be called first. Event, Mission, and Sortie objects all have this method. The analyze method will run a series of methods that will gather important information such as takeoff and landing times, number of sorties in a mission, and number of missions in an event.
For example, my_event.analyze() will find the basic important information about all missions and sorties contained in my_event.
Further examples of using the module can be seen in the examples.py file.
The Event, Mission, and Sortie objects contain methods that will analyze data from single or groups of UAVs. These objects also have elementary graphing capabilities. However, functions that use these objects to draw complex, single-purpose graphs probably do not belong inside of the Event, Mission, or Sortie classes. Instead, these longer functions that often make extensive use of graph formatting can be stored in the MissionAnalysis.py and SortieAnalysis.py files. Examples of functions that should be stored here are the concurrent sortie graphing function, which makes a histogram showing number of UAVs aloft vs. time, and the assess_launch function which plots several values of interest around the time of launch.
The documentation from this module has been generated automatically with the python module pdoc. If updated documentation needs to be created, pdoc can be used to make it. pdoc can be installed with:
sudo pip install pdoc
If pip is not installed please install pip with:
sudo apt-get install python-pip
Code for Automatic Documentation Generation
pdoc ACSObjects --html --html-dir <output_directory>
If there is already documentation in the specified output folder then the above command needs to be called with the --overwrite flag.
Unfortunately, I haven't had much time to test this code on the target data. As a result there are some areas of the code that probably need refinement.
If more methods are added to any of the classes in this module, it is possible that they should be added to the analyze method of the corresponding class. Not all new methods need to be called by analyze. However, any data that will be wanted frequently and does not take long t o run should have a corresponding method call in analzye.
A similar decision must be made regarding the summarize method. summarize will print summary information about an Event, Mission, or Sortie to a text file. Any new methods that return data deemed to be relevant in this format should be called in the summarize method in the corresponding class.
I currently have no plans to add to or change this code. However, if anyone stumbles upon this and has a desire to expand upon the code here, I am more than happy to collaborate and provide further information about the thought process behind developing this so far.
Email: [email protected]