DIS Messages

Explaining DIS to Readers

DIS designers back in the 1980's and 1990's had to design a way to handle state information transmitted between hosts. It's a difficult problem to solve, and one that hadn't yet been discussed much at the time, but they came up with a pretty good solution.

As has been mentioned, DIS does this with dozens of different messages, but we have not yet discussed what the messages are, or how they are used. There are two aspects to describing DIS messages: what data is present, and how the data is arranged in the message. In addition to this we need to know how the message interacts with other messages. Consider one tank shooting at another tank. It will include information about what tank is shooting at another specific tank, and transmit that information in a known format and known quantity. But we also need information about how and when the simulation creates the firing PDU, and what part of the simulation issues the detonation PDU, and when that happens. That's information about the simulation's DIS protocol works.

Describing this--both the syntax and information in the PDU, and how the PDU interacts with other messages--can be distracting. In this tutorial section it is a tricky description problem to solve. Instead we generally describes the information that's in the message. This gives the programmer an idea about what data needs to be set or read when creating or reading a message. This section can (optionally) also describes what this intended for in general terms and how it interacts with other messages, but tries to be general.

But that's not enough in specific terms. In addition to this section, it's valuable to also look at the approach used in Section IV, which expands on the use of DIS traffic when implementing a specific task in compliance with the standard. For example, creating an entity, or one vehicle shooting at another. This gives more details on using DIS to accomplish a solution.

At the same time, this tutorial is not about how to write an implementation of DIS. It helps, but in the end, anyone writing their own implementation of the PDUs they are using. That involves acquiring a copy of the IEEE-1278 standard, which has greater detail about individual fields and where they are placed in messages. In the end, our interpretation will be less accurate than the defining IEEE-1278 standard itself, and you should read the source document.

Byte Order

DIS sends information in binary format between hosts. Those hosts may have CPUs from any of many vendors, and CPU makers have made different choices about how to represent numbers that take more than one byte to represent. An "integer," for example, often is represented with 4 bytes. But the question is, does the byte farthest to the left have the highest value, or the byte farthest to the right? This seems odd, but the CPU vendors made different choices for decades. The TCP/IP protocol largely chose to do "big endian" arrangement for multi-byte numbers. In fact, it happens so often that "big endian" is sometimes called "network byte order." But the Intel CPUs and, today, several other CPUs choose to use "little endian" multibyte numbers. (Endianness)

DIS sends many multi-byte data fields such as short integers, full integers, floating point numbers, and double precision floating point numbers. From a programming operation standpoint one danger is to write your own DIS code, read a PDU, and then incorrectly decode the DIS message as little endian binary data. This will cause very strange results, because the field values will be translated to values far away from reality.

This is often not as bad as it may seem for programmers. They often use pre-existing libraries that hide the byte order within a higher level API; in the case of DIS, there are almost always implementations that take care of endianness issues themselves. However, implementors of DIS simulations sometimes write their own DIS implementations, and they need to be aware of the issue. Those who choose to log messages to storage may need to be aware of byte order captures as well. Some PDUs include the ability to include simulation-generated data in binary format as well, and this is often set to big-endian format, while some others use little-endian format. If anything goes wrong with transmitted user data you should check the endian format used on both sides.

In the end, be aware of the possibility of error when you create a DIS message and then put it onto the network. There's a possibility that it will be placed onto the network in the wrong byte order.

Languages and Implementations

What's standardized in DIS is the messages placed on the network, not an API, or for that matter languages at all. While HLA has standardized APIs for Java and C++, DIS can be implemented in Python, Javascript, C++, Objective-C, C#, or any other language that can read and write binary data to the internet. Even within C++ there can be different APIs in the implementation.

To compare two open source implementations in the , consider KDIS and Open-DIS and their API implementations of one of an Entity State PDU, one of the most used PDUs. Both implementations have slightly different code to do exactly the same thing, in this case setting a number in an object that identifies what type of PDU message this is. In the case of KDIS, it looks like this:

//************************************
// FullName:    KDIS::PDU::Header6::SetPDUType
//              KDIS::PDU::Header6::GetPDUType
// Description: The type of PDU. Set by PDU automatically.
//              Only change if you know what you are doing.
// Parameter:   PDUType Type
//************************************
void SetPDUType( KDIS::DATA_TYPE::ENUMS::PDUType Type );
KDIS::DATA_TYPE::ENUMS::PDUType GetPDUType() const;

On the other hand, the Open-DIS C++ source code for getting and setting the PDU type in any PDU looks like this:

unsigned char getPduType() const; 
void setPduType(unsigned char pX); 

The function name for setting the pdu type is not the same--one uses a capital letters in places the other does not, to begin with. That means changing a C++ simulation to use Open-DIS rather than KDIS is likely to involve considerable work to change the simulation code. The function calls in the code would need to change, at least, and it would likely involve many other changes to the code logic.

