Open-DIS

1. Open-DIS Open Source Distributed Interactive Simulation Don McGregor (mcgredo at nps dot edu) Don Brutzman (brutzman at nps dot edu) John Grant (johnkonradgrant at yahoo dot com)

2. Open-DIS • Very few open source DIS implementations to date. We’ve done a couple for Java, but there are none that I know of for C++ • This results in duplicated effort as people re-implement the wheel • You can buy a commercial license, but this tends to not work well in an academic environment, or for projects with extremely long product life cycles • It takes time and effort to sort out licensing and stay within the license requirements, and avoiding this is valuable • What happens if the vendor goes away? • Free is an easy to licensing concept understand and work with

3. Licensing • Open-DIS uses the BSD open source license. Anyone can use or modify the code, and it is non-viral; using Open-DIS in your project does not make your project open source • You can modify the code if you like • You do not have to return changes to the authors (though this is appreciated and encouraged) • You can use it in commercial products • No license fees • Just use it!

4. Implementation Features • Java and C++ code implementation with a similar API • Java and C++ PDU objects can marshal themselves to DIS format • Java objects can also marshal themselves to XML and Java Object Serialization format • An XML schema is provided • Some supporting networking code and example implementations

5. Availability • http://sourceforge.net/projects/open-dis/ • Code is available as both tar.gz and subversion source code control downloads • Sourceforge forums and mailing lists for tech support • Full source code, not just binary releases

6. Implementation • The Java and C++ code was generated from an XML template • From this: • <attribute name="x" comment="velocity about the x axis"> • <primitive type="float" defaultValue="0"/> • </attribute>

7. Implementation • To this in Java: public class AngularVelocityVector extends Object implements Serializable { /** velocity about the x axis */ protected float x = 0; … public void setX(float pX) { x = pX;} @XmlAttribute public float getX() { return x; }

8. Implementation • And this in C++ AngularVelocityVector::AngularVelocityVector(): _x(0),_y(0), _z(0) {} AngularVelocityVector::~AngularVelocityVector(){} float AngularVelocityVector::getX() const {return _x;} void AngularVelocityVector::setX(float pX) {x = pX;}

9. Implementation • Getters, setters, constructors, and destructors for each PDU and sub-PDU object • Each PDU also has code to marshal itself to DIS format, and unmarshal itself • The “@XmlAttribute” annotations specify how the java objects should be marshalled to XML; in this case the X field will be marshalled as an attribute to the AngularVelocityVector element • < AngularVelocityVector … x=“17.0”/>

10. Implementation C++ .h, .cpp files C++ Code Generator XML Template Java Code Generator Java Source Files C# Code Generator C# Source Files

11. Implementation • If there are fundamental changes, we can modify the template code and re-generate the C++ and Java code • This code that generates C++ and Java is also provided if you want to do something different, or you can do another language generator if you like • About 4KLines of template XML and 1KLines of code generation to create ~30KLines of C++ and ~20KLines of Java • The generated Java and C++ is checked into source code control, so we can modify it directly as well

12. Implementation • Drawbacks to the approach: the classic problem of modifying code that is autogenerated. Changes are lost if you regenerate code after modifying it • Work around this by using automated patch files; apply patches after generation to regain manual edits

13. Why Not Schema • Originally we attempted to use XML Schema as the basis for generating Java and C++ source code • • C++ schema-to-code tools generated lousy code • • The generated code didn’t handle variable length lists well • • Parsing schema is complex, and there is no semantic link between variable length lists and the list length fields • • Different C++ and Java APIs • The template XML file and code generator gives us complete control over how the Java and C++ source code looks, and turned out to be not that difficult to write

14. XML • JDK 1.6 gives us the ability to marshal and unmarshal XML to and from Java objects via JAXB, which is built into the JDK release • Can generate a schema for DIS from the Java source code (provided) • As a result we get XML interoperability for free

15. Efficient XML Interchange • EXI is a W3C working group activity to design a more compact, faster to parse representation of the XML infoset • Exactly equivalent to an XML document, only in a more compact and faster to parse format • Relaxes XML’s text-only rule, implements many compression techniques, faster to parse than gzip of text XML • Working group is releasing to “final call” status as we speak

16. EXI • Interesting outcome: DIS in XML format run through EXI results in slightly smaller ESPDUs • Roughly 135 bytes per plain ESPDU vs. 144 for IEEE DIS when encoding with the DIS schema • There is some variation in EXI PDU sizes depending on the nature of the data, so they will sometimes be larger, but the general trend seems to be “about the same size or smaller” • This has interesting implications for DoD communications protocols: why not specify the protocol in XML, send it on the wire in EXI, results in about the same size as a plain binary message

17. Class Hierarchy Pdu Entity Interaction Family Warfare Family PDU Entity State PDU Collision PDU Fire PDU Detonation PDU

18. Object Hierarchy • PDUs also contain objects for major records, such as position, EntityType, orientation, etc ESPDU EntityID EntityType AltEntityType Location

19. Object Hierarchy • The major records defined in the DIS standard are represented as objects, such as location, an object that contains three double precision floating point numbers • The object knows how to marshal and unmarshal itself

20. Garbage Collection • This can create a problem when receiving a lot of PDUs. Every time a new PDU is created it may contain several objects within it • In Java this stresses the garbage collector in realtime operation • Observation: the vast majority of PDUs are ESPDUs. If we can optimize that we will solve most of the problem • The FastEntityStatePdu class “flattens” the object structure of entity state PDUs and consists only of primitive type fields • Eliminates 11 objects per ESPDU

21. Supporting Java Classes • PduFactory creates new Open-DIS PDU objects from binary data • Logger example saves PDU traffic to XML files • X3D example shows DIS being used to drive a 3D scene • XMPP example shows DIS in XML format being sent across chat channels

22. C++ Classes • Essentially identical to the Java classes, but lacking XML support • Uses HawkNL library for networking support. (You can also use plain old Berkeley sockets if you like)

23. Enumerations • There are a lot of arbitrary numbers associated with DIS (and HLA) called Entity Bit Values. Every PDU type has a number assoicated with it: ESPDU=1, Fire=2, etc • These are included in the wire format • It is inconvienient for programmers to work with magic numbers, so we want symbolic names to be associated with those • This is done via enumerations

24. Enumerations • Luckily, SISO has an XML document that describes these values called the EBV document <enum length="8" id="2" cname="pduheader.pdutype" name="PDU Type" source="3.2"> <enumrow id="0" description="Other"/> <enumrow id="1" description="Entity State"/> <enumrow id="2" description="Fire"/>

25. Enumerations • So: we read in the XML document and use the information contained in that to generate programming language enumerations public enum PduType { OTHER(0, "Other"), ENTITY_STATE(1, "Entity State"), FIRE(2, "Fire"),

26. Future Work • Not all PDUs correctly implemented--radio communications in particular needs work • Enumerations support (Done in Java) • HLA bridge • Support for DIS-200x • Dead Reckoning algorithms (Done) • Finite state machine support • Programming help appreciated