Module `Radio`

Core -- The RADIO Module is responsible for everything that is related to radio transmission and you can hear in DCS, be it TACAN beacons, Radio transmissions...

Banner Image

The Radio contains 2 classes : RADIO and BEACON

What are radio communications in DCS ?

Radio transmissions consist of sound files that are broadcasted on a specific frequency (e.g. 115MHz) and modulation (e.g. AM),
They can be subtitled for a specific duration, the power in Watts of the transmiter's antenna can be set, and the transmission can be looped.

How to supply DCS my own Sound Files ?

Your sound files need to be encoded in .ogg or .wav,
Your sound files should be as tiny as possible. It is suggested you encode in .ogg with low bitrate and sampling settings,
They need to be added in .\l10n\DEFAULT\ in you .miz file (wich can be decompressed like a .zip file),
For simplicty sake, you can let DCS' Mission Editor add the file itself, by creating a new Trigger with the action "Sound to Country", and choosing your sound file and a country you don't use in your mission.

Due to weird DCS quirks, radio communications behave differently if sent by a Unit#UNIT or a Group#GROUP or by any other Positionable#POSITIONABLE

If the transmitter is a Unit#UNIT or a Group#GROUP, DCS will set the power of the transmission automatically,
If the transmitter is any other Positionable#POSITIONABLE, the transmisison can't be subtitled or looped.

Note that obviously, the frequency and the modulation of the transmission are important only if the players are piloting an Advanced System Modelling enabled aircraft, like the A10C or the Mirage 2000C. They will hear the transmission if they are tuned on the right frequency and modulation (and if they are close enough - more on that below). If a FC3 airacraft is used, it will hear every communication, whatever the frequency and the modulation is set to. The same is true for TACAN beacons. If your aircaft isn't compatible, you won't hear/be able to use the TACAN beacon informations.

Author: Hugues "Grey_Echo" Bousquet

Global(s)

BEACON
RADIO

Type `BEACON`

BEACON:AATACAN(TACANChannel, Message, Bearing, BeaconDuration)	Activates a TACAN BEACON on an Aircraft.
BEACON.ClassName
BEACON:New(Positionable)	Create a new BEACON Object.
BEACON:RadioBeacon(FileName, Frequency, Modulation, Power, BeaconDuration)	Activates a general pupose Radio Beacon This uses the very generic singleton function "trigger.action.radioTransmission()" provided by DCS to broadcast a sound file on a specific frequency.
BEACON:StopAATACAN()	Stops the AA TACAN BEACON
BEACON:StopRadioBeacon()	Stops the AA TACAN BEACON
BEACON:_TACANToFrequency(TACANChannel, TACANMode)	Converts a TACAN Channel/Mode couple into a frequency in Hz

Type `RADIO`

RADIO:Broadcast()	Actually Broadcast the transmission * The Radio has to be populated with the new transmission before broadcasting.
RADIO.ClassName
RADIO.FileName	Name of the sound file
RADIO.Frequency	Frequency of the transmission in Hz
RADIO.Loop	(default true)
RADIO.Modulation	Modulation of the transmission (either radio.modulation.AM or radio.modulation.FM)
RADIO:New(Positionable)	Create a new RADIO Object.
RADIO:NewGenericTransmission(FileName, Frequency, Modulation, Power, Loop)	Create a new transmission, that is to say, populate the RADIO with relevant data In this function the data is especially relevant if the broadcaster is anything but a UNIT or a GROUP, but it will work with a UNIT or a GROUP anyway.
RADIO:NewUnitTransmission(FileName, Subtitle, SubtitleDuration, Frequency, Modulation, Loop)	Create a new transmission, that is to say, populate the RADIO with relevant data In this function the data is especially relevant if the broadcaster is a UNIT or a GROUP, but it will work for any Positionable#POSITIONABLE.
RADIO.Positionable	The transmiter
RADIO.Power	Power of the antenna is Watts
RADIO:SetFileName(FileName)	Check validity of the filename passed and sets RADIO.FileName
RADIO:SetFrequency(Frequency)	Check validity of the frequency passed and sets RADIO.Frequency
RADIO:SetLoop(Loop)	Check validity of the loop passed and sets RADIO.Loop
RADIO:SetModulation(Modulation)	Check validity of the frequency passed and sets RADIO.Modulation
RADIO:SetPower(Power)	Check validity of the power passed and sets RADIO.Power
RADIO:SetSubtitle(Subtitle, SubtitleDuration)	Check validity of the subtitle and the subtitleDuration passed and sets RADIO.subtitle and RADIO.subtitleDuration Both parameters are mandatory, since it wouldn't make much sense to change the Subtitle and not its duration
RADIO:StopBroadcast()	Stops a transmission This function is especially usefull to stop the broadcast of looped transmissions
RADIO.Subtitle	Subtitle of the transmission
RADIO.SubtitleDuration	Duration of the Subtitle in seconds

