comm

See Predefined Comm Types

Script Class: WsfComm

comm <name-or-type> <base-type-name> … end_comm
comm <name-or-type> <base-type-name>
  ... Platform Part Commands ...
  ... Articulated Part Commands ...
  ... protocol Commands ...
  ... medium Commands ...

  # Common Device Characteristic Commands

  transmit_mode [ intermittent | continuous ]
  modifier_category <category-name>

  # Common Datalink Commands

  channels <integer-value>
  queue_type [ fifo | lifo | priority ]
  queue_limit <queue-limit>
  purge_interval <time-value>
  retransmit_attempts <integer-value>
  retransmit_delay <time-value>

  # Common Router Association Commands

  router_name <router-name>
  gateway <platform-name> <comm-name>

  # Common Network Addressing Commands

  network_name [ <network-name>  | <local:master> | <local:slave> ]
  network_address <address>
  address <address>
  link <platform-name> <comm-name>
  local_link <comm-name>
  link_address <address>

  # Common Physical Layer Commands

  propagation_speed <random-speed-reference>
  transfer_rate <random-data-rate-reference>
  packet_loss_time <random-time-reference>

  # Frequency Selection Commands

  frequency_select_delay <time-value>

end_comm

Overview

A comm object represents a device over which messages can be sent between platforms.

The following commands are available for all comm devices, but they are not necessarily used by all comm models, or in the case of the router specific commands, on all protocol implementations.

Common Device Characteristic Commands

transmit_mode [ intermittent | continuous ]

Defines if the device transmits intermittently or continuously. This is currently applicable only to devices that transmit over the air (e.g., WSF_RADIO_TRANSCEIVER). intermittent indicates the device radiates only when a message is actually being transmitted. continuous indicates the devices radiates as long as it is ‘on’. continuous would be used to model systems such as television or radio broadcast stations.

This is used by WSF_PASSIVE_SENSOR to determine the mechanism to be used for detecting signals from this device.

Default intermittent

modifier_category <category-name>

The category that maps to the attenuation value defined in the zone_set. Setting this value tells the communications device to evaluate zones for attenuation. See Zone-based attenuation for more information.

Common Network Addressing Commands

These commands are used to define the address of a comm. By extension, an address also defines network membership of a comm object. Finally, these commands may also define the connectivity (external to default connectivity behavior) of comm objects to other comm objects for the purpose of message routing. Support for usage of explicit and static linking commands depends on the protocol implementation.

Warning

It is recommended to use static addressing of communication devices by explicitly specifying the address of comms sharing a network across distributed simulations. See Communications Primer for more details.

network_name [ <network-name> | <local:master> | <local:slave> ]

Define the network name that this device belongs to. Network names are strings that map directly to a value used to generate a 32-bit IPv4 address. The use of IPv4 does not infer that AFSIM is only capable of IP based communications, it is simply an internally consistent method to identify all comm objects in the simulation. Usage of the IPv4 address to infer anything beyond an identifier and common membership in a “network” or “group” depends entirely on the comm type implementation itself. Due to support for legacy AFSIM behavior, all comm devices on the same network are assumed to have connectivity to every other object in the same network at the beginning of the simulation with default settings (mesh network topology).

Communication to other comm objects not part of the same network require explicit definition of a link between the objects. If a comm object is not provided network membership or addressing via this command, the network_address command, or the address command, then the comm object is assumed to belong to a generic network in AFSIM referred to as the “default” network, and will be provided an address based on the first available, unused address.

Note

The commands network_name, network_address, and address are exclusive. Only one of these should be used on any given comm.

The <local:master> and <local:slave> are special case network names used to create simple networks based on the explicit commander-subordinate relationships as defined by the commander keyword in platform definition. This, in effect, creates a network between a commander and its subordinates. Example:

# Creates a network named master:CMDR
platform CMDR WSF_PLATFORM
   add comm  name  Predefined Comm Types
      network_name <local:master>
   end_comm
end_platform
platform SUB-1 WSF_PLATFORM
   commander CMDR
   add comm  name  Predefined Comm Types
      network_name <local:slave>
   end_comm
end_platform
platform SUB-2 WSF_PLATFORM
   commander CMDR
   add comm  name  Predefined Comm Types
      network_name <local:slave>
   end_comm
end_platform

Default default

network_address <address>

Define the device’s network address. If the address provided belongs to an existing network, this comm device will join that network and be provided the lowest available address not currently assigned in that network. If the address is not currently managed by a network, a network will be created based on a combination of the parent platform and comm name (network-name = platform-name.comm-name) and this comm added to the first available address.

Note

The commands network_name, network_address, and address are exclusive. Only one of these should be used on any given comm.

address <address>

