DACS App Note
Using the Terrain Database Interface in Model Builder (#16)
Model Builder provides a high fidelity radio simulation. High level parameters such as radio position, modulation type, radio frequency, etc., are used by the Model Builder software to calculate signal loss due to ranging and over the horizon effects based on a smooth, ellipsoidal earth (WGS84) model.
Sometimes, other propagation effects due to local terrain are important in an exercise. Individual terrain databases may vary, and the level of sophistication required may also vary (line of sight terrain occulting may be enough, but diffraction effects may also need to be taken into account.) In order to handle this, Model Builder provides a "hook" to allow the host computer to specify propagation loss for any transmission.
The Terrain Interface feature is an inexpensive, separately purchased software option. If your DACS has the Terrain Interface Package its presence will be displayed on the Model Builder Options page located under the Models menu in the Model Builder software environment.
The general operation of the Terrain Interface is as follows:
- Model builder determines which radios are in range and in tune for the smooth earth model. (Normally, for occulting by the earth, model builder includes the effects of the first fresnel diffraction zone. With the Terrain Interface option, this is turned off, and only geometric line of sight is used.)
- Model Builder generates a set of PDUs (Protocol Data Units) pertaining to each transmitter/receiver pair that is in range and in tune. This includes navigational beacons as well as communications radios.
- PDUs are bundled into an ethernet packet and transmitted to the host computer via the DACS Host Interface.
- The host fills in the path loss information and retransmits the PDUs back to the DACS.
- Model Builder incorporates the path loss factor for each path in its calculations to achieve the appropriate terrain occulting and propagation effects.
Path Loss Request PDU Generation
Requests for path loss information are generated in the form of a DIS style PDU. This path loss request PDU is sent to the host computer under the following conditions:
When a transmitter or receiver has moved more than the DIS position limit the DACS will issue a request for path loss information pertaining to the affected transmitter or receiver.
Default position limit is 500m but can be set to other values via a command line in the Model Builder start up configuration file (see configuration commands at the end of this app note). Value can also be changed temporarily on the DIS Options Page if DIS is operational on the DACS. Note that the default position limit pertains to DIS packet transmissions as well as the terrain PDU transmission.
When a particular Transmitter or Receiver time out as indicated by the PDU Time Out setting the DACS will issue a request for path loss information pertaining to the affected transmitter or receiver.
Default time out is 5 seconds but can be set to other values via a command line in the Model Builder start up configuration file (see configuration commands at the end of this app note). Value can also be changed temporarily on the DIS Options Page if DIS is operational on the DACS. Note that the default time out pertains to DIS packet transmissions as well as the terrain PDU transmission.
Request for path loss information is not made for radios less than 10 meters apart.
Path loss information will be requested for all Receiver and Transmitter types regardless of whether the particular radio, transmitter, etc. is set to none, local, voicenet or DIS operation in the attached World Position Object.
The packet is in a DIS format. The packet is formatted as follows:
RXpathPDU = record PDUheader : record ProtocolVer : byte; ExerciseID : byte; PDUtype : byte; PDUfamily : byte; TimeStamp : Unsigned_32bit; Length : Unsigned_16bit; Pad1 : Unsigned_16bit; end; RXEntityID : record Site : Unsigned_16bit; Application/Host : Unsigned_16bit; Entity : Unsigned_16bit; end; RXDeviceID : Unsigned_16bit; TXEntityID : record Site : Unsigned_16bit; Application/Host : Unsigned_16bit; Entity : Unsigned_16bit; end; TXDeviceID : Unsigned_16bit; PathFactor : IEEE_float_32bit; LocationRX : record X : IEEE_float_64bit; Y : IEEE_float_64bit; Z : IEEE_float_64bit; end; LocationTX : record X : IEEE_float_64bit; Y : IEEE_float_64bit; Z : IEEE_float_64bit; end; FrequencyMSW : Unsigned_32bit; FrequencyLSW : Unsigned_32bit; end;
All PDUs are delivered in network byte order (Big Endian).
Path Factor loss is of the range 0.0 - 1.0 with 1.0 indicating no loss at all (0dB) and 0.0 indicating complete loss (-300dB).
Transmission of PDUs to the Host Computer
Ethernet packets containing one or more PDUs are transmitted to the host via the host ethernet interface. PDUs are not transmitted over the DIS ethernet interface. The DACs can be configured to place from 1-16 PDUs in a single packet. Number of PDUs/packet is set using a command line in the start up configuration file (see configuration commands at the end of this app note).
Packets are properly formatted UDP ethernet packets.
Broadcast IP address is set using a command line in the start up configuration file (see configuration commands at the end of this app note). This address should be the host IP address.
The UDP port is also set via a command line in the start up configuration file It is recommended that this port number be different from the Host Interface port number set for receiving state information for the audio models.
Network information is displayed on the Terrain Occulting Status Window. This window is accessed via the Terrain selection found on any of the network information submenus (Local, DIS or Voicenet - found on the Main Menu). Display is similar to the other network status displays, showing current network status and configuration . Network parameters as well as several options can be changed temporarily on this page for debug and testing purposes.
UDP packets containing PDUs are transmitted to the host at a maximum rate equal to the Master Model Rate of the DACS. Packets will only be sent out during a frame if new PDUs have been generated.
The maximum transmission rate can also be limited using a configurable division factor. A division factor of one indicates that packets can go out at the master model rate while a division factor of 10 would restrict packet transmission to 1/10th the master model rate. The division factor is set using a command line in the Model Builder start up configuration file (see configuration commands at the end of this app note). Value can also be changed temporarily on the Terrain Status Window.
Note that if more PDUs are generated in a frame than can be transmitted in a single packet then the PDUs will be spread over multiple packets.
Reception and Retransmission By the Host
Packets will be transmitted to the host address and port number specified by the DACS. Upon reception of a packet containing Terrain PDUs, the host computer must perform the following operations:
- Increment PDUtype by 1 changing PDU type from request to reply (current values are 30 for request and 31 for reply)
- Calculate PathFactor value between the locations indicated by LocationRX and LocationTX and insert this value into PathFactor. Note that LocationRX and LocationTX are given by geocentric coordinates. Path factor is value of range 0.0 - 1.0 with 1.0 representing no loss (0.0dB loss) and 0.0 representing complete loss of signal (-300.0dB loss).
- Retransmit the entire PDU back to the sourceIP/sourceUDP port.
It is important that the reply packet contains all of the ID numbers in the original request packet. The host should not modify any field except as described above.
As a simple example, if line of sight occulting was being used:
- PathFactor = 1.0 would be clear line of sight, while
- PathFactor = 0.0 would be occulted by terrain.
If the host has a more sophisticated occulting/propagation model which takes into account frequency, the frequency of the transmitter/receiver pair is provided in the PDU.
Configuration Commands and DefaultsEnabling the Terrain Interface:
... where [Mode] is ON or OFF. This enables the "Terrain" menu under "DisNetwork" and allows the DACS to communicate with a terrain server. The default value is: Terrain=OFF.
Specifying the Number of Terrain PDUs in a Packet
... where [Decimal Number] is in the range 1 to 16 inclusive. The default value is: Terrain:PDUs_packet=16.
Specifying the UDP Ports for the Terrain Interface
... where [Decimal Number] is in the range 0 to 65535, inclusive. This sets the TX and RX UDP ports to the same value. The default is: Terrain:udp_port=55000.
Alternately, you can set the TX and RX UDP ports separately using:
Terrain:tx_udp_port=[Decimal Number] Terrain:rx_udp_port=[Decimal Number]
Setting the Terrain Packet Transmit Rate
This command sets the maximum rate at which the DACS send packets to the terrain server. This is simply the model rate divided by [Decimal Number]. If [Decimal Number] was 10, then one packet would be sent out for every 10 model frames.
Setting the Terrain Gateway
... where [IP Address] is in dotted-quad notation (e.g., YYY.YYY.YYY.YYY) with decimal numbers. Each field must be in the range 0 through 255, inclusive. This commands sets the gateway IP address for the terrain server interface. The default value is: Terrain:gateway=0.0.0.0.
Setting Up External Pathloss Queries
... where [Mode] is OFF, LOS, OTH, or ALL.
This command controls the conditions under which the DACS will send requests for path loss values. If this value is set to OFF, no requests will be sent. If it is set to LOS, then requests will be sent out for in-tune radio pairs, for which the receiving radio is in "Line-Of-Sight" mode. If set to OTH, requests will be sent out for radios in "Over-The-Horizon" mode. Setting this value to ALL, will cause Model Builder to send requests for all in-tune transmitter receiver pairs, regardless of whether they are in "Line-Of-Sight" or "Over-The-Horizon" mode. Default value is: Terrain:request=ALL.
Setting Up Internal Pathloss Queries
... where [Mode] is OFF, LOS, OTH, or ALL.
This statement controls the conditions under which Model Builder will apply its own internal loss calculation to the received power of a radio. For "Line-Of-Sight" radios, Model Builder computes free-space loss, fresnel diffraction effects, and occulting by the smooth ellipsoidal (WGS-84) earth for in-tune transmitter/receiver pairs. This flag will control whether or not an internally-computed loss will be applied to a given type of radio. If it is set to LOS, Model Builder will apply internally-computed losses to "Line-Of-Signt" radios. If it is set to OTH, Model Builder will apply internally-computed losses to "Over-The-Horizon" radios. If it is set to ALL, Model Builder will apply internally-computed losses to all radios. If it is set to OFF, Model Builder will not apply any internally-computed losses to any radios. Default value is: Terrain:pathloss=ALL.
As an example, a typical configuration file would include:
|terrain:broadcast_ip=126.96.36.199||sets destination IP address for terrain PDU packets|
|terrain:udp_port=40000||sets udp port number for both transmission and reception|
|terrain:pdus_packet=5||sets limit to 5 pdus per packet|
|terrain:rate_divider=10||sets packet rate at 1/10 of system model rate|
|terrain:pathloss=All||sets internal loss calculation to 'all'|