= Radio Controller =

The radio contoller is a custom peripheral designed to utilize the many functions of the radio boards. It contains SPI logic to set the registers in the Radio and DAC chips on the boards and logic to keep track of the control pins for both of the chips. Also provided with the radio controller are drivers that enable the use of the radio controller. For the latest copy of the radio controller and its drivers refer to the [source:PlatformSupport/CustomPeripherals/ repository].

This core only has logic in it and does not connect to pins directly. It must be used in conjunction with the [wiki:HardwareUsersGuides/RadioBoard_v1.4/RadioBridge Radio Bridge] peripheral which actually provides the connections for each of the four available daughtercard slots. Select radio bridges for the locations where a WARP radio board is plugged in. Up to four radio bridges can be used in a project. 

The Radio Controller and Radio Bridge are EDK peripherals that should be available as options in Base System Builder when using the Board Description File (*.xbd) available in the repository.

== Setting up the Radio Controller Peripheral ==

The latest version of the radio controller peripheral and drivers are located in the repository. Its setup is included in the Board Description File (*.xbd) for the WARP Boards. Please refer to the [wiki:FAQ/EDK#HowdoIinstalltheWARPsupportfiles FAQ] for instructions on obtaining the peripherals and XBD file.

 1. Use the Base System Builder to set up a new project in Xilinx Platform Studio (refer to [wiki:Tutorials Tutorials] to see how to set up a project that tests the basic peripherals on the FPGA board).
 1. Check the box referring to the Radio Controller to include it.
 1. Also you will see four [wiki:HardwareUsersGuides/RadioBoard_v1.4/RadioBridge Radio Bridge] peripherals. Each of these refer to a daughtercard slot on the FPGA board. If your radio is in slot 2, check the box for Radio_Bridge_2. If you have mutliple radios you may check more than one bridge. 
''To use the Radio Controller you must have alteast one Radio Bridge included. Also setting up Radio Bridge without the Radio Controller does not provide any tools to use the radios.''

Once the project has been created you will notice a Radio Controller core in the System Assembly View.

== Using the Radio Controller Drivers ==

The Radio Controller functions are divided up into four libraries: {{{radio_controller_basic.h}}}, {{{radio_controller_ext.h}}}, {{{radio_controller_adv.h}}} and {{{radio_controller_5ghz.h}}}. To use each of the libraries in your C program, include the following line in the beginning of your code:
{{{
 #include "radio_controller_basic.h"
 #include "radio_controller_ext.h"
 ...
}}}

These are the functions that are available in each of the files:

{{{radio_controller_basic.h}}}
  This library must always be included as it has the initialization functions as well as basic functions such as transmit enable and receive enable. It also has control to change the center frequency of transmission in the 2.4GHz band.
{{{radio_controller_ext.h}}}
  This builds on the most basic functions available by allowing the user to change the transmit and receive gains, having finer control of the amplifiers and the transmit enable state machine and controlling the various transmit and recieve filters provided by the radio.
{{{radio_controller_adv.h}}}
  This has all the advanced functions for the user. The user can select whether the shutdown, transmit enable and receive enable pins are controlled by software or by hardware ports, power down chips on the board and adjust gains for the digital-to-analog converter.
{{{radio_controller_5ghz.h}}}
  Has all the functions related to using the 5 GHz ISM band that is covered by the radio.

=== Inputs to Functions ===

All the inputs are well defined in the [//WARP_API WARP APIs]. One argument to all functions is common:

 {{{radios}}}: This refers to the Radio boards that are to be affected by the function call. Each radio board can be selected by {{{RADIO1_ADDR}}} for the board in slot 1, {{{RADIO2_ADDR}}} for slot 2, etc. To call the function on multiple boards at the same time, OR (|) the values with each other. For example, {{{RADIO1_ADDR|RADIO3_ADDR}}} would affect both the radios in slot 1 and 3.

=== Initialization ===

Initialization of the Radio boards requires one function call at the beginning of time. {{{WarpRadio_v1_Reset(...)}}}, located in {{{radio_controller_basic.h}}}, must be called at the beginning of your {{{main()}}} function so that the radio and DAC can be reset into their default states. The input argument to the the Reset function is the base address of the radio controller peripheral core. The base address information of all the peripherals is located in the {{{xparameters.h}}} file. This file appears only after the hardware has been generated the first time. To access the file open the Software Application Project and expand the {{{Processor: ppc405_0}}} list. Be sure to include this file at the top of your C program as well by using the following line:
{{{
 #include "xparameters.h"
}}}
If the project has been created with the Base System Builder, generally the base address of the radio controller is XPAR_RADIO_CONTROLLER_0_BASEADDR. Be sure to check this to be certain. None of the other function calls require the base address as the drivers will remember it from the Reset function so make sure that before any other {{{WarpRadio_v1_}}} functions are used, {{{WarpRadio_v1_Reset(...)}}} has been called.

An example of this would be:
{{{
 #include "xparameters.h"
 #include "radio_controller_basic.h"
 .
 . 
 .
 int main() {
    xil_printf("---Entering Main---\r\n");
    WarpRadio_v1_Reset((unsigned int*)XPAR_RADIO_CONTROLLER_0_BASEADDR);
    .
    .
    .
 }
}}}

=== Basic Usage of Radio Functions ===

'''Transmitting Data:''' When the radio is reset and comes up in the default state, the transmit path of the radio is set to use the largest gain that is available. To allow the radio to transmit `TxEnable` from `radio_controller_basic.h` must be called. It forcibly turns off receive enable mode. At this point, data that is available on `user_DAC_I` and `user_DAC_Q` ports of the radio_bridge are transmitted over the air. To turn off transmit mode and go to standby, use `TxRxDisable(...)` again from `radio_controller_basic.h`.

'''Receiving Data:''' To receive data put the radio into receive enable mode using `RxEnable(...)` from `radio_controller_basic.h`. This function call automatically turns off the transmit mode. The data that is received will be available on `user_ADC_I` and `user_ADC_Q` ports of the radio bridge peripheral. To turn off receive mode and go to standby, use `TxRxDisable(...)` again from `radio_controller_basic.h`.

'''Selecting Center Frequency:''' Function `SetCenterFreq2GHz(...)` in `radio_controller_basic.h` can be used to set the transceiver center frequency in the 2.4 GHz  ISM band. Within this the channel number can also be selected. By default the center frequency in the 2.4 GHz band is channel number 6 which is equivalent to 2.437 GHz. See [source:/PlatformSupport/CustomPeripherals/drivers/radio_controller_v1_08_a/src/radio_controller_basic.h#L36 radio_controller_basic.h] for details on the different center frequencies available. The center frequency can also be set in the 5 GHz ISM band with `SetCenterFreq5GHz(...)` in [source:/PlatformSupport/CustomPeripherals/drivers/radio_controller_v1_08_a/src/radio_controller_5ghz.h#L24 radio_controller_5ghz.h]. 

'''Setting Transmit and Receive Gains:''' There are two methods of setting up gains for transmission and reception of data. They can either be setup using software functions or hardware ports. This difference is controlled by `SoftwareTxGainControl(...)` and `SoftwareRxGainControl(...)`. When using the software mode the receive gains are set using `RxLNAGainControl(...)` and `RxVGAGainControl(...)` while transmit gains are set by `TxVGAGainControl(...)`. When using hardware, the receive gains are set by a parallel bus `user_BB_gain` and `user_RF_gain` respectively. This is generally used where there is a separate peripheral that selects the receive gains, for example an Automatic Gain Control algorithm. All function calls are in [source:/PlatformSupport/CustomPeripherals/drivers/radio_controller_v1_08_a/src/radio_controller_ext.h#L37 radio_controller_ext.h].

'''Transmit State Machine:''' In the radio controller there is a state machine that controls outputs gains and amplifiers. This does not turn them on full immediately but instead ramps them up to desired gains at given gain steps to avoid an output power spike. This state machine also has an output signal (`TxStart`) that gets enabled once the state machine has finished executing. The state machine gets enabled when the `TxEnable(...)` function from `radio_controller_basic.h` is called. For the state machine to be activated the output transmit gain must be in hardware mode (see Setting Transmit and Receive Gains above). The parameters that can be controlled include the time to wait before starting the state machine, enabling `TxStart`, enabling amplifier and the target gains and gain ramp steps. All of these can be set up in `SetTxTiming(...)` and `SetTxGainTiming(...)` functions that are part of [source:/PlatformSupport/CustomPeripherals/drivers/radio_controller_v1_08_a/src/radio_controller_ext.h#L69 radio_controller_ext.h]. Details of the functions are available in the API below.

== Radio Controller APIs ==

All the APIs are available in the [//WARP_API WARP APIs] that cover the MAC layer and the radio controller.