Likewise, the API changes between languages. The Open-DIS Python language implementation of DIS relies on the programmer directly accessing the pduType data field of PDU object instead of using an accessor method:

self.pduType = 1

As does the Open-DIS Javascript implementation. The direct access (arguably) follows some of the Python and Javascript language writing habits, while C++ and Java typically use access methods to set or retrieve field values. The Java Open-DIS implementation relies on the "getPduType()" and "setPduType()" methods and the habits of the Java language. There is no standard at all for the names of the API functions to set the value--any method name at all is legitimate, and any popular language implementation can be used in any language capable of reading and writing binary data to the network.

List of All Families and PDUs

Entity Families

Families contain a group of PDUs that work with each other. For example, they may connect with messages that relate to live vehicles colliding with each other, or radio traffic. If your simulation simply doesn't have a radio it can't make use of those PDUs. On the other hand, it can make sense to detect the type of PDU being sent to silently discard it in the binary-to-code decoding, which would reduce the incoming traffic. You can also use different multicast channels for some areas.

0: Other.

Sometimes the sender will forget to include the PDU Family field. Not being able to retrieve it is a good sign that the PDU is defective. Simply discarding it is a good practice.

1: Entity Information/Interaction PDUs

The PDU number--each major PDU has a PDU number, which is not necessarily in sequential steps. In the Entity State PDU member the PDU is number 1, the Entity State Update is PDU number 67, and the Collision-Elastic PDU number 66. Click on the link to get an explanation of the PDU.

1. Entity State (1)
2. Collision (4)
3. Collision-Elastic (66)
4. Entity State Update (67)
5. Attribute (72)

See the links for more information on the PDUs.

2: Warfare

1. Fire (2)
2. Detonation (3)
3. Directed Energy Fire (68)
4. Entity Damage Status (69)

3: Logistics

1. Service Request (5)
2. Resupply Offer (6)
3. Resupply Received (7)
4. Resupply Cancel (8)
5. Repair Complete (9)
6. Repair Response (10)

4: Radio Communication

1. Create Entity (11)
2. Remove Entity (12)
3. Start/Resume (13)
4. Stop/Freeze (14)
5. Acknowledge (15)
6. Action Request (16)
7. Action Response (17)
8. Data Query (18)
9. Set Data (19)
10. Data(20)
11. EventReport(21)
12. Comment(22)

5: Simulation Management

1. Electromagnetic Emission (23)
2. Designator (24)
3. Underwater Acoustic (UA) (29)
4. IFF (28)
5. Supplemental Emission/Entity State (SEES) (30)

6: Distributed Emission Regeneration

1. Electromagnetic Emission (23)
2. Designator (24)
3. Underwater Acoustic (UA) (29)
4. IFF (28)
5. Supplemental Emission/Entity State (SEES) (30)

7: Entity Management

1. Transmitter (25)
2. Signal (26)
3. Receiver (27)
4. Intercom Signal (31)
5. Intercom Control (32)

8: Minefield

1. Minefield State (37)
2. Minefield Query (38)
3. Minefield Data (39)
4. Minefield Response Negative Acknowledgment (NACK) (40)

9: Synthetic Environment

1. Environmental Process (41)
2. Gridded Data (42)
3. Point Object State (43)
4. Linear Object State (44)
5. Areal Object State (45)

10: Simulation Management with Reliability

1. Create Entity-R (51)
2. Remove Entity-R (52)
3. Start/Resume-R (53)
4. Stop/Freeze-R (54)
5. Acknowledge-R (55)
6. Action Request-R (56)
7. Action Response-R (57)
8. Data Query-R (58)
9. Set Data-R (59)
10. Data-R(60)
11. EventReport-R(61)
12. Comment-RMessage(62)
13. RecordQuery-R(65)
14. SetRecord-R(64)
15. Record-R(63)

11: Live Entity

1. Information Operations Action (70)
2. Information Operations Report (71)

12: Non-Real Time

1. Time Space Position Information (TSPI) (46)
2. Appearance (47)
3. Articulated Parts (48)
4. LE Fire (49)
5. LE Detonation (50)

129: Experimental - Computer Generated Forces

Entity Information Family

The Entity Information Family is a group of PDUs that are related to that of the position and other information about entities. They describe the location of entities, and sometimes their collision. An image of the PDUs in the family is below.

In addition PDUs are defined up into "families." There are PDUs grouped into moving entities, colliding, doing logistics, and more. There are a dozen families that the PDUs are divided into.

Alt text

Entity State PDU

The entity state PDU is one of the most widely used PDUs in DIS. It includes the unique ID of the entity described, numeric values that describe the type of entity, and its position, orientation, velocity, acceleration, and the dead reckoning algorithm that should be used between the receipt of other position PDUs.

Describing what the Entity State PDU (ESPDU) does can be complicated or simple. Some of the capabilities are described in greater detail elsewhere in this document.