The address command specifies a specific, user provided address for this comm device. If the address is managed by a network, this comm device will join that network - otherwise a new network will be created that is based on the name of the platform owning the comm device, and the comm device (e.g. platform-name.comm-name). Note that this command may fail and halt simulation input processing if the address provided is already utilized elsewhere, which can happen via use of dynamic addressing based on other objects being assigned addresses.

Note

The commands network_name, network_address, and address are exclusive. Only one of these should be used on any given comm.

This command provides a communications link between this comm device and the device specified. Any number of links may be defined on any given comm object. This link is established both via truth in the network manager and locally as a perception-based link (for the legacy protocol only - other protocols MAY use this command on a case-by-case basis, but are not required to). Be mindful that links may be removed during the simulation if the comm implementation reports failed links for removal, such as when a WSF_RADIO_TRANSCEIVER is out of the EM interaction limits to communicate with another comm, or if the particular network object used to enforce topologies does not support the link provided via this input.

This command is equivalent to the link command for comms on the same platform. As such, only the linking comm name is required to establish this link, and is convenient for platform_type definitions where the platform name is not available in that context.

This command performs the same actions as the link command above, except it uses a specific address to create the link to. This assumes that knowledge of the comm address is known at the time of input, as other addressing commands are dynamic in nature.

Common Router Association Commands

These commands relate specifically to the comm interface and its relation to the router object.

router_name <router-name>

Specifies by name the router this comm is assigned to as an interface. Router must be located on the same platform instance as the comm.

Default Use the default router available on every platform instance in AFSIM

gateway <platform-name> <comm-name>

Specifies the remote interface to be used as the gateway for this comm instance. Since AFSIM allows multiple links per comm interface, the exact destination interface must be specified for gateway usage. This value will only be used if this comm is designated as the gateway interface to be used by the router object.

Default no gateway specification, no gateway usage

Common Physical Layer Commands

These commands define the physical characteristics associated with the comm device, (not including the transmitter and receiver definitions).

propagation_speed <random-speed-reference>

Sets the speed of message propagation. This is a pass-through command that defines the propagation speed for the medium associated with this comm object, provided for legacy compatability.

This command is not available for usage in the context of the comm object if the user has explicitly specified a medium type. In such cases, the propagation_speed (if available depending on the medium type) must be defined via the medium definition.

Default c (speed of light constant)

transfer_rate <random-data-rate-reference>

Sets the amount of data that can be transmitted by this comm over a set period of time. Any message being sent by this comm uses this value for its transfer rate. Any uninitialized value for transfer_rate is interpreted to be instantaneous transfer for most comm implementations.

This command defines the maximum transfer rate available for the comm object based on its hardware model specification. Any subsequent explicit usage of the medium object may have its own unique value associated with a transfer rate (or a completely different method of determining this value). In such cases where these values differ, any subsequent transmission using this comm device is always the smaller of these two values, such that the transfer rate may be limited by either the comm model itself, or the medium it is using.

Default -1 (instantaneous transfer)

packet_loss_time <random-time-reference>

Sets a time that adds to the delay in every transmission by this comm. Although indicated as a delay due to packet loss, this value can be used to introduce a delay to the normal transmission time of any comm device for any reason, or an aggregate delay due to modelling multiple sources of transmission delay.

This command is not available for usage in the context of the comm object if the user has explicitly specified a medium type. In such cases, the packet loss time (if available depending on the medium type) must be defined via the medium definition.

Default 0 (no delay)

Frequency Selection Commands

frequency_select_delay <time-value>

Specifies the delay when selecting between alternate frequencies as defined on the transmitter.

Default 0.0 seconds

Frequency Selection Notes

Note

This input (frequency_select_delay) is only operational for the WSF_AGILITY_EFFECT frequency_changing functionality.

Jamming Detection Commands

comm <name-or-type> <base-type-name>
  # Jamming Detection Commands

  jamming_perception_timeout <time-value>
  jamming_perception_threshold <ratio>
  continuous_jamming_perception_threshold <ratio>
  pulsed_jamming_perception_threshold <ratio>
  coherent_jamming_perception_threshold <ratio>
end_comm

These commands are can be used to assist in the simulation of an operator detecting that communications are being jammed.

jamming_perception_timeout <time-value>

Specifies the time after which jamming that was perceived is no longer perceived that the perception of jamming will be returned to a ‘false’ state. If jamming is perceived again before this time has elapsed then the perception of jamming will be maintained ‘true’.

Default 0.0 seconds

jamming_perception_threshold <ratio>
continuous_jamming_perception_threshold <ratio>
pulsed_jamming_perception_threshold <ratio>
coherent_jamming_perception_threshold <ratio>

Specifies the minimum threshold value that jamming will be perceived by the operator. Often used in conjunction with jamming_perception_timeout, JammingPerceived script method.

Default 380 dB