RadioPlan

General

RadioPlan is the module for radioplanning. Radioplanning involves to define the radio equipment, optimize positions and parameters to ensure succesful radio communication. The Radioplan module offers a set of tools to achieve this:

• Radio and RadioNet coverage predictions
• RadioNet connectivity predictions
• Equipment templates
• Antenna models
• Propagation models for VHF, UHF, SHF

Functionality is controlled via the interface IMariaRadioPlanLayer

public interface IMariaRadioPlanLayer : IMariaLayer

Data model

Radio

The Radio represents a physical radio that is both a transmitter and receiver of radio signals.

A Radio must be attached to a Site, which defines the physical position of the Radio. For coverage calculations, both a Site and an Antenna must be assigned to the Radio.

Property	Type	Description
Id	Guid	Unique identifier for the radio.
Name	string	Name of the radio.
RadioSystem	RadioSystem	The radio system of the radio. The RadioSystem property of the Radio must match the RadioSystem property of the RadioNet.
TxPower	SignalPower	[dBm] The transmitter output power of the radio.
Loss	Decibel	[dB] Total signal loss between the radio and the antenna system. This includes cable loss, connector loss, filters, and other inline components.
RxSensitivity	SignalPower	[dBm] The receiver sensitivity threshold. Represents the minimum signal strength the receiver can reliably detect while maintaining required performance metrics (e.g., BER or SINR). Lower (more negative) values indicate a more sensitive receiver.
Antenna	Antenna?	The antenna connected to the radio. An Antenna must be connected for coverage calculation.
Frequency	Frequency	[MHz] The operating center frequency of the radio. The Frequency is set by the RadioNet.
Status	Status	The current operational status of the radio.
Site	Site	The site where the radio is installed or registered.
RadioNet	RadioNet?	The radio network to which this radio belongs.

Site

The Site defines the geographical position for one or more radios. Radios on the same Site is considered to be collocated.

Property	Type	Description
Id	Guid	Unique identifier for the site.
Name	string	Name of the site.
Location	GeoPos	The geographical position of the site.
Status	Status	The current operational status of the site.
Radios	ImmutableArray<Radio>	The radios deployed at this site.

RadioNet

The RadioNet holds a group of radios that can communicate. The RadioNet has some properties that are shared for all Radios in the RadioNet:

• RadioSystem
• TerminalProperties - optional
• CoverageCalculationSettings - optional
• Frequencies

Property	Type	Description
Id	Guid	Unique identifier for the radio net.
Name	string	Name of the radio net.
NetworkType	NetworkType	Defines the type of network the radios operate within.
RadioSystem	RadioSystem	Identifies the radio system used for this network. Available radio systems is restricted by the network type.
TerminalProperties	TerminalProperties?	Terminal‑specific configuration for radios that are part of this network.
CoverageCalculationSettings	CoverageCalculationSettings?	Configuration settings used when performing coverage calculations for this network. Overrides application settings when this is set.
MasterRadio	Radio?	The identifier of the designated master radio for this network. The master radio typically provides synchronization, control, or timing functions depending on the network type
Radios	ImmutableArray<Radio>	The collection of radios participating in this network.
Frequencies	ImmutableArray<Frequency>	The set of frequencies allocated to this network. Radios in the network can only use one of the allocated frequencies.

TerminalProperties

Terminal configuration for user terminals that are part of a cellular network type RadioNet.

Property	Type	Description
Id	Guid	Unique identifier for the terminal properties.
TxPower	SignalPower	[dBm] The transmitter output power of the terminal.
RxSensitivity	SignalPower	[dBm] The receiver sensitivity of the terminal.
AntennaGain	Decibel	[dB] The gain of the terminal’s antenna.

Antenna

A single Antenna can be applied to the radio.

Property	Type	Description
Id	Guid	Unique identifier for the antenna.
AntennaType	AntennaType	The antenna type used by this antenna.
Height	double	The antenna height measured in meters above ground level (AGL). This defines the elevation of the antenna relative to the local terrain surface and is a key parameter in propagation and coverage calculations.
Direction	Azimuth	The azimuth direction the antenna is oriented toward, expressed as a bearing in degrees (0–360). Defines the horizontal pointing direction of directional antennas.
ElectricalTilt	Tilt	The electrical downtilt of the antenna, defined in degrees.
MechanicalTilt	Tilt	The mechanical downtilt of the antenna, defined in degrees.
PositionOffset	PositionOffset	The position offset relative to the Site location.