The Java language class documentation for the ESPDU class is available here.

PDU header

Every ESPDU starts with the PDU header, just as does every other PDU.

Enity ID

Every entity handled by DIS--every vehicle, every person whose position is described, every ship, every aircraft--must have an ID to uniquely identify it. This is what the entity ID is. It is described later, butiIt consists of a triplet of three numeric values: {Site, Application, Entity}. The triplet, together, must be unique. Arriving ESPDUs decode the entity ID and use it to update the position and orientation of the entity it is tracking.

Entity ID is discussed in greater depth in Section IV: Entity Identifiers

Force ID

There can be more than one (or two!) force affiliations on the battlefield. The force ID field lets you specify this. The values set are defined in the Enumerated and Bit Encoded Values (EBV) document published by SISO. This document contains many predefined values. This is the case for force ID fields, as shown below:

Force Integer Field Value Other 0 Friendly 1 Opposing 2 Neutral 3 Number of Variable Parameters

The ESPDU can also contain some extra parameters with Tartary, programmer-defined data. This field identifies the number of the parameters (which are of a predefined size) at the end of the PDU. This is described in greater detail later in the document.

Entity type

One question is how the receiver should draw the entity. How does the simulation know what it looks like? The type of the entity being described is included in the entity type field of the ESPDU. The receiving simulation can identify the entity type and, if it has a model for the entity, use that model to draw on the screen.

Field Name Value Entity Kind The kind of entity described by the Entity Type record Domain The domain in which the entity operates (e.g., subsurface, surface, and land) except for munition entities Country Nation to which the entity belongs Category Unique ID Subcategory Unique ID Specific Unique ID Extra Unique ID The EBV document includes SISO defined collections of entity types. For example, the UK Challenger Main Battle tank has these values:

Field Name Value Entity Kind 1 Domain 1 (land) Country 223 (UK) Category 1 Subcategory 2 Specific 2 (Mk 2) Extra Unused This information was defined in the EBV SISO document, and is an agreed-upon, compact, and exact vocabulary for defining entity types.

Alternate Entity Type

This is exactly like an Entity Type field. However, some simulation applications also want to allow simulations to use deceptive appearances to other simulations. If an aircraft issues deceptive electronic signatures to make a fighter aircraft appear to be a civilian airliner, that is possible. The alternate entity type field holds a description of what airliner that entity is, and other simulations may present an airliner in the 3D display, rather than an F-16.

Entity Linear Velocity

How fast the entity is moving. Three coordinate values (x, y, and z) are used. This is quite valuable for making the entity appear to travel in a smooth manner by using dead reckoning to move the entity between receptions of individual ESPDUs, which might appear only seconds apart. We don't want the movement to appear to be jerky or hyperspace-jump like.

The coordinate system used in the field varies. It could be global, with a coordinate system that has its origin at the center of the earth, or it may use a more local coordinate system. The type of coordinate system used in the field is set in the dead reckoning field below.

Entity Location

The entity location is interesting. It uses a three-value record, X, Y, and Z, that measures the distance from the center of earth. These values can be converted to latitude, longitude, and altitude with some mathematical work, or to MGRS coordinates, or to a local coordinate system placed with its origin at a known location. It is described further in a later section.

Entity Location is discussed in more detail at Entity Location

Entity orientation

This determines which way the entity is pointing. It's a little mysterious; what defines the "front" or "up" of an entity? Still, it can often be defined. As with the location, this is described elsewhere, but is done with what are called "Euler angles."

Entity appearances

Some entities may be burning, or smoking, and this alters how receiving simulations should draw the entity. There are several appearance settings, and this is accomplished in the ESPDU by using a 32-bit integer. Sub-regions of the integer are used to describe the appearance.

Dead Reckoning Parameters

This represents how the sending simulation believes dead reckoning should be done. For example, should it include the entity's acceleration, or not. The angular acceleration, or not? The object's linear acceleration, or not?

This is another subject discussed elsewhere. (Sigh.)

Entity Marking

This is a useful debugging measure. The marking is effectively 11 string characters. This lets presenting applications use the string to have a small description drawn along with the 3D model. Viewers can view something like "Open-DISApp" or "FooApp".

Capabilities

A 32-bit integer. Sub-ranges of the integer describe what the entity is capable of.

Variable Parameters

The ESPDU can contain a list of variable parameters. Each of the parameters is 128 bits, total, long. This can be used to contain such information as the direction in which the rotating turret of a tank is pointing, and what the elevation of the gun is. This depends on the sending and receiving simulations having an agreement on what the variable parameters mean, and what the endian format of the data is in.

Collision PDU

Collision-Elastic PDU

Entity State Update PDU

Attribute PDU

Warfare Protocol Family

Firing PDU

Detonation PDUD

Directed Energy PDU

Entity Damage Status PDU