Example Uses

This page contains links to various examples of using Open-DIS.

Send Entity State PDUs

Entity State PDUs contain the position, orientation, speed, and other data about a specific entity in the virtual world. To send a series of ESPDUs, using Java, first change directories to open-dis/languages/java/trunk and then type on the command line

ant runSender

This will send 100 Entity State PDUs. The entity type is set to be an M1A2 tank; the location is near Monterey, CA, and the entity will move due east. The above command assumes that Java and Apache Ant are installed on your machine and are on the path.

The source code for this is in the class edu.nps.moves.exmples.EspduSender, which can be viewed in the Source Forge repo browser here.

The class is called via the ant file; this is the relevant portion:

  <target name="runSender" depends="jar" description="run DIS example program">

        <java classname="edu.nps.moves.examples.EspduSender">

            <!-- Possible properties to pass into the program:

                 networkMode: unicast or multicast or broadcast

                 destinationIp: destination IP address. Could be mcast if in mcast mode, bcast if in bcast mode

                 port: Both source and destination port

            -->

             <sysproperty key="networkMode" value="multicast"/>   <!-- multicast, unicast, broadcast -->

             <sysproperty key="destinationIp" value="239.1.2.3"/> <!-- could be multicast (if in mc mode) or bcast -->

             <sysproperty key="port" value="62040"/>              <!-- Both source and destination port -->

            <classpath>

                <fileset dir="${dist}">

                    <include name="**/*.jar"/>

                </fileset>

            </classpath>

        </java>

    </target>

The PDUs will be sent to the address specified in the ant task. In this case, to the multicast group 239.1.2.3 on port 62040. We can also send to broadcast by changing some system properties in the ant file:

<sysproperty key="networkMode" value="broadcast"/>             

<sysproperty key="destinationIp" value="172.20.87.255"/>

The destination address is set to the local network’s broadcast address, which is calculated with the local IP and the subnet mask. There are many online calculators to determine this.

Receiving PDUs

Receiving PDUs is also straightforward.

ant runReceiver

Will listen (by default) on port 62040 and multicast group 239.1.2.3 for PDUs. The Java class being called is edu.nps.moves.examples.EspduReceiver, which can be viewed here.

The guts of the class are shown here:

packet = new DatagramPacket(buffer, buffer.length);

socket.receive(packet);

Pdu pdu = pduFactory.createPdu(packet.getData());

System.out.print("got PDU of type: " + pdu.getClass().getName());

The datagram packet is received, and the contents handed off to a PDU factory object. The PDU factory decodes the packet and returns a Java PDU of the appropriate class--EntityStatePdu, FirePdu, DetonationPdu, etc. You can determine the type of PDU returned either via the java instanceof operator or by calling getPduType() on the returned object.

DIS and XML

Open-DIS is capable of saving and reading PDUs in XML format. Again from the command line, type

ant runXml

This will run the Java class edu.nps.moves.examples.MarshallExample, which sends PDUs to an XML file named somePdus.xml, and then reads them back. The Java class can be viewed here.

An excerpt from the XML file is below.

<pdus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="firePdu" rangeToTarget="0.0" fireMissionIndex="0" timestamp="0" protocolVersion="6" protocolFamily="2" pduType="2" pduLength="0" padding="0" exerciseID="0">

DIS and SQL Databases

Open-DIS can save PDUs in a SQL database, such as MySQL. The DIS source code is marked up with Java Hibernate annotations, which allow Java objects to be saved to SQL databases. To run an example, first install MySQL on your local machine. You should create a database:

mysql -u root -p

mysql> create database opendis character set utf8;

By default the code code tries to connect to the MySQL user “root” on localhost with no password on the default MySQL port 3306. If you are using a different user or a password you should change the connection parameters.  The connection parameters are in the class edu.nps.moves.sql.DatabaseConfiguration.java. Other databases can be used as well, such as HSQLDB or Derby. The database example class will listen on port 62040 and multicast group 239.1.2.3 for DIS packets and save them to the opendis database in MySQL. The tables in the database will be created automatically.

Performance with SQL is OK; on MySQL approximately 1000 PDUs per second can be inserted into the database.

mysql> desc Pdu;

+-----------------+-------------+------+-----+---------+----------------+

| Field           | Type        | Null | Key | Default | Extra          |

+-----------------+-------------+------+-----+---------+----------------+

| pk_Pdu          | bigint(20)  | NO   | PRI | NULL    | auto_increment |

| exerciseID      | smallint(6) | NO   |     | NULL    |                |

| padding         | smallint(6) | NO   |     | NULL    |                |

| pduLength       | int(11)     | NO   |     | NULL    |                |

| pduType         | smallint(6) | NO   |     | NULL    |                |

| protocolFamily  | smallint(6) | NO   |     | NULL    |                |

| protocolVersion | smallint(6) | NO   |     | NULL    |                |

| timestamp       | bigint(20)  | NO   |     | NULL    |                |

+-----------------+-------------+------+-----+---------+----------------+

mysql> select count(*) from Pdu;

+----------+

| count(*) |

+----------+

|       39 |

+----------+