DACS App Note

DACS Entity Attachment Over HLA (#52)

Purpose

The purpose of this Application Note is to describe how to use an HLA interaction to successfully attach an entity on the HLA network to a radio on the DACS. This Application Note assumes familiarity with HLA terminology such as federation, federate, object instance, and interaction; and the functional interface between the federates and the runtime infrastructure (RTI).

Background

The world position field of a radio object on the DACS may be updated by one of two sources. Firstly, the radio may receive world position data directly from a host computer. Secondly, the radio may receive its position indirectly from a separate entity. In this case, the DACS inserts position data from the entity into the world position field of the radio object. This allows the radio object functions to be simulated on the DACS while the position is simulated elsewhere on the network.

Entity attach in the HLA environment refers to the process of pointing the world position field of a radio object to another entity on the HLA network, such as an aircraft platform. This is accomplished through an HLA interaction sent to the Telestra units from the simulation host. After a successful attachment, the DACS will apply propagation effects to the radio as if it were collocated with the HLA entity.

This Application Note describes how to configure the radio on the DACS and the corresponding HLA settings so that the entity attachment will work properly and how to send the entity attach interaction. It also presents a few troubleshooting steps to follow if the attach is unsuccessful.

Model Setup

Correct configuration of the radio requires three objects: a world position object, an entity object, and a radio object. The world position object holds the default position data for the radio in geocentric (x,y,z) or geodetic (lat, lon, alt) coordinates. If this value is not specified, the radio will not transmit or receive if it stops receiving position data from the HLA network. World position objects are accessed from the "Controls List". To create a geocentric object, press F2 and select Insert->World Position->Geocentric. Set the x, y, and z position variables to the appropriate values (use [0,0,0] for the center of the earth), press Enter, then press Esc to return to the Controls List.

The entity object feeds world position data to the radio object. Entity objects are accessed from the Controls List. To create an entity object, press F2 and select Insert->World Position->Entity from the Controls List submenu. The Identifier field specifies the name of the entity and should be set to a unique value. Move the cursor to the Entity ID field and press "+" until the displayed value is "HLA". The Site No and Host No fields now display preassigned values that the user cannot change. The Entity No field may be set to any value as long as the Radio ID and Entity ID form a unique combination. The Default Posn field should point to the world positon object. To insert the world position object, move the cursor to the Default Posn field and press Enter. The Controls List appears. Select the world position object from the list and press Tab to insert this object into the default position field in the entity object.

Radios are accessed from the "Signals List". To create a radio object, press F2 and select Insert->Receivers->Radio from the Signals List submenu. The World Position field of the radio holds the position data that the DACS uses to calculate line-of-sight and propagation effects. This field should point to the newly created entity object. To enter the entity object, move the cursor to the World Position field and press Enter. The Controls List appears. Select the entity object from the list and press Tab to insert this object into the World Position field in the radio object. The RadioID-HLA field may be set to any value as long as the Radio ID and Entity ID form a unique combination. The radio is now configured to use entity attachment.

For more information regarding the radio and world position objects, please refer to the Model Builder Reference Manual.

Naming Conventions

The Telestra system publishes Transmitter and Receiver objects on the HLA network based on the Radio objects created in Model Builder. The names for these objects are derived from the Identifier and World Position fields in the Radio object in Model Builder. For instance, if a Radio in Model Builder has the Identifier 'UHF' and a World Position 'Viper1,' then Telestra will create a Transmitter named 'Viper1.UHF.tx' and a Receiver named 'Viper1.UHF.rx' on the HLA network.

In order to track a Transmitter or Receiver object as it moves from Entity to Entity, each Transmitter and Receiver object contains an attribute called 'HostObjectIdentifier.' Telestra will update this attribute when a Radio moves from one Entity to another. Note that the 'HostObjectIdentifier' attribute is only populated when you are doing dynamic entity attachment. During Static attachment the field will remain null. See Entity Attach Process below for details.

HLA Settings

Telestra configures its HLA settings automatically. For each radio object created in Model Builder, Telestra creates a receiver object instance and a transmitter object instance in HLA. Telestra also subscribes to the BaseEntity object class upon startup. This allows Telestra to be informed whenever a new entity object on the HLA network has been created.

The user must ensure that the external entity object instance has been registered in HLA. Name is one of the attributes specified when an object instance is registered. The object instance name can be any string value but must be unique across the federation. Once the entity object has been registered in HLA, Telestra will discover it and be able to receive any updates to entity attribute values such as position data.

Entity Attach Process

Static Attachment

By using an Entity Attach object in Model Builder for the World Position field of a Radio, Telestra will automatically look for an Entity on the HLA network with the same name as the Entity Attach object in Model Builder. If found, Telestra begins pulling world position information from the HLA network.

Dynamic Attachment

The command to attach an entity to a radio is sent as an HLA interaction from an initialization script during startup or from an HLA host interface during a simulation run. The attach interaction class, EntityAttach, is defined in the ASTi Simulation Object Model (SOM). EntityAttach uses the names of the radio entity and external entity as parameters.

The following pre-conditions must be true before EntityAttach can be sent:

  • Telestra federate has joined the same federation as the simulation host
  • Radio object has been created in Model Builder
  • Entity object has been created in Model Builder
  • Entity object has been inserted into world position field of radio object in Model Builder
  • External entity object instance has been registered and discovered in HLA environment

NOTE: The Entity Attach object from Model Builder does not need to exist in the HLA environment.

The format of the attach interaction is:

EntityAttach(RadioEntityName, ExternalEntityName)

... where RadioEntityName is the identifier of the HLA radio object (e.g. Viper1.UHF.tx or Viper1.UHF.rx) and ExternalEntityName is the name of the HLA entity object to which the radio will attach. The name of an HLA entity object is the name that was assigned when the entity object instance was registered in HLA. Because HLA is case sensitive, the names passed as interaction parameters must match the assigned names exactly. Once the radio and entity are attached, the radio will receive new position data as the position of the entity changes. The 'HostObjectIdentifier' field will also get updated with the ExternalEntityName defined in the EntityAttach Interaction.

When implementing entity attach through HLA, it is important to remember the following points:

  • If multiple radios are attached to the same entity, these radios will reflect the same position data. In other words, they will behave as if they are moving together as a unit. For example three radios in the same aircraft could be attached to the same entity, so that they would receive the same position data.
  • Sending an EntityAttach interaction for a radio that is already attached to an external entity will first detach the radio from its current entity, then attach it to the new entity. An example of this case would be if a Telestra unit receives two interactions that attach a radio to two different external entities. In this case, the last interaction received will detach the radio from the first entity, then attach the radio to the second entity. Received audio quality may be affected as the position data source switches from one entity to the next.
  • A radio may be implicitly detached from an external entity by sending an attach interaction with an empty string as the ExternalEntityName parameter.
  • If the external entity to which the radio is attached disappears from the network, the radio will revert to the default position specified in Model Builder.
  • All position data in the external entity should be specified as geocentric coordinates with the x,y, and z values as 64-bit floating point numbers.
  • If one of the parameters is misspelled in the EntityAttach interaction or if the external entity does not exist in HLA, the EntityAttach command will be ignored.
  • Troubleshooting

    For dynamic entity attach the user can confirm that the entity attachment was successful by viewing the attributes of the receiver and transmitter object instances in HLA. The "HostObjectIdentifier" attribute contains the HLA name of the entity object to which the radio is attached. If this field is empty, the radio object is not attached to an entity. Note that for static attachment this field will be null. The "WorldLocation" attribute of the RadioTransmitter class should reflect the position of the HLA entity. This is true for both static and dynamic entity attach.

    Problem How to Check Solution
    The external entity does not exist in HLA At the Telestra console, type "OBJECT Entity". This returns a list of all entity objects that the Telestra federate has discovered. Check that the name of the external object is listed. Have an object instance for the external entity registered in HLA as described in HLA Settings above
    Position data of entity object in DACS does not change In Model Builder, go to the Controls List, select the world position entity and press Enter. Check that the Geocentric Position field shows changing X,Y,Z values. Check that the external entity exists in HLA. Follow steps in Problem #1 above. Resend EntityAttach interaction if necessary.