Global(s)

#BEACON BEACON

#RADIO RADIO

Type `Radio`

Type `BEACON`

BEACON class, extends Base#BASE

After attaching a #BEACON to your Positionable#POSITIONABLE, you need to select the right function to activate the kind of beacon you want.

There are two types of BEACONs available : the AA TACAN Beacon and the general purpose Radio Beacon. Note that in both case, you can set an optional parameter : the BeaconDuration. This can be very usefull to simulate the battery time if your BEACON is attach to a cargo crate, for exemple.

AA TACAN Beacon usage

This beacon only works with airborne Unit#UNIT or a Group#GROUP. Use #BEACON() to set the beacon parameters and start the beacon. Use @#BEACON:StopAATACAN}() to stop it.

General Purpose Radio Beacon usage

This beacon will work with any Positionable#POSITIONABLE, but **it won't follow the Positionable#POSITIONABLE** ! This means that you should only use it with Positionable#POSITIONABLE that don't move, or move very slowly. Use #BEACON() to set the beacon parameters and start the beacon. Use #BEACON() to stop it.

Field(s)

BEACON:AATACAN(TACANChannel, Message, Bearing, BeaconDuration)

Activates a TACAN BEACON on an Aircraft.

Parameters

#number TACANChannel : (the "10" part in "10Y"). Note that AA TACAN are only available on Y Channels
#string Message : The Message that is going to be coded in Morse and broadcasted by the beacon
#boolean Bearing : Can the BEACON be homed on ?
#number BeaconDuration : How long will the beacon last in seconds. Omit for forever.

Return value

#BEACON: self

Usage:

-- Let's create a TACAN Beacon for a tanker
local myUnit = UNIT:FindByName("MyUnit") 
local myBeacon = myUnit:GetBeacon() -- Creates the beacon

myBeacon:AATACAN(20, "TEXACO", true) -- Activate the beacon

#string BEACON.ClassName

BEACON:New(Positionable)

Create a new BEACON Object.

This doesn't activate the beacon, though, use BEACON.AATACAN or BEACON.Generic If you want to create a BEACON, you probably should use Positionable#POSITIONABLE.GetBeacon() instead.

Parameter

Wrapper.Positionable#POSITIONABLE Positionable : The Positionable that will receive radio capabilities.

Return values

#BEACON: Beacon
#nil: If Positionable is invalid

BEACON:RadioBeacon(FileName, Frequency, Modulation, Power, BeaconDuration)

Activates a general pupose Radio Beacon This uses the very generic singleton function "trigger.action.radioTransmission()" provided by DCS to broadcast a sound file on a specific frequency.

Although any frequency could be used, only 2 DCS Modules can home on radio beacons at the time of writing : the Huey and the Mi-8. They can home in on these specific frequencies : Mi8 R-828 -> 20-60MHz * ARKUD -> 100-150MHz (canal 1 : 114166, canal 2 : 114333, canal 3 : 114583, canal 4 : 121500, canal 5 : 123100, canal 6 : 124100) AM * ARK9 -> 150-1300KHz Huey AN/ARC-131 -> 30-76 Mhz FM

Parameters

#string FileName : The name of the audio file
#number Frequency : in MHz
#number Modulation : either radio.modulation.AM or radio.modulation.FM
#number Power : in W
#number BeaconDuration : How long will the beacon last in seconds. Omit for forever.

Return value

#BEACON: self

Usage:

