Main Content

link

Display or compute communication link status

Description

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.

example

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 to use for the path loss calculations, specified as one of these options:

  • "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. When you specify a ray tracing model as input, the function incorporates multipath interference by using a phasor sum.

  • A propagation model created using the propagationModel function. For example, you can create a ray tracing propagation model that uses the image method by specifying propagationModel("raytracing","Method","image").

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 a glTF™ file, the name of an STL file, or a triangulation object. The default ray tracing model uses the shooting and bouncing rays (SBR) method.

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

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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: "Type","power"

Propagation model to use for the path loss calculations, specified as one of these options:

  • "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. When you specify a ray tracing model as input, the function incorporates multipath interference by using a phasor sum.

  • A propagation model created using the propagationModel function. For example, you can create a ray tracing propagation model that uses the image method by specifying propagationModel("raytracing","Method","image").

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 a glTF file, the name of an STL file, or a triangulation object. The default ray tracing model uses the shooting and bouncing rays (SBR) method.

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

Data Types: char | string

Color of successful links, specified as one of these options:

  • 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 one of these options:

  • 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 objecta

  • 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 a glTF file

  • 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®.

In most cases, if you specify this argument as a value other than a siteviewer or "none", then you must also specify an output argument.

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.

Version History

Introduced in R2017b

expand all