PositionOffset

Position offset of Antenna relative to Site location.

Property	Type	Description
Direction	Azimuth	[degrees] The horizontal direction (bearing in degrees) of the antenna’s position offset relative to the Site location.
Distance	double	[m] The horizontal distance of the antenna’s position offset relative to the Site location.

AntennaType

Property	Type	Description
Id	Guid	Unique identifier for the antenna type.
Name	string	The name of the antenna type.
OmniDirectional	bool	Indicates whether the antenna is omnidirectional in azimuth.
AntennaPatternSpecs	ImmutableArray<AntennaPatternSpec>	The set of antenna pattern specifications associated with this antenna type.
MinimumFrequency	Frequency	[MHz] The lowest frequency covered by the associated pattern specifications. Returns 0 if no specs exist.
MaximumFrequency	Frequency	[MHz] The highest frequency covered by the associated pattern specifications. Returns 0 if no specs exist.

Antenna type can return an antenna pattern specification valid for a specific radio frequency and electrical tilt.

public AntennaPatternSpec? GetAntennaPatternSpec(Frequency frequency, Tilt electricalTilt)

The list of available antenna types is available from the Antenna Service which are handled by the AntennaCache:

var antennaTypes = await RadioPlanLayer.AntennaCache.GetAsync();

From the AntennaType we get the string AntennaTypeName which is set on the Antenna object. Antenna cache can return antenna types valid for a specific radio frequency.

Task<IEnumerable<AntennaType>> GetAntennaTypeForFrequencyAsync(Frequency frequency);

AnntennaPatternSpec

A specification describing the antenna’s radiation characteristics for a particular frequency range and electrical tilt setting. Each pattern spec typically corresponds to a manufacturer‑defined dataset for a specific band and tilt configuration.

Property	Type	Description
Name	string	Human‑readable name or label for this pattern specification.
MaxGain	double	The maximum gain (in dBi) of the antenna within this specific pattern definition. Represents the highest gain value found in the azimuth/elevation radiation pattern for this frequency range and tilt.
FrequencyLowerBoundary	Frequency	[MHz] The lower frequency boundary (inclusive) for which this pattern specification is valid. Frequencies below this value cannot use this pattern.
FrequencyUpperBoundary	Frequency	[MHz] The upper frequency boundary (inclusive) for which this pattern specification is valid. Frequencies above this value cannot use this pattern.
ElectricalTilt	Tilt	[degrees] The electrical downtilt (in degrees, positive values downwards) associated with this pattern specification. This indicates how the antenna’s vertical radiation pattern is shaped electronically for this dataset.

AntennaPattern

Represents a full antenna radiation pattern for a specific frequency range and electrical tilt. Extends AntennaPatternSpec by providing detailed horizontal and vertical gain patterns used for coverage calculations.

Property	Type	Description
HorizontalGains	double[]	[dB] Horizontal-plane gain values (azimuth pattern).
VerticalGains	double[]	[dB] Vertical-plane gain values (elevation pattern).

How to use the Radioplan API

Most mehods in the Radioplan API returns Result<T> to indicate success and failure.

Result<T>

Result and Result<TValue> implement a functional-style result pattern for handling success and failure without relying on exceptions for control flow.

Instead of throwing exceptions, methods can return a Result object that explicitly indicates:

• whether the operation succeeded
• and, if not, what went wrong

This leads to clearer, more predictable, and testable code

Design Intent

This pattern is meant to:

• Replace exception-driven flow. Exceptions should be reserved for truly unexpected situations—not validation or business rules.
• Make failures explicit. Callers are forced to acknowledge failure cases instead of ignoring them.
• Encourage safer code. You cannot access a value unless the result is successful.

• Improve readability Instead of hidden control flow via exceptions, outcomes are visible in method signatures:

  Result<Radio> CreateRadio(...)
  

Core Concepts

Success vs Failure

Every Result has two possible states:

• Success
  • IsSuccess == true
  • Error == NoError
• Failure
  • IsSuccess == false
  • Error contains details about what went wrong

if (result.IsSuccess)
{
    // proceed
}
else
{
    // handle result.Error
}

Creating Results

Non-generic (no return value)

return Result.Success();

return Result.Failure(new Error("Something went wrong"));

Generic (with return value)

return Result.Success(42);

return Result.Failure<int>(new Error("Invalid number"));

Accessing Values

Only valid for successful results:

Result<int> result = Result.Success(10);

int value = result.Value; // OK

If accessed on a failure:

result.Value // throws InvalidOperationException

So always check:

if (result.IsSuccess)
{
    var value = result.Value;
}

Example Usage

public static Result<Frequency> Create(double frequencyInMhz)
{
    if (frequencyInMhz <= 0)
    {
        return Result.Failure<Frequency>(new ValidationError("Frequency", "Value must be positive."));
    }

    var mhz = (uint)frequencyInMhz;
    var khz = (uint)((frequencyInMhz - mhz) * 1000);
    var hz = (uint)((frequencyInMhz - mhz - khz) * 1000000);
    return Result.Success(new Frequency(mhz, khz, hz));
}

var frequencyResult = Frequency.Create(_newFrequency);
if (frequencyResult.IsFailure)
{
    Console.WriteLine(frequencyResult.Error.Message);
    return;
}
var frequency = frequencyResult.Value;

When to Use This

Use Result when:

• You expect failures as part of normal logic (validation, lookups, business rules)
• You want to avoid excessive try/catch blocks

Avoid overusing it for:

• cases where failure truly is exceptional

Data model stores

Site store

Access to the sites in a Situation is provided through IRadioPlanLayer.SiteStore, see IRadioPlanSiteStore for functionality.

Save a new Site:

 Site = new Site(Guid.NewGuid(), Name, Location);
 _radioPlanLayer.SiteStore.AddOrUpdate(Site);

Get all sites:

var sites = _radioPlanLayer.SiteStore.Get();

Get a speficic site:

var site = _radioPlanLayer.SiteStore.Get(siteId);

Remove a site from store:

RadioPlanLayer.SiteStore.Remove(site);

Radio store

Access to radios in a Situation is provided through IRadioPlanLayer.RadioStore, see IRadioplanRadioStore for functionality.

Similar to SiteStore, this interface uses AddOrUpdate, Get and Remove.

Radio net store

Access to radio nets in a Situation is provided through IRadioPlanLayer.RadioNetStore, see IRadioplanRadioNetStore for functionality.

Similar to SiteStore, this interface uses AddOrUpdate, Get and Remove.

Situation

The Situation holds collections of site, radios and radio nets. Only one Situation can be active at the same time.

The Situation data can be stored in to persistent storage system as Maria DrawObjects with the help of IMariaRadioPlanLayer.Serialize

Example of saving to a Situation file:

byte[] situationBytes = _radioPlanLayer.Serialize(_parent.DrawObjectCommonFactory);
File.WriteAllBytesAsync(filePath, situationBytes);

Situation data can be restored from persistent storage system with help of IMariaRadioPlanLayer.DeSerialize The Situation will be set as active in this method. Example reading from a file:

byte[] situationBytes =  await System.IO.File.ReadAllBytesAsync(filePath);
_radioPlanLayer.DeSerialize(situationBytes, _parent.DrawObjectCommonFactory);

A new Situation is created with IMariaRadioPlanLayer.CreateNewSituation comment:

Coverage predictions

Calculate coverage

Coverage plots and coverage contours are created from coverage predictions for Radios. See the Coverage Predictions page for a description of the coverage calculation process.

Coverage plots

To show coverage plots in the map, follow these steps:

• Select Radio coverage areas to include in the plot with IMariaRadioPlanLayer.IRadioCoverage, methods AddOrUpdate and Remove.
  • Combined radio coverage plot for a RadioNet can be created by adding all Radios in the RadioNet:

foreach (var radio in radioNet.Radios)
{
    _radioPlanLayer.RadioCoverage.AddOrUpdate(radio);
}

• The plot visibility is controlled with IMariaRadioPlanLayer.IRadioCoverage.Visible, and must be set to true to show plot.

• Select the plot type to show with IMariaRadioPlanLayer.IRadioCoverage.PlotType. See the Coverage Plots page for descriptions of the plot types.

Coverage contours

For a polygon presentation of coverage areas, coverage contours can be calculated and displayed.

See: Coverage Contours page

Connectivity Lines

Connectivity lines show the connectivity between radios in a RadioNet.

See: Connectivity Lines page

Route Coverage

For seeing coverage along a route.

See: Route Coverage page

Settings

RadioPlanSettings

Radio plan settings is available from IMariaRadioPlanLayer.Settings

These settings is used to control:

• Setting for creating coverage predictions
• Color schemas for plots

See: Radio plan Settings pages

Dependent External Services

The radioplan module uses external services for

• Antenna store
• Coverage calculations

These services need to have their URI's configured through settings.