Main Content

link

Display or compute communication link status

Description

example

link(rx,tx) displays a one-way point-to-point communication link between a receiver site and transmitter site in the current Site Viewer. The plot is color coded to identify the link success status.

link(rx,tx,propmodel) displays the communication link based on the specified propagation model.

link(___,Name,Value) displays a communication link using additional options specified by Name,Value pairs.

status = link(___) returns the success status of the communication link as true or false.

Examples

collapse all

Create a transmitter site.

tx = txsite('Name','MathWorks', ...
        'Latitude',42.3001, ...
        'Longitude',-71.3503);

Create a receiver site with a sensitivity defined in dBm.

 rx = rxsite('Name','Boston', ...
        'Latitude',42.3601, ...
        'Longitude',-71.0589, ...
        'ReceiverSensitivity',-90);

Plot the communication link between the transmitter and the receiver.

link(rx,tx)

Import and view an STL file. The file models a small conference room with one table and four chairs.

viewer = siteviewer('SceneModel','conferenceroom.stl');

Create a transmitter site near the upper corner of the room and a receiver site above the table. Specify the position using Cartesian coordinates in meters.

tx = txsite('cartesian', ...
    'AntennaPosition',[-1.46; -1.42; 2.1]);
rx = rxsite('cartesian', ...
    'AntennaPosition',[0.3; 0.3; 0.85]);

Plot the communication link between the transmitter and the receiver.

link(rx,tx)

Pan by left-clicking, zoom by right-clicking or by using the scroll wheel, and rotate the visualization by clicking the middle button and dragging or by pressing Ctrl and left-clicking and dragging.

Input Arguments

collapse all

Receiver site, specified as a rxsite object. You can use array inputs to specify multiple sites.

Transmitter site, specified as a txsite object. You can use array inputs to specify multiple sites.

Propagation model, specified as a character vector, a string, or a propagation model created with the propagationModel function. The default value depends on the coordinate system used by the input sites.

Coordinate SystemDefault propagation model value
'geographic'
  • 'longley-rice' when you use a terrain.

  • 'freespace' when you do not use a terrain.

'cartesian'
  • 'freespace' when Map is set to none.

  • 'raytracing' when Map is set to the name of an STL file or a triangulation object. The default ray tracing model uses the shooting and bouncing rays (SBR) method.

You can also specify the propagation model by using the 'PropagationModel' name-value pair argument.

Name-Value Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Type','power'

Propagation model to use for the path loss calculations, specified as the comma-separated pair consisting of 'PropagationModel' and one of the following:

  • 'freespace' — Free space propagation model

  • 'rain' — Rain propagation model

  • 'gas' — Gas propagation model

  • 'fog' — Fog propagation model

  • 'close-in' — Close-in propagation model

  • 'longley-rice' — Longley-Rice propagation model

  • 'tirem' — Tirem propagation model

  • 'raytracing' — Ray tracing propagation model that uses the shooting and bouncing rays (SBR) method

  • A propagation model created with the propagationModel function

The default propagation model is 'longley-rice' when terrain is enabled and 'freespace' when terrain is disabled.

Terrain propagation models, including 'longley-rice' and 'tirem', are only supported for sites with a CoordinateSystem value of 'geographic'.

Data Types: char

Color of successful links, specified as the comma-separated pair consisting of 'SuccessColor' and one of the following:

  • An RGB triplet whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

  • A character vector such as 'red' or 'r'.

  • A string scalar such as "red" or "r".

This table contains the color names and equivalent RGB triplets for some common colors.

Color NameShort NameRGB TripletAppearance
'red''r'[1 0 0]

Sample of the color red

'green''g'[0 1 0]

Sample of the color green

'blue''b'[0 0 1]

Sample of the color blue

'cyan' 'c'[0 1 1]

Sample of the color cyan

'magenta''m'[1 0 1]

Sample of the color magenta

'yellow''y'[1 1 0]

Sample of the color yellow

'black''k'[0 0 0]

Sample of the color black

'white''w'[1 1 1]

Sample of the color white

Data Types: char | string | double

Color of unsuccessful links, specified as the comma-separated pair consisting of 'FailColor' and one of the following:

  • An RGB triplet whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

  • A character vector such as 'red' or 'r'.

  • A string scalar such as "red" or "r".

This table contains the color names and equivalent RGB triplets for some common colors.

Color NameShort NameRGB TripletAppearance
'red''r'[1 0 0]

Sample of the color red

'green''g'[0 1 0]

Sample of the color green

'blue''b'[0 0 1]

Sample of the color blue

'cyan' 'c'[0 1 1]

Sample of the color cyan

'magenta''m'[1 0 1]

Sample of the color magenta

'yellow''y'[1 1 0]

Sample of the color yellow

'black''k'[0 0 0]

Sample of the color black

'white''w'[1 1 1]

Sample of the color white

Data Types: char | string | double

Map for visualization or surface data, specified as a siteviewer object, a triangulation object, a string scalar, or a character vector. Valid and default values depend on the coordinate system.

Coordinate SystemValid map valuesDefault map value
'geographic'
  • A siteviewer object[a].

  • A terrain name, if the function is called with an output argument. Valid terrain names are 'none', 'gmted2010', or the name of the custom terrain data added using addCustomTerrain.

  • The current siteviewer object or a new siteviewer object if none are open.

  • 'gmted2010', if the function is called with an output.

'cartesian'
  • 'none'.

  • A siteviewer object.

  • The name of an STL file.

  • A triangulation object.

  • 'none'.

[a] Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.

Data Types: char | string

Output Arguments

collapse all

Success status of communication links, returned as an M-by-N arrays. M is the number of transmitter sites and N is the number of receiver sites.

Compatibility Considerations

expand all

Behavior changed in R2021b

Introduced in R2019b