[[Include(WikiToC)]]

=== RF Control

This service is used to configure the RF front ends of the nodes. The functionality follows the descriptions and details on the [wiki:Hardware/rf-front-end RF front end] page (eg. setting the filters for one TX chain applies the setting to both TX chains of the node).

'''NOTE:''' Where node names are required, please use the fully qualified domain name (FQDN) of the node (eg. `sdr1-s1-lg1.bed.cosmos-lab.org`).

=== Usage

All the available methods are accessible from the a testbed console via an HTTP API located at `am1.cosmos-lab.org:5054/rf_control`. This API can be interacted with via a command line tool such as "curl" or any script using a "REST client" library.

=== Get the current configuration ===

This API call is used to get the current configuration of the RF front end(s) with respect to a node or list of nodes. The response will specify the parameters of the TX chain for the node(s) in question. It will show for a given node's `rf_port`, what `antenna` would be used if it were `connected`, whether the power amplifier (`power_amp`) is on or off, and the lower frequency (`f_lower`) and upper frequency (`f_upper`) of the filters.

HTTP API Path: `am1.cosmos-lab.org:5054/rf_control/get_tx_path`

Parameters:
 ||= '''Name''' =||= '''Decription''' =||= '''Required''' =||= '''Acceptable Input''' =||
 ||  node  ||  Comma separated list of node FQDNs  ||  Y  ||  (list of nodes)  ||

==== Example 1 ====
HTTP Request:
{{{
am1.cosmos-lab.org:5054/rf_control/get_tx_path?node=sdr1-s1-lg1.bed.cosmos-lab.org
}}}

Response:
{{{
<response status="OK">
  <nodes>
    <node name="sdr1-s1-lg1.bed.cosmos-lab.org">
      <rf_port number="0" antenna="1" connected="true" power_amp="ON" f_lower="4900" f_upper="6200"/>
      <rf_port number="1" antenna="3" connected="true" power_amp="ON" f_lower="4900" f_upper="6200"/>
      <rf_port number="2" antenna="" connected="false"/>
      <rf_port number="3" antenna="" connected="false"/>
    </node>
  </nodes>
</response>
}}}

In this example, node `sdr1-s1-lg1.bed.cosmos-lab.org` has:
* TX of rf_port 0, connected to antenna 1, its power amplifier is on, and the filters are set to 4900-6200MHz
* TX of rf_port 1, connected to antenna 3, its power amplifier is on, and the filters are set to 4900-6200MHz
* TX of rf_port 2 is not connected to anything
* TX of rf_port 3 is not connected to anything

==== Example 2 ====

HTTP Request:
{{{
am1.cosmos-lab.org:5054/rf_control/get_tx_path?node=sdr1-s1-lg1.bed.cosmos-lab.org,sdr2-s1-lg1.bed.cosmos-lab.org
}}}

Response:
{{{
<response status="OK">
  <nodes>
    <node name="sdr1-s1-lg1.bed.cosmos-lab.org">
      <rf_port number="0" antenna="1" connected="false" power_amp="OFF" f_lower="4900" f_upper="6200"/>
      <rf_port number="1" antenna="3" connected="false" power_amp="OFF" f_lower="4900" f_upper="6200"/>
      <rf_port number="2" antenna="" connected="false"/>
      <rf_port number="3" antenna="" connected="false"/>
    </node>
    <node name="sdr2-s1-lg1.bed.cosmos-lab.org">
      <rf_port number="0" antenna="1" connected="true" power_amp="OFF" f_lower="4900" f_upper="6200"/>
      <rf_port number="1" antenna="3" connected="true" power_amp="OFF" f_lower="4900" f_upper="6200"/>
    </node>
  </nodes>
</response>
 }}}

=== Turn off power amplifiers ===

This API call is simply a shorthand to easily turn off the power amplifiers for a given node. Keep in mind that power amplifier state is shared between nodes in the same physical location (eg. sdr1-md1.bed.cosmos-lab.org and sdr2-md1.bed.cosmos-lab.org).

HTTP API Path: `am1.cosmos-lab.org:5054/rf_control/power_amp_off`

Parameters:
 ||= '''Name''' =||= '''Decription''' =||= '''Required''' =||= '''Acceptable Input''' =||
 ||  node  || Comma separated list of node FQDNs ||  Y  ||  list of node names  ||

==== Example 1 ====

Turn off the power amplifier for `sdr1-s1-lg1.bed.cosmos-lab.org`.

HTTP Request:
{{{
am1.cosmos-lab.org:5054/rf_control/power_amp_off?node=sdr1-s1-lg1.bed.cosmos-lab.org
}}}

Response:
{{{
<response status="OK">
  <message>OK</message>
</response>
}}}

=== Configure the TX chain ===

HTTP API Path: `am1.cosmos-lab.org:5054/rf_control/set_tx_path`

Parameters:
 ||= '''Name''' =||= '''Decription''' =||= '''Required''' =||= '''Acceptable Input''' =||
 ||  node  ||  Comma separated list of node FQDNs  ||  Y  ||  (list of node names)  ||
 ||  rf_port  ||  Node RF port to configure  ||  Y  ||  0, 1  ||
 ||  power_amp  ||  Power amplifier state  ||  N  ||  on, off  ||
 ||  f_center  ||  Center frequency of range requested  ||  *  ||  (frequency in MHz)  ||
 ||  f_bandwidth  ||  Bandwidth of frequency range requested  ||  *  ||  (frequency in MHz)  ||
 ||  f_lower  ||  Lower end of frequency range requested  ||  *  ||  (frequency in MHz)  ||
 ||  f_upper  ||  Upper end of frequency range requested  ||  *  ||  (frequency in MHz)  ||

 '''*''' The filter frequency selection parameters are not required if all are committed. However, to select a frequency range, at least two are required using the following format.

 ||= '''1st Parameter''' =||= '''2nd Parameter''' =||= '''Effective Frequency Range''' =||
 ||  f_center  ||  f_bandwidth  ||  (f_center - f_bandwidth/2) to (f_center + f_bandwidth/2)  ||
 ||  f_upper  ||  f_lower  ||  (f_lower) to (f_upper)  ||
 ||  f_lower  ||  f_bandwidth  ||  (f_lower) to (f_lower + bandwidth)  ||
 ||  f_upper  ||  f_bandwidth  ||  (f_upper - bandwidth) to (f_upper)  ||

The allowed transmit frequency bands are detailed on the [wiki:PoliciesCompliance#OutdoorRadioFrequencyAllocation] page.

==== Example 1 ====

For `sdr1-s1-lg1` in `bed` testbed, connect TX RF ports 0 and 1 to their respective antennas, turn on the power amplifier, and request a frequency of 2.4-2.5 GHz.

HTTP Request:
{{{
am1.cosmos-lab.org:5054/rf_control/set_tx_path?node=sdr1-s1-lg1.bed.cosmos-lab.org&rf_port=0,1&power_amp=on&f_lower=2400&f_upper=2500
}}}

Response:
{{{
<response status="OK">
  <message>OK</message>
</response>
}}}