The Aquarius DIS PDU Suite is a collection of simple tools supporting the Distributed Interactive Simulation protocol used by the modeling and simulation industry. The suite provides the capability to easily heartbeat, capture, sequence a set of PDUs, and playback DIS PDUs from a captured session. It also supports the display of Entity State PDU locations on a world map.
Aquarius DIS PDU Suite is licensed under the GNU GPL 3.0.
Source code is available from the Git repository at the project's homepage: https://github.com/harlan3/aquarius-dis-pdu
Each of the tools within the suite can be compiled by executing the create_jar script located in the directory of each tool. The Java Developers Kit must be installed prior to compilation.
The projects are all preconfigured for eclipse. To import into the eclipse workspace, select File->Import and choose to import an existing project.
PDU Logger parses and logs DIS PDUs in both human readable and hexadecimal formats. The output of PDU Logger containing hexadecimal content can be used for populating the content of a single packet.xml data file used by the PDU Generator Heartbeat, as well as providing the content for the contiguous stream of packets which is used by the PDU Generation - Db playback (database).
PDU Logger works by associating a handler with each PDU type (see the source file ProcessDatagramThread.java). A default handler also exist to provide PDU identification and a hexadecimal dump of the PDU for unhandled PDU types.
There are currently handlers for DIS version 5 and DIS version 7. To configure the PDU logger for DIS 5 or DIS 7, run the Python script config_DISv5.py or config_DISv7.py, respectively.
PDU Logger provides the capability to filter specific types of PDUs. A default log_filter.cfg file will be generated when this file is not found by PDU Logger. All PDUs are logged by default, but this behavior can be modified by inserting or removing the comment hash marks before each defined PDU type in the log_filter.cfg file.
PDU Logger allows the specification of the port to listen on (3000 by default), a DIS exercise ID filter, and the specification of a multicast group. A datagram socket is used by default if the multicast group is not specified. PDU Logger supports both IPv4 and IPv6 addresses.
Use the -h option on this tool to view usage instructions.
-
Heartbeat Tab
Sends out a DIS PDU at a regular 5 second heartbeat interval. The data sent in the PDU is defined within an xml data file residing in the DIS version directories in pdu-generator-eclipse-ws. Any hex data defined within child data elements of the datagramPacket parent element will appear sequentially as byte data in the DIS PDU packet, while ignoring comments. There are currently DIS PDUs defined for DIS version 5 and DIS version 7, respectively. -
Sequence Tab
Sends out a sequence of selected DIS PDUs at an interval that is defined in the Sequence Composition file, which is generated by the PDU Sequencer tool. The time delay between PDUs is set in the settings menu in the Sequencer tool and it defaults to 5 seconds. This delay value will then appear between the DIS PDUs in the Sequence Composition file. -
Db Playback Tab
Db playback provides the capability to playback the PDUs of an entire DIS simulation exercise containing multiple PDU producers, that was captured using PDU Logger. These are the steps to generate a database and playback a captured exercise.-
Use PDU logger to capture all simulation exercise PDUs
cd aquarius-dis-pdu
python config_DISv7.py
cd pdu-logger-eclipse-ws
java -jar pdu_logger.jar -p 3000 > default_db.txt
start the simulation
when simulation is complete press ctrl-c
copy default_db.txt ..\pdu-generator-eclipse-ws\playback_db\ -
Generate the PDU manifest file and binary database files.
cd pdu-generator-eclipse-ws\playback_db
python create_playback_db default_db.txtThis will generate the default_db.man manifest, and default_db.bin database files.
-
Start PDU Generator and select the Db Playback tab. Then use the file selector to choose the default_db.man file for playback.
cd pdu-generator-eclipse-ws
java -jar pdu_generator.jar
select the previously generated default_db.man fileThe previously captured DIS PDUs are now played back. Note this will include all of the PDUs that were visible on the configured port (port 3000 is default) which is useful to capture multiple PDU producers.
-
PDU Sequencer generates a Composition XML file containing selected DIS PDUs for playback. The tool supports both dis_version_5 and dis_version_7, however the dis_versions cannot be mixed. Note that it is an error to save a composition tree with one DIS version, and then load the composition tree with a different DIS version selected. DIS PDUs are drag and dropped into the Composition Tree on top of the Message Group branch. Multiple Message Group branches can also be defined for organizational purposes. The Composition Tree can be saved for use at a later time. The time between PDUs can be modified under the Application Settings. Upon completion of the DIS pdu sequence selection, the Generate Composition File button can be pushed which generates the Sequence Composition file. This file is then used by the PDU Generation - Sequence tab to send out the selected DIS PDUs at the interval defined in the Application Settings of this tool.
If you would like to use a customized set of PDUs containing modified fields, create a new folder and copy the modified xml files into aquarius-dis-pdu-master\pdu-generator-eclipse-ws\dis_version_modified. All directories that start with “dis_version” will be available for selection by the pdu-generator and pdu-sequencer.
DIS simulation map supports the display of entity locations on an interactive map using the PDU generator to send heartbeats or sequences of Entity State PDUs. The force definition found in the Entity State PDU for Friendly, Opposing, or Neutral forces will show up as either Blue, Red or Green markers, respectively. Entity states have a time to live for 15 seconds, before being removed from the map. This provides an indication of how frequently the Entity State pdus are being published. Dead reckoning is not being used in the display of the the entities. Only the position information contained in the Entity State PDU is used for display. A cantor pairing function is used to uniquely identify each entity by creating a hash consisting of the Site, Application and Entity ID fields contained in the Entity State PDU. The cantor ID along with the entity marking contained which is contained in the received Entity State PDU are displayed on the secondary GUI. The secondary GUI also provides the simulation exercise with controls as well as the listing of all of the received Entity State PDUs. Selection of any of the received Entity State PDUs in this listing will highlight the corresponding entity on the map. The exercise number defaults to 0 which will receive all Entity State PDUs. Setting the exercise field to a value greater than 0 will filter out all other Entity State PDUs except for the exercise number specified in this field.
Source code for geotools which provides the map definition can be found here:
https://geotools.cvs.sourceforge.net/
Companion is a tool to assist in the modification of the hex data contained in the XML files used for representing the DIS PDU data. Many of the common conversion functions are supported by this tool.