rxsite

Create RF receiver site

Description

Use the rxsite object to create a radio frequency (RF) receiver site.

A receiver consists of an RF circuit and an antenna, where the antenna intercepts radio waves and converts them to a current that is decoded by the RF circuit (e.g. demodulated) into a signal. Key characteristics of a receiver include its sensitivity and its antenna radiation pattern.

Creation

Syntax

rx = rxsite

rx = rxsite(coordsys)

rx = rxsite(___,PropertyName=Value)

Description

rx = rxsite creates a radio frequency receiver site in geographic coordinates.

rx = rxsite(coordsys) specifies the coordinate system used to reference the location of the site. By default, receiver sites use a geographic coordinate system.

rx = rxsite(___,PropertyName=Value) sets properties using one or more name-value arguments. This syntax is useful for creating multiple receiver sites.

• For geographic receiver sites, you can specify the location by setting the Latitude, Longitude, and AntennaHeight properties.

• For Cartesian receiver sites, you can specify the location by setting the AntennaPosition property.

Input Arguments

coordsys — Coordinate system used to reference location of site

"geographic" (default) | "cartesian"

Coordinate system used to the reference the location of the site, specified as "geographic" or "cartesian". This argument sets the CoordinateSystem property of the site.

Output Arguments

rx — Receiver site

rxsite object | vector of rxsite objects

Receiver site, returned as a rxsite object or a vector of rxsite objects.

Properties

Name — Site name

character vector | string scalar | cell array of character vectors | string vector

Site name, specified as one of these options:

• A string scalar or a character vector. Use this option to create one site or to create multiple sites with the same name.

• A string vector or a cell array of character vectors. Use this option to create multiple sites and use a different name for each site. The number of names must match the number of sites.

When updating the Name property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a string scalar or a character vector, for example rx(1).Name = "Fenway Park".

Data Types: char | string | cell

CoordinateSystem — Coordinate system used to reference site location

'geographic' (default) | 'cartesian'

Coordinate system used to the reference the location of the site, specified as 'geographic' or 'cartesian'.

• 'geographic' — Geographic coordinate system. Specify the locations of the receiver sites using the Latitude, Longitude, and AntennaHeight properties.

• 'cartesian' — Cartesian coordinate system. Specify the locations of the receiver sites using the AntennaPosition property.

Data Types: char | string

Latitude — Latitude coordinates of site, in degrees

42.3021 (default) | numeric scalar in range [–90, 90] | numeric vector with elements in range [–90, 90]

Latitude coordinates of the site, in degrees, specified as one of these options:

• A numeric scalar in the range [–90, 90]. Use this option to create one site or to create multiple sites with the same latitude coordinate.

• A numeric vector with elements in the range [–90, 90]. Use this option to create multiple sites and use a different latitude coordinate for each site. The length of the vector must match the number of sites.

Latitude assumes that the coordinates use the World Geodetic System of 1984 (WGS 84) reference ellipsoid.

When updating the Latitude property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a numeric scalar, for example rx(1).Latitude = 45.098.

Dependencies

To enable this property, the value of CoordinateSystem must be 'geographic'.

Longitude — Longitude coordinates of site, in degrees

-71.3764 (default) | numeric scalar | numeric vector

Longitude coordinates of the site, in degrees, specified as one of these options:

• A numeric scalar. Use this option to create one site or to create multiple sites with the same longitude coordinate.

• A numeric vector. Use this option to create multiple sites and use a different longitude coordinate for each site. The length of the vector must match the number of sites.

Longitude assumes that the coordinates use the WGS 84 reference ellipsoid.

When updating the Longitude property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a numeric scalar, for example rx(1).Longitude = -71.0972.

Dependencies

To enable this property, the value of CoordinateSystem must be 'geographic'.

Antenna — Antenna element or array

'isotropic' (default) | antenna object | array object | vector of antenna objects | vector of array objects

Antenna element or array, specified as 'isotropic', an antenna object, an array object, a vector of antenna objects, or a vector of array objects. The rxsite object supports these antenna options:

• 'isotropic' which models an antenna that radiates uniformly in all directions.

• An antenna object from the Antenna Catalog (Antenna Toolbox) or an array object from the Array Catalog (Antenna Toolbox). To specify an antenna object, design the antenna at the required receive frequency by using the design (Antenna Toolbox) function. Then, add the antenna to the receiver site. This option requires an Antenna Toolbox™ license.

• An arrayConfig object.

• An antenna object from Antennas, Microphones, and Sonar Transducers (Phased Array System Toolbox) or an array object from Array Geometries and Analysis (Phased Array System Toolbox). This option requires a Phased Array System Toolbox™ license.

• A measuredAntenna (Antenna Toolbox) object. The E and EmbeddedE properties of the object must be empty. The Directivity property of the object must be nonempty. This option requires an Antenna Toolbox license. (since R2026a)

Specify a value for Antenna depending on the number of sites you want to create:

• To create one site or to create multiple sites with the same antenna, specify a scalar antenna or array object.

• To create multiple sites and use a different antenna for each site, specify a vector of antenna or array objects. The length of the vector must match the number of sites.

When updating the Antenna property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying an antenna or array object, for example rx(1).Antenna = arrayConfig(Size=[8 1]).

AntennaAngle — Antenna x-axis angle, in degrees

0 (default) | numeric scalar | 2-by-1 numeric vector | 2-by-N numeric matrix

Antenna x-axis angle with respect to a local Cartesian coordinate system, in degrees, specified as one of these options:

• A numeric scalar that specifies the azimuth angle. Use this option to create one site or to create multiple sites with the same azimuth angle. When you specify a scalar, the elevation angle is 0.

