Book of Disorder

This example can be found in the source tree and is compiled with the library. The executable is hiding in <build>/examples/hello_world within a compiled disorder source tree.

The PDU sent by this stupid example can be captured using the awesome and infinitely useful wireshark tool. The specifics of how to do that are outside the scope of this document, but such an experiment may yield something similar to the following:

As clearly shown, the Comment PDU was sent and it contains the obligatory text with the specified datum identifier. Perhaps more interestingly, Disorder filled out many of the PDU fields automatically and assumed a few things along the way that may not be correct.

Also of note here is that Disorder automatically padded the PDU’s variable datum field to achieve the 64-bit alignment required by the DIS standard. The actual value is 12 bytes (96 bits), but the field was padded to occupy 16 bytes (128 bits) to satisfy the standard.

One can also see that IPv6 was used for the transmission. This is a result of localhost resolving to an IPv6 address and an IPv4 address on the test machine. While IPv6 addresses are preferred by default when something ambiguous is specified, Disorder happily accepts IPv4 addresses and can be made to prefer IPv4 over IPv6 via disorder::network::udp::Options::ip_version in ambiguous situations if desired.

Here is some example content from a Disorder log file:

Each message is composed of various parts from left to right:

In order to transmit and receive PDUs, one or more PDU transports have to be registered with disorder::Exercise. One or more of the transports that come with disorder can be employed and/or user defined transports can be used. PDUs are sent and received using all registered transports unless the transports themselves employ some kind of filtering.

There is no default PDU transport. If at least one PDU transport is not registered with disorder::Exercise no PDUs will be transmitted or received. A log message will be generated in this case, but it isn’t treated as a fatal error so disorder::Exercise::initialize will not fail as a result of not registering a PDU transport.

It’s usually a one-liner to register a PDU transport. Here’s the simplest possible example:

Here’s a slightly more complex example showing how to make an IPv4 UDP multicast transport on port 3000 with multicast loopback disabled using the local interface on the 192.168.1 subnetwork:

All received PDUs are routed from PDU transports to the PDU disseminator. The disseminator is responsible for distributing received PDUs to the rest of the simulation application. As described in the Receiving PDUs section, a simulation application registers receivers for PDUs it is interested in with the disseminator and the disseminator then invokes appropriate registered receivers when a PDU is received.

Like PDU transports, the PDU disseminator supports passive and active processing models. By default, the PDU disseminator is active causing it to spawn its own dedicated thread which invokes registered PDU receivers. That makes all simulation applications that use Disorder multi-threaded by default. While that is generally useful, some closed minded people may consider this an abomination so disorder allows the disseminator to easily be switched to a passive processing model where it only invokes registered PDU receivers when disorder::Exercise::update is called using the thread that calls disorder::Exercise::update. Here’s how to do that:

Sending a PDU is a matter of instantiating an object of the desired disorder::pdu::PDU derived class, populating its fields with data, and then calling send on it.

The network transports shipped with disorder allow different PDU instances to be sent concurrently from multiple threads.

Here’s an example:

An internal entity is managed by the simulation application. The simulation application is responsible for maintaining its state.

An external entity is managed by another simulation application. External entities may be managed by a different application on the same computer or they may be managed by an application on another computer on a local or wide area network.

Each DIS entity has a 32-bit field that contains a set of appearance attributes that depends on the type of the entity. See UIDs 31-43 in the SISO-REF-010 for more details. Working with this 32-bit field directly is cumbersome and error prone, so Disorder provides a more convenient mechanism for examining and manipulating these appearance attributes in addition to allowing simulation applications to interact with the bits directly if so desired.

Generally, external entities should be treated as const Entity objects from the perspective of simulation applications because they are read-only. Internal entities are non-const as the simulation application manages the state of those entities and will call mutator methods on the Entity objects to update that state.

The convenient appearance mechanism is available via the appearance() method of Entity. There are two different overloads of this method, a const version and a non-const version. The const version provides read-only access to the appearance attributes whereas the non-const version provides read/write access. The appearance() method returns an Appearance object. That object provides access to entity kind, and domain in the case of platforms, specific appearance interfaces. See the appearance.hpp header in the source tree for more details.

