5.2 - DIS Networking Using the SDK

Table of Contents

• 5.2.1 Controlling the Update Rate for DIS
• 5.2.2 How DI-Guy Custom PDUs are Defined
• 5.2.3 DI-Guy Entity Mapping in the Absence of Custom PDUs

DI-Guy broadcasts and responds to standard DIS entity state PDUs.

It can also broadcast and respond to DI-Guy Custom DIS PDUs. DI-Guy also broadcasts and responds to standard DIS fire and detonation PDUs. Examine the programming example diguy_networking/DIS, detailed below:

1. Before the DI-Guy scenario object is constructed, call:

   diguy_module_net_initialize();

   and retrieve the net interface:

   diguyNetInterface * diguy_net_module = get_net_interface();

2. To join the exercise once the DI-Guy scenario object is constructed, call:

   diguy_net_module->go_online()

3. Once per frame or tick of the simulation clock during your simulation, call:

   diguy_net_module->update()

4. When you want to leave the DIS exercise, call:

   diguy_net_module->offline()

5. At least once after calling diguy_net_module->go_offline() and before calling diguy_module_net_deinitialize(), call:

   diguy_net_module->update() 

   This allows the offline command to be processed, so that objects to be destroyed in Step 6 are unused.

6. After the DI-Guy scenario object has been destroyed, call:

   diguy_module_net_deinitialize()

Please see diguy_module_dis.h for more information about these functions, as well as a listing of other DIS-related functions offered by DI-Guy.

    \note The diguyNetInterface class acts as a wrapper around either a DIS or an HLA network interface. The type of interface that is created depends on which library is linked against.

The ./programming_examples/diguy_networking/DIS/net_send example demonstrates broadcasting DIS. The ./programming_examples/diguy_networking/DIS/net_recv example demonstrates receiving DIS.

5.2.1 Controlling the Update Rate for DIS

DI-Guy periodically broadcasts DIS entity state PDUs for each character. It broadcasts PDUs when the dead-reckoned error in position of an entity exceeds one of the following:

• The translation_threshold (default 0.05m).
• The rotation_threshold (default 0.2 radians).

PDUs are also sent if the timeout threshold is reached (default 5 seconds). The timeout rate can be altered by calling diguyNetInterface::set_timeout_interval().

These threshold parameters are specified in the configuration file ./custom/config/diguy/scenario/network.cfg.

5.2.2 How DI-Guy Custom PDUs are Defined

The IEEE standard 1278.1 defines DIS PDUs. The first record of a PDU is the PDU Header Record, defined as follows:

typedef struct PDUHeader_s {
U8                      m_version ; // 4 for DIS 2.0.4, 
U8                      m_exerciseID ;
U8                      m_PDU_kind ;
U8                      m_family ;/* unused in DIS Version 3 */
U32                     m_time ;
U16                     m_length ;
U16                     m_unused ;
} PduHeader_t; 

Setting the m_pdu_kind variable to a value between 220 and 255 designates a custom PDU. You can change the m_pdu_kind by editing the cust_pdu_kind = 220 line in network.cfg. The default value is 220. All your DI-Guy custom PDUs should use a single common number. m_version should be:

• 4 – For DIS 2.0.4.
• 5 – For IEEE 1278.1.
• 6 – For DIS 2.1.4 or IEEE 1278.1a.

The overall DI-Guy Custom PDU is defined by the structure:

struct diguyCustomPdu {
        PDUHeader_t                                             m_header;                                                                               /* Header, defined above */
        U16                                                     m_bdimessageversion;                                                                            /* Depends on MessageID */
        U16                                                     m_bdimessageid ;                                                                                /* Message ID */
        EntityID_t                                              m_entityID ;                                                                            /* Entity ID defined below */
        U8                                                      m_datasize ;                                                                            /* Size of m_data */
        U8                                                      m_data[] ;                                                                              /* Message data */

where:

• m_pdu_header. The PDU record header described previously.
• m_bdimessageversion. Depends on the message ID. Is used to make messages backwards compatible. Currently m_bdimessageversion is 7 for all message IDs except SETCHARACTION, which must be 8. If you ever receive a DI-Guy PDU with an unsupported message version, ignore the message.

• m_bdimessageid. A zero-based enumeration, with the following mnemonics defined:

  enum {
          DIGUY_CUSTOM_PDU_ID_ESCAPE_RESERVED = 0,                                
          DIGUY_CUSTOM_PDU_ID_SET_CHAR_TYPE,                                                      
          DIGUY_CUSTOM_PDU_ID_SET_CHAR_APPEARANCE,                                        
          DIGUY_CUSTOM_PDU_ID_SET_CHAR_ACTION,                                            
          DIGUY_CUSTOM_PDU_ID_SET_CHAR_VISIBLE,
  .
  .
  };

      \note A second set of message IDs, the DI-Guy Scenario Control PDUs, are discussed in \ref diguysdkControllingDIGuyScenarioRemotelyUsingCustomPDUs. The message IDs listed here are for Live Reckoning.
  

• m_entityID. Identifies the site, host, and entity, with three 16-bit values.
• m_datasize. Describes how many bytes are in m_data. If m_data is longer than 255 bytes, this value is zero.
• m_data. Void data whose format depends on the value of m_bdimessageid and m_bdimessageformat. m_data can be any combination of short integers, long integers, 32-bit floating point values, and null-terminated strings. For instance, if the format is long, short, string, string, then the first 4 bytes are a long integer, the next 2 bytes are a short integer, followed by a null-terminated string, and then another null-terminated string.

The most important messages are for the type, appearance, and action. For a complete list, see the diguyCustomPDUType enumeration in diguy_dis_constants.h.

For further information and type definitions, consult IEEE 1278.1.

    \note In DIS PDUs, the network representation of multi-byte integers is big-endian. Therefore, on Intel architectures, multi-byte integers sent to and received from the network must have their byte order reversed.

5.2.3 DI-Guy Entity Mapping in the Absence of Custom PDUs

DI-Guy using custom DIS PDUs supports the full range of characters available in DI-Guy by specifying the character type and appearance within the PDU. In the absence of custom PDUs, a mapping configuration file specifies:

• The character type and appearance DI-Guy uses to display entities being received.
• The DIS entity type and parameters to broadcast for locally simulated characters.

If neither custom PDUs nor an entity map specify the character and appearance, DI-Guy displays and sends the entity as either:

• An American soldier (lifeform).
• An American M1A1 Abrams tank (vehicle).

Specify the desired mappings in ./custom/config/diguy/scenario/network_model_map.cfg. The default configuration file is ./config/diguy/scenario/network_model_map.cfg.

DI-Guy offers a network model map application as part of DI-Guy Scenario that has an easy-to-use GUI to update this file.

Model Map Application

Each entry line in network_model_map.cfg corresponds to a DIS Entity Type Record of a DIS Entity State PDU.

• A DIS Entity Type Record contains 7 fields that describe the type of entity to which the PDU refers.
• The order of lines in the mapping file is not important.

In the mapping file:

• -1 is a wildcard meaning any number.
• Asterisk (*) is a wildcard meaning any string.
• Wildcards cannot precede non-wildcards in any line of the mapping file.
• All lines are considered during mapping, and the most specific match (the one with the fewest wildcards) is used.
• A line with all wildcards to the left of the second equals sign denotes a default mapping, used when no more specific mapping exists.
• If there is no match in the table, DI-Guy uses an American solder for lifeforms and an American M1A1 Abrams tank for platforms.
• Comments on the end of each line are ignored.
• The two word pairs (for example, "vehicle2 helicopter1" or "soldier2 default") refer to the DI-Guy character and appearance.

The following are some example entries in network_model_map.cfg:

entry = 1 1 225 2  1  3  0  = vehicle_turret m2a3_bradley_des_turret
entry = 1 1 225 2  1  3  1  = vehicle_turret m2a3_bradley_grn_turret
entry = 1 1 225 2  1  3  2  = vehicle_turret m2a3_bradley_des_turret
entry = 1 1 225 2  1  3  3  = vehicle_turret m1a2_abrams_des_turret
entry = 1 1 225 2  1  3  4  = vehicle_turret m1a2_abrams_grn_turret
entry = 1 1 225 2  1  3  5  = vehicle_turret t72_tank_des_turret 
entry = 1 1 225 2  1  3  6  = vehicle_turret t72_tank_grn_turret 
entry = 1 1 225 2  1  1  1  = vehicle_technical gaz_truck_w_ZSU23_turret
entry = 1 1 225 2  1  1  2  = vehicle_technical humvee_50cal_des_turret
entry = 1 1 225 2  1  1  3  = vehicle_technical humvee_50cal_grn_turret

[<< Networking with DI-Guy] [Home] [Top of Page] [HLA Networking >>]