• A 2-by-1 numeric vector that specifies the azimuth and elevation angles of the antenna. Use this option to create one site or to create multiple sites with the same azimuth and elevation angles.

• A 2-by-N numeric matrix that specifies the azimuth and elevation angles of the antenna, where N is the number of sites. Use this option to create multiple sites and use different azimuth and elevation angles for each site.

For sites with geographic coordinates, the azimuth angle is measured counterclockwise from the east along the antenna x-axis. For sites with Cartesian coordinates, the azimuth angle is measured from the global x-axis around the global z-axis. Specify the azimuth angle in the range [–180, 180].

The elevation angle is measured from the antenna x-axis along the horizontal (or xy) plane. Specify the elevation angle in the range [–90, 90].

When updating the AntennaAngle property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a numeric scalar or a 2-by-1 numeric vector, for example rx(1).AntennaAngle = [25 -80].

AntennaHeight — Antenna height above surface, in meters

1 (default) | nonnegative scalar | vector of nonnegative values

Antenna height above the ground or building surface, in meters, specified as one of these options:

• A nonnegative scalar. Use this option to create one site or to create multiple sites with the same antenna height.

• A vector of nonnegative values. Use this option to create multiple sites and use a different antenna height for each site. The length of the vector must match the number of sites.

Antenna heights must be less than or equal to 6,371,000 m.

When the site coincides with a building, the antenna height measures from the top of the building to the center of the antenna. Otherwise, the height measures from the ground to the center of the antenna.

When updating the AntennaHeight property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a nonnegative scalar, for example rx(1).AntennaHeight = 15.

Dependencies

To enable this property, the value of CoordinateSystem must be 'geographic'.

Data Types: double

AntennaPosition — Position of antenna center, in meters

[0;0;0] (default) | three-element vector | 3-by-N matrix

Position of the antenna center, in meters, specified as one of these options:

• A three-element vector that specifies the Cartesian xyz-coordinates of the antenna center. Use this option to create one site or to create multiple sites with the same antenna position.

• A 3-by-N matrix, where N is the number of sites, and each column specifies the Cartesian xyz-coordinates of the antenna center for that site. Use this option to create multiple sites and use a different antenna position for each site.

When updating the AntennaPosition property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a 3-element vector, for example rx(1).AntennaPosition = [0; 2; 4].

Dependencies

To enable this property, the value of CoordinateSystem must be 'cartesian'.

Data Types: double

SystemLoss — System loss, in dB

0 (default) | nonnegative scalar | vector of nonnegative values

System loss, in dB, specified as one of these options:

• A nonnegative scalar. Use this option to create one site or to create multiple sites with the same system loss.

• A vector of nonnegative values. Use this option to create multiple sites and use a different system loss for each site. The size of the vector must match the number of sites.

System loss includes transmission line loss and any other miscellaneous system losses.

When updating the SystemLoss property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a nonnegative scalar, for example rx(1).SystemLoss = 10.

Data Types: double

ReceiverSensitivity — Minimum received power to detect signal, in dBm

-100 (default) | numeric scalar | numeric vector

Minimum received power to detect the signal, in dBm, specified as one of these options:

• A numeric scalar. Use this option to create one site or to create multiple sites with the same receiver sensitivity.

• A numeric vector. Use this option to create multiple sites and use a different receiver sensitivity for each site. The length of the vector must match the number of sites.

When updating the ReceiverSensitivity property after creation, if rx is a vector of sites, you must update the property of each site individually by indexing into the vector and specifying a numeric scalar, for example rx(1).ReceiverSensitivity = -80.

Data Types: double

Object Functions

show	Show site in Site Viewer
hide	Hide site from Site Viewer
distance	Distance between sites
angle	Angle between sites
elevation	Elevation of site
location	Coordinates at distance and angle from site
sigstrength	Received signal strength
los	Display or compute line-of-sight (LOS) visibility status
link	Display or compute communication link status
pattern	Display antenna radiation pattern in Site Viewer

Examples

Create Receiver Site in Geographic Coordinates

Create a receiver site. By default, receiver sites use geographic coordinates. Specify the latitude as 42.3001 degrees and the longitude as -71.3504 degrees.

rx = rxsite(Name="MathWorks Apple Hill", ...
    Latitude=42.3001,Longitude=-71.3504);

Display the receiver site.

show(rx)

Create Receiver Array Using Dipole Antenna

Specify the names, latitudes, and longitudes of three locations.

name = ["Fenway Park","Faneuil Hall","Bunker Hill Monument"];
lat = [42.3467 42.3598 42.3763];
lon = [-71.0972 -71.0545 -71.0611];

Specify the sensitivity of the receivers in dBm.

sens = -90;

Create an array of receiver sites in geographic coordinates that uses dipole antennas.

rxs = rxsite(Name=name,Latitude=lat,Longitude=lon, ...
      Antenna=dipole,ReceiverSensitivity=sens);

Display the receiver sites.

show(rxs)

Version History

Introduced in R2019b

R2026a: Specify Antenna as measuredAntenna object

Create sites from measured pattern data by specifying the Antenna property as a measuredAntenna (Antenna Toolbox) object. This capability requires an Antenna Toolbox license.

R2026a: Specify AntennaPosition, AntennaHeight, SystemLoss, and ReceiverSensitivity using additional input sizes

These name-value arguments now accept additional input sizes:

• AntennaPosition accepts a three-element row vector or a 3-by-N matrix, where N is the number of sites. In previous releases, the argument required you to specify a three-element column vector.

• AntennaHeight, SystemLoss, and ReceiverSensitivity accept column vectors. In previous releases, the arguments required you to specify scalars or row vectors.