-- Let's create a beacon for a unit in distress.
-- Frequency will be 40MHz FM (home-able by a Huey's AN/ARC-131)
-- The beacon they use is battery-powered, and only lasts for 5 min
local UnitInDistress = UNIT:FindByName("Unit1")
local UnitBeacon = UnitInDistress:GetBeacon()

-- Set the beacon and start it
UnitBeacon:RadioBeacon("MySoundFileSOS.ogg", 40, radio.modulation.FM, 20, 5*60)

BEACON:StopAATACAN()

Stops the AA TACAN BEACON

Return value

#BEACON: self

BEACON:StopRadioBeacon()

Stops the AA TACAN BEACON

Return value

#BEACON: self

BEACON:_TACANToFrequency(TACANChannel, TACANMode)

Converts a TACAN Channel/Mode couple into a frequency in Hz

Parameters

#number TACANChannel :
#string TACANMode :

Return values

#number: Frequecy
#nil: if parameters are invalid

Type `RADIO`

RADIO class, extends Base#BASE

RADIO usage

There are 3 steps to a successful radio transmission.

First, you need to **"add a #RADIO object** to your Positionable#POSITIONABLE. This is done using the Positionable#POSITIONABLE.GetRadio() function,
Then, you will set the relevant parameters to the transmission (see below),
When done, you can actually broadcast the transmission (i.e. play the sound) with the RADIO.Broadcast() function.

Methods to set relevant parameters for both a Unit#UNIT or a Group#GROUP or any other Positionable#POSITIONABLE

RADIO.SetFileName() : Sets the file name of your sound file (e.g. "Noise.ogg"),
RADIO.SetFrequency() : Sets the frequency of your transmission.
RADIO.SetModulation() : Sets the modulation of your transmission.
RADIO.SetLoop() : Choose if you want the transmission to be looped. If you need your transmission to be looped, you might need a #BEACON instead...

Additional Methods to set relevant parameters if the transmiter is a Unit#UNIT or a Group#GROUP

RADIO.SetSubtitle() : Set both the subtitle and its duration,
RADIO.NewUnitTransmission() : Shortcut to set all the relevant parameters in one method call

Additional Methods to set relevant parameters if the transmiter is any other Positionable#POSITIONABLE

RADIO.SetPower() : Sets the power of the antenna in Watts
RADIO.NewGenericTransmission() : Shortcut to set all the relevant parameters in one method call

What is this power thing ?

If your transmission is sent by a Positionable#POSITIONABLE other than a Unit#UNIT or a Group#GROUP, you can set the power of the antenna,
Otherwise, DCS sets it automatically, depending on what's available on your Unit,
If the player gets too far from the transmiter, or if the antenna is too weak, the transmission will fade and become noisyer,
This an automated DCS calculation you have no say on,
For reference, a standard VOR station has a 100W antenna, a standard AA TACAN has a 120W antenna, and civilian ATC's antenna usually range between 300 and 500W,
Note that if the transmission has a subtitle, it will be readable, regardless of the quality of the transmission.

Field(s)

RADIO:Broadcast()

Actually Broadcast the transmission * The Radio has to be populated with the new transmission before broadcasting.

Please use RADIO setters or either Radio#RADIO.NewGenericTransmission or Radio#RADIO.NewUnitTransmission
This class is in fact pretty smart, it determines the right DCS function to use depending on the type of POSITIONABLE
If the POSITIONABLE is not a UNIT or a GROUP, we use the generic (but limited) trigger.action.radioTransmission()
If the POSITIONABLE is a UNIT or a GROUP, we use the "TransmitMessage" Command
If your POSITIONABLE is a UNIT or a GROUP, the Power is ignored.
If your POSITIONABLE is not a UNIT or a GROUP, the Subtitle, SubtitleDuration are ignored

Return value

#RADIO: self

#string RADIO.ClassName

#string RADIO.FileName: Name of the sound file

#number RADIO.Frequency: Frequency of the transmission in Hz

#boolean RADIO.Loop: (default true)

#number RADIO.Modulation: Modulation of the transmission (either radio.modulation.AM or radio.modulation.FM)

RADIO:New(Positionable)

Create a new RADIO Object.

This doesn't broadcast a transmission, though, use RADIO.Broadcast to actually broadcast If you want to create a RADIO, you probably should use Positionable#POSITIONABLE.GetRadio() instead

Parameter

Wrapper.Positionable#POSITIONABLE Positionable : The Positionable that will receive radio capabilities.

Return values

#RADIO: Radio
#nil: If Positionable is invalid

RADIO:NewGenericTransmission(FileName, Frequency, Modulation, Power, Loop)

Create a new transmission, that is to say, populate the RADIO with relevant data In this function the data is especially relevant if the broadcaster is anything but a UNIT or a GROUP, but it will work with a UNIT or a GROUP anyway.

Only the #RADIO and the Filename are mandatory

Parameters

#string FileName :
#number Frequency : in MHz
#number Modulation : either radio.modulation.AM or radio.modulation.FM
#number Power : in W
Loop :

Return value

#RADIO: self

RADIO:NewUnitTransmission(FileName, Subtitle, SubtitleDuration, Frequency, Modulation, Loop)

Create a new transmission, that is to say, populate the RADIO with relevant data In this function the data is especially relevant if the broadcaster is a UNIT or a GROUP, but it will work for any Positionable#POSITIONABLE.

Only the RADIO and the Filename are mandatory.

Parameters

#string FileName :
#string Subtitle :
#number SubtitleDuration : in s
#number Frequency : in MHz
#number Modulation : either radio.modulation.AM or radio.modulation.FM
#boolean Loop :

Return value

#RADIO: self

Positionable#POSITIONABLE RADIO.Positionable: The transmiter

#number RADIO.Power: Power of the antenna is Watts

RADIO:SetFileName(FileName)

Check validity of the filename passed and sets RADIO.FileName

Parameter

#string FileName : File name of the sound file (i.e. "Noise.ogg")

Return value

#RADIO: self

RADIO:SetFrequency(Frequency)

Check validity of the frequency passed and sets RADIO.Frequency

Parameter

#number Frequency : in MHz (Ranges allowed for radio transmissions in DCS : 30-88 / 108-152 / 225-400MHz)

Return value

#RADIO: self

RADIO:SetLoop(Loop)

Check validity of the loop passed and sets RADIO.Loop

Parameter

#boolean Loop :

Return value

#RADIO: self

Usage:

RADIO:SetModulation(Modulation)

Check validity of the frequency passed and sets RADIO.Modulation

Parameter

#number Modulation : either radio.modulation.AM or radio.modulation.FM

Return value

#RADIO: self

RADIO:SetPower(Power)

Check validity of the power passed and sets RADIO.Power

Parameter

#number Power : in W

Return value

#RADIO: self

RADIO:SetSubtitle(Subtitle, SubtitleDuration)

Check validity of the subtitle and the subtitleDuration passed and sets RADIO.subtitle and RADIO.subtitleDuration Both parameters are mandatory, since it wouldn't make much sense to change the Subtitle and not its duration

Parameters

#string Subtitle :
#number SubtitleDuration : in s

Return value

#RADIO: self

Usage:

-- create the broadcaster and attaches it a RADIO
local MyUnit = UNIT:FindByName("MyUnit")
local MyUnitRadio = MyUnit:GetRadio()

-- add a subtitle for the next transmission, which will be up for 10s
MyUnitRadio:SetSubtitle("My Subtitle, 10)

RADIO:StopBroadcast()

Stops a transmission This function is especially usefull to stop the broadcast of looped transmissions

Return value

#RADIO: self

#string RADIO.Subtitle: Subtitle of the transmission

#number RADIO.SubtitleDuration: Duration of the Subtitle in seconds

Modules

Module Radio

Author: Hugues "Grey_Echo" Bousquet

Global(s)

Type BEACON

Type RADIO

Global(s)

Type Radio

Type BEACON

BEACON class, extends Base#BASE

AA TACAN Beacon usage

General Purpose Radio Beacon usage

Field(s)

Parameters

Return value

Usage:

Parameter

Return values

Parameters

Return value

Usage:

Return value

Return value

Parameters

Return values

Type RADIO

RADIO class, extends Base#BASE

RADIO usage

Field(s)

Return value

Parameter

Return values

Parameters

Return value

Parameters

Return value

Parameter

Return value

Parameter

Return value

Parameter

Return value

Usage:

Parameter

Return value

Parameter

Return value

Parameters

Return value

Usage:

Return value

Module `Radio`

Type `BEACON`

Type `RADIO`

Type `Radio`

Type `BEACON`

Type `RADIO`