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.
  Weve 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
• ltattribute name"x" comment"velocity about the
  x axis"gt
• ltprimitive type"float" defaultValue"0"/gt
• lt/attributegt

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 _at_XmlAttribute public float getX() return
x
8
Implementation

• And this in C

AngularVelocityVectorAngularVelocityVector()
_x(0),_y(0), _z(0) AngularVelocityVectorAng
ularVelocityVector() float AngularVelocityVecto
rgetX() const return _x void
AngularVelocityVectorsetX(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 _at_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
• lt AngularVelocityVector x17.0/gt

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 didnt 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 XMLs 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
  ESPDU1, Fire2, 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

ltenum length"8" id"2" cname"pduheader.pdutype"
name"PDU Type" source"3.2"gt ltenumrow id"0"
description"Other"/gt ltenumrow id"1"
description"Entity State"/gt ltenumrow id"2"
description"Fire"/gt
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