Disorder provides two different mechanisms for entity event notification, an entity specific mechanism and a general mechanism.

The entity specific event mechanism is useful for efficiently handling changes to a specific entity. Entity specific events are available for both internal and external entities.

Only one change handler can be registered with an Entity. Even though a change handler can be configured to react to multiple types of changes, the change handler is only invoked once per Entity State/Entity State Update PDU after all the pending changes to the Entity have been applied.

A concrete example will probably help illustrate the practical usefulness of this mechanism. Consider a simulation object that represents a DIS entity that needs to react to appearance changes:

The general mechanism is perhaps most useful for reacting to entities joining and leaving the simulation, but it can also be used for handling changes to existing entities.

Applications can subscribe for events from internal and external entities within Disorder. External entity events are probably more useful than internal because the simulation is less likely to anticipate changes to the entities it does not manage.

disorder::entity::Manager is passive. It only manipulates internal and external entities during the exercise update process that happens when disorder::Exercise::instance().update() is called. When exactly is a good time to manipulate simulation entities depends on whether or not your simulation application is multi-threaded with respect to the parts that interact with disorder.

Disorder can transfer entity ownership between simulation applications in accordance with section 5.9.4 and Annex H of the 1278.1-2012 DIS standard. Entity ownership transfer is an asynchronous process with several coordinated steps between the divesting and acquiring simulation applications. A simulation application initiates an entity transfer by calling disorder::entity::Manager::instance().transfer_ownership(…​). This method is used to push an entity to or pull an entity from another simulation application. It does the right thing depending on the current ownership status of the entity being transferred. When entity ownership is transferred, existing disorder::entity::Entity instances remain valid, the ownership attribute just changes accordingly. Ownership status changes are considered modifications like other changes to an entity and event handlers can be attached to ownership changes as desired.

Disorder will ignore incoming transfer ownership requests by default because they allow other simulation applications to steal internal entities and thrust other entities a simulation application may not want to deal with upon it. To process incoming transfer ownership requests, call disorder::Exercise::instance().configuration().process_transfer_ownership_requests(true) prior to initializing the disorder exercise.

The designator::Manager doesn’t manage or create unique internal designator identifiers automatically. A unique designator identifier has to be supplied to the designator::Manager::new_internal_designator function. A desigantor::Id consists of an entity identifier and a designator system name.

The entity is the unique identifier of the designating entity and the system uniquely identifies the type of designating system within the entity.

Designator PDUs seem to contain state that implies designators can be dead reckoned using an algorithm and a linear acceleration. At present, Disorder is too dumb to use this information to actually dead reckon designators as that modicum of information does not seem sufficient to adequately perform reasonable dead reckoning. Disorder will only dead reckon designators that are on or offset from an entity using the dead reckoning information in the entity and the entity referenced spot information in the Designator PDU.

If you know how the designator spots are supposed to be dead reckoned using the information in the Designator PDU, please submit a patch or e-mail information to disorder@squallline.com so the library can be improved.

The transmitter::Manager doesn’t manage or create unique internal transmitter identifiers automatically. A unique transmitter identifier has to be supplied to the transmitter::Manager::new_internal_transmitter function by the simulation application. A transmitter::Id consists of a reference_id and a number.

The reference_id is generally the unique identifier of the entity the transmitter is attached to. For intercoms and other special cases, the 1278.1-2012 says an "Unattached Identifier Record" shall be used instead of an entity identifier. An "Unattached Identifier Record" cannot be practically distinguished from a proper entity identifier, so Disorder recommends using a legitimate entity identifier even for an intercom.

The number field uniquely identifies the transmitter within an entity. This is just a 1 based index. If an entity has multiple transmitters, the first one should be assigned a number 1, the second gets 2, and so on.

Disorder models transponders and interrogators with disorder::iff::Transponder and disorder::iff::Interrogator objects respectively. Similar to entities, these come in internal and external flavors depending on whether or not the local simulation application owns them.

New internal transponders and interrogators and created via the disorder::iff::Manager by calling the new_internal_transponder or new_internal_interrogator functions. Disorder does not manage or create unique IFF system identifiers. When creating a new internal IFF system, a simulation application must supply a unique identifier for the new system. Unique IFF system identifiers consist of an entity_id, type, name, and a designator. Please reference the Disorder API Manual or disorder::iff::Id class documentation for guidance on how to specify a unique IFF system identifier.

Disorder supports both regeneration and interactive IFF simulation modes. By default, all internal IFF systems are capable of supporting interactive mode. Simulation applications can elect to disable interactive mode support on a per IFF system basis via the disorder::iff::System::interactive_mode_enabled method. When interactive mode is disabled on a transponder, any received interactive interrogations for that transponder are completely ignored.

Simulation applications have a unique set of identifiers that entities and synthetic environment objects share. An entity and an object cannot have the same unique identifier. When the library selects identifiers for new internal entities and objects, it prevents multiple things from having the same identifier. The library will also try to prevent simulation applications that choose their own identifiers for objects and entities from overlapping entity and object unique identifiers.

The draft 1278.1 standard version 8 removes synthetic environment objects. They have been combined with entities, so the object management facility of Disorder should be considered deprecated.

disorder::time::SimulationClock is a wall clock in the simulated environment. Simulation time adheres to the following rules:

The simulation time is available via disorder::time::SimulationClock::instance().now(). The simulation time quantity is a std::chrono::time_point with nanosecond precision which can be interacted with just like standard std::chrono clock times.

disorder::time::ReferenceClock provides the time for PDU timestamps and is the basis for simulation time. By default, the reference clock is equivalent to a real-world wall clock.

The reference clock is probably not very useful to simulation applications. If you really want to know what time the reference clock thinks it is at any given instant, call disorder::time::ReferenceClock::instance().now().

The disorder::geospatial::Location class models an absolute point in space somewhere on or above the surface of the Earth. A location exists in all three coordinate systems. One can use the Location in any of the coordinate systems and it will lazily and non-redundantly convert between them. For example, it’s perfectly fine to assign the value in one coordinate system and then ask for the value in a different coordinate system.

To get the dead reckoned position at the current simulation time from an Entity:

Here are a few examples showing how to set the location of an Entity:

The disorder::geospatial::Orientation class models the attitude of an object. An orientation exists in all three coordinate systems. One can use the Orientation in any of the coordinate systems and it will lazily and non-redundantly convert between them. For example, it’s perfectly fine to assign the value in one coordinate system and then ask for the value in a different coordinate system.

All angles in disorder are measured in radians. Convenience functions to convert between degrees and radians are provided in disorder/linear_algebra/angle_conversion.hpp.

Orientations coexist in four different notations: Tait-Bryan ZYX intrinsic convention Euler angles, yaw/pitch/roll, quaternion, and matrix.

Disorder is built on top of the powerful Eigen linear algebra library, so there are many convenient ways to compute all sorts of geospatial and orientation values of interest. Getting the right answer will often require some math and 3D reasoning skills. The library provides you with the tools, but leaves a lot up to the simulation application author. This affords great flexibility at the cost of some complexity.

Let’s look at a few examples. These are in no way exhaustive. They are just intended to give you an idea of what power is at your fingertips.

If your simulation application has a moving map or otherwise renders a 2D projection, the flattened coordinate system might be able to help. It can be configured as a local tangent space, Lambert conformal conic, transverse mercator, or universal transverse mercator projection. It must be configured prior to initializing the disorder exercise and cannot be changed thereafter.

Here’s an example of how to configure it as a local tangent space with origin at the intersection of the Equator and the Prime Meridian:

Once the flattened configuration is in place, the flattened reference frame can be accessed via the standard Location and Orientation objects.

Disorder comes with two different geospatial conversion backends. By default, the library prefers GeographicLib, but it also contains built-in support for SEDRIS SRM. Both backends provide the full feature set for geospatial conversions. Which one to choose comes down to simulation application author preference. It’s also possible to extend disorder to use a different conversion backend. See Geospatial Convertors for more details on that.

If you want to use the SEDRIS SRM, there’s a little more work to do. Because the SEDRIS SRM creators don’t give away their source code without forcing people to have an account in their system and agree to their license, Disorder is not distributed with the SEDRIS SRM and cannot automatically download it for you. The following additional steps are required to use the SEDRIS SRM:

The disorder::network::Transport base class constructor requires a processing model to be specified. While one can opt to cheerfully ignore this parameter and specify something that isn’t exactly true and then do whatever the hell one wants, it is generally suggested that one implement both processing models and then see which works best for a particular situation. In the PASSIVE processing model, the transport only transports when the update method is called by disorder’s main processing loop. When using the ACTIVE model, the transport transports whenever there is something to do via a dedicated thread.

Two custom transport examples are included in the source distribution in addition to disorder’s provided transports. These are simply for demonstration purposes as they may be completely illogical to use in practice.

Converting between the user PDU model (disorder::pdu::PDU derived classes) and whatever transmission protocol dependent PDU representation is required for PDU transmission and reception is the job of PDU transforms in disorder. PDU transforms implement a visitor pattern on PDU fields. Deflators serialize user model PDUs into another format while inflators go the other direction. Both transforms derive from the disorder::pdu::field::Visitor base class.

Disorder provides the disorder::pdu::transform::IPPacketEncoder to transform a user model PDU into the transmission representation specified in the IEEE-1278.1 standard. The disorder::pdu::transform::IPPacketDecoder performs the opposite transformation.

When a PDU is received, it should be inflated into the appropriate disorder::pdu::PDU instance. PDU transforms and the disorder::pdu::Factory are useful for those purposes respectively. Once the user model PDU instance is obtained, it is generally forwarded to the disseminator registered with the transport. Said disseminator is kept in the disseminator_ protected member of the Transport base class. Generally, this disseminator is an instance of the built-in disorder::pdu::dissemination::Disseminator. It requires the dynamically allocated PDU to be wrapped in a std::shared_ptr and forked over to the disseminate method. That’s all there is to it. For other parts of your simulation application to handle the received PDUs, register interest in them as described in the Receiving PDUs section.

Custom implementations of disorder::pdu::dissemination::DisseminationInterface can be used to avoid the built-in dissemination mechanism for a specific PDU transport.

Sending PDUs with custom variable records is not likely to induce headaches or carpal tunnel syndrome.

Are you sick of examples yet? No? Good. Here’s an example.

Why the hell did you waste your damn time making such a stupid thing? I already use <insert your favorite packet capture playback utility here> for that!

The main reason is that rewriting DIS timestamps is necessary to replay a packet capture with absolute DIS timestamps.

Run the tool with no arguments and it will tell you how to use it. Here is a sample of that output:

The only required argument is a capture file to play back. It will use the destination endpoint from the captured packets and relative DIS timestamp mode by default. If that’s not what you want, pass it more options.

Display rewrites DIS timestamps when the captured PDU’s timestamp mode is absolute or display is made to produce absolute timestamps. DIS timestamps on replayed PDUs are unmolested when the captured PDU’s timestamp mode is relative and display is producing relative timestamps.

Global namespace pollution is a giant problem with the horrendously offensive windows APIs. Several symbols used in disorder are haphazardly #defined in the windows API. To counter this, disorder will #undef the offending symbols. However, this might piss off your software if it relies on that stupidity, so disorder will re-pollute the global namespace if you #define DISORDER_PLEASE_RESTORE_GLOBAL_NAMESPACE_POLLUTION before including disorder stuff. Doing such a thing is probably not a good solution because it will make your life difficult if you use the trampled symbols from the disorder library in your code. To resolve any such issues, you can use disorder/utility/global_namespace_pollution_countermeasures.hpp similarly to how it is done in the library itself. Something like this might help:

Good luck. This problem sucks. Send all fan mail and thanks to Microsoft for this situation.