View on GitHub

Chapter 7
Working with Devices

Devices in REDHAWK are generally used as proxies for hardware. As such, Devices can be used to interact with the physical world, to run a Component, or to interface with FPGAs. The following sections explain how to use Devices to interact with the physical world, to run Components, or to interface with FPGAs :

7.1 Using Devices to Interact with Hardware

REDHAWK Devices can be used to interact with hardware receivers and digitizers, for example, a data acquisition board or a USRP. To have a REDHAWK Component use a REDHAWK Device, you can establish a usesdevice relationship between a Component and a Device. The usesdevice relationship requires the Component to only use that particular type of Device. For more information on the usesdevice relationship refer to Section 11.4.8. The REDHAWK distribution includes three Devices that can be used out-of-the-box: Realtek RTL2832-based DVB dongles with Osmocom’s rtl-sdr library, Ettus’s USRP, and an FM RDS simulator with the libRfSimulators library.

The following example explains how to use the FmRdsSimulator REDHAWK Device to receive and process a generated FM signal, and provide the audio and a plot of the signal.

The RTL2832U REDHAWK Device can be substituted for the FmRdsSimulator REDHAWK Device to receive a live FM signal.

  1. Open the Python Sandbox and import the frontend module.
  2. Launch the FmRdsSimulator Device, the AmFmPmBasebandDemod Component, the fastfilter Component, the ArbitraryRateResampler Component, the SoundSink Sandbox Component, and set up the REDHAWK IDE plotter.

    To plot data, the REDHAWK IDE must be installed and the path to the Eclipse directory of the installed IDE must be specified in the Sandbox. This can be done through the IDELocation() function.

  3. Connect Devices and Components.
  4. Configure and start all Components and Devices in the Sandbox.
  5. Create a tuner allocation structure and allocate the Device.

    Set the center_frequency Property in the allocation structure to the radio station desired. Specifying a bandwidth of 0.0 indicates that any bandwidth is acceptable given that the other parameters are met.

Devices may be used within the Sandbox or within a Domain, in which case Devices are deployed by a Device Manager at startup. The lifecycles of the Devices used within the Sandbox follow the same lifecycle as the scripting environment; when the scripting environment is shutdown, the Devices are shutdown. The lifecycles of Devices deployed by a Device Manager follow the lifecycle of the Device Manager; when a Device Manager is started, the Devices associated with that Device Manager are launched, and when the Device Manager is shutdown, the associated Devices are released.

The configuration of a Device Manager’s Devices is controlled through an XML file called a Device Configuration Descriptor (DCD) file. Any one DCD file associated with a Device Manager instance is often referred to as a Node.

When a Node is deployed, the Devices associated with the Node become available to the Domain. Applications can contain usesdevice relationships. In other words, elements in the SAD XML file can declare that the Application requires the use of a particular type of Device. When the Application is deployed by the Domain, the Domain searches through the deployed Devices for any one Device that can satisfy the declared dependency. Any Device that satisfies an Application dependency may become busy and unavailable for use by other Applications. When the Application is released, the Device is brought back into the pool of available Devices.

Given the radio nature of REDHAWK, the interaction between the REDHAWK environment and Radio Frequency (RF) devices has been standardized through a common API, known as FrontEnd Interfaces (FEI).

If you have RF FrontEnd hardware that you want to model in REDHAWK, you can use the FEI module to facilitate this process. The FEI module contains interfaces designed to standardize the interaction (allocation, operation, and development) of tuner Devices within the REDHAWK Core Framework (between Applications and radio hardware). This standard breaks the tie between the Application and the hardware and provides more flexibility.

The FEI module defines a number of interfaces to enable users to interact with several different generic types of tuners, including:

For more information about tuner types, refer to Section F.2.

Before you can interact with the tuners, you must create a REDHAWK Device that is FEI compliant. The following procedure explains how to make a REDHAWK Device that is compliant with FEI version 2.2.

7.1.1 Creating an FEI Device in the IDE

The following steps explain how to create an FEI Device in the IDE.

  1. Use the FEI Wizard to create an FEI Device Project.
  2. Edit an FEI Device Project.
  3. Generate and customize the source code.
  4. Install the FEI Device.

7.1.1.1 Using the FEI Wizard to Create an FEI Device

The FEI Wizard enables users to quickly create an FEI compliant RX or TX tuner Device. In the wizard, the user specifies the physical properties of the Device, including whether the Device ingests or outputs GPS and if the Device has digital or analog input and output Ports. Additionally, the user can choose to augment the required tuner status Properties with additional optional Properties. The following procedure explains how to use the FrontEnd Interfaces Wizard.

  1. To open the FrontEnd Interfaces Wizard, select File > New > Other.

    The Select a wizard dialog is displayed (Figure 7.1).


    PIC
    Figure 7.1: Select a Wizard Dialog


  2. Select REDHAWK Front End Device Project and click Next.

    The Create a REDHAWK Device Project dialog is displayed (Figure 7.2).


    PIC
    Figure 7.2: Create a REDHAWK Device Project Dialog


  3. In the Project name field, enter a project name and click Next.

    The New Implementation dialog is displayed (Figure 7.3).


    PIC
    Figure 7.3: New Implementation Dialog


  4. Select the programming language used, the code generation template, and ID for the Device’s implementation; enter a description for this implementation; and click Next.

    The FrontEnd Interfaces Device Type Selection dialog is displayed (Figure 7.4).


    PIC
    Figure 7.4: The FrontEnd Interfaces Device Type Selection Dialog


  5. Select the appropriate aspects of the Device (needs GPS data or produces GPS data) and its general usage (receiver, transmitter, or transceiver). Click Next.

    The FrontEnd Interface Tuner Options dialog is displayed (Figure 7.5).


    PIC
    Figure 7.5: The FrontEnd Interface Tuner Options Dialog


  6. Specify the types of inputs and outputs that the Device supports (analog, digital float) and click Next.
  7. The FrontEnd Interfaces Tuner Status Customization dialog is displayed (Figure 7.6). The following options are available:


    PIC
    Figure 7.6: The FrontEnd Interfaces Tuner Status Customization Dialog


    • To add an optional tuner status Properties, click +, select the checkboxes for the Properties, and click OK.
    • To remove optional tuner status Properties, under Tuner Status Property Selection, select the Properties to remove, and click X. If a required Property is selected, the X button is disabled.
    • Click Finish to exit this wizard.

Upon exiting this wizard,the FEI Device project to is created, and the Overview tab of the project is displayed (Figure 7.7).


PIC

Figure 7.7: The FEI Device Overview tab


7.1.1.2 Editing a FrontEnd Interfaces Device Project

After completing the wizard, you can add Ports, Properties, and descriptions to an FEI Device using the same processes used for all other Components and Devices. For more information about adding Ports, refer to Section 14.4.1.1. For more information about adding Properties, refer to Section 14.4.1.2.

For example, it may be useful to add a Property used to uniquely identify the target Device, such as an IP address.

When editing a FrontEnd Device Project:

  • Do not rename Properties that were generated using the wizard.
  • Do not modify the pre-populated values generated in the wizard (for example, the Property, device_kind). You may, however, add default values to the Properties without pre-populated values, such as device_model.
  • Do not change pre-defined FEI Tuner Status Properties that were generated in the wizard. You may, however, add user-defined FEI Tuner Status Properties.
  • Before adding user-defined FEI Tuner Status Properties, check to see if relevant pre-defined FEI Tuner Status Properties are already available. Use pre-defined FEI Tuner Status Properties whenever possible.

To add or remove optional FEI Tuner Status Properties using the FrontEnd Interfaces Tuner Status Customization dialog, on the Overview tab of the project, click the Edit FrontEnd Properties icon. The same dialog used to define the FEI Device’s tuner status property on the creation wizard (Figure 7.6) is displayed. Add or remove the properties and click Finish.

7.1.1.3 Generating and Customizing the Source Code

  1. On the Overview tab for the project, click the Generate All Implementations icon to generate the source code.

    The Regenerate Files dialog is displayed (Figure 7.8).


    PIC
    Figure 7.8: The Regenerate Files Dialog


  2. Select the files to be generated and click OK.

    Files are generated that define the classes for the FEI Device. The FEI base class inherits from the FrontendTunerDevice class to provide much of the FEI capability. The generated FEI Device class must be modified or customized to interact with the target Device. During generation, intentional compiler warnings are inserted in the main class to indicate where code should be modified to reflect the behavior of the device. The output of the make command for a C++ device, including the compiler warnings, is displayed in the Console view (Figure 7.9).


    PIC
    Figure 7.9: FEI Device Compiler Warnings


    There are five functions that contain a default implementation that should be modified to match the desired behavior, each with an intentional compiler warning inserted in place of the function implementation. These functions are constructor, deviceEnable, deviceDisable, deviceSetTuning, and deviceDeleteTuning. The constructor function is called when the Device is instantiated. During allocation of an FEI Device, deviceSetTuning is called and, if successful, deviceEnable is called. During deallocation, deviceDisable is called followed by a call to deviceDeleteTuning.

  3. Add source code to allocate and setup a tuner channel.

    The following table explains what is expected in each function/method.

    Each of the following functions have fts and tuner_id passed in as parameters. The tuner_id parameter specifies which tuner channel to operate on, and fts is a reference to the FEI tuner status associated with the specified tuner channel. Additionally, deviceSetTuning has a parameter called request, which defines the parameters of the tuning request. For more information about tuner status elements, refer to Section F.6.1.




    Function/Method

    Description



    constructor

    This is the REDHAWK constructor. All properties are initialized prior to this function being invoked. The default behavior when implementing a tuner is to create 1 RX_DIGITIZER channel.



    deviceEnable

    Command the hardware to enable the output and begin generating data. The FEI tuner status element fts.enabled is updated to reflect the current state of the tuner output. This is a good place to call start to start the service function.



    deviceDisable

    Command the hardware to disable the output and stop generating data. The FEI tuner status element fts.enabled is updated to reflect the current state of the tuner output. This is a good place to call stop to start the service function.



    deviceSetTuning

    Validate that the request parameters can be satisfied by the tuner indicated by tuner_id. There are several helper functions (validateRequest, validateRequestVsSRI, validateRequestVsRFInfo, and validateRequestVsDevice) provided in the inherited FrontendTunerDevice class of the Device to assist in validation. Then, either configure the hardware with the tuner request, throw a BadParameterException if the request is outside of the capabilities of the tuner, or return false. Update the appropriate FEI tuner status elements (i.e. fts.center_frequency, fts.bandwidth, fts.sample_rate) with the actual values queried from the hardware rather than with the requested values. Push new SRI within this function. Finally, when using the multi-out capability for BulkIO Ports, it is recommended that the matchAllocationIdToStreamId function be called at this point with the stream ID and Allocation ID. Return True upon successful configuration of the tuner according to the request, or False otherwise.



    deviceDeleteTuning

    Prior to deallocateCapacity return, a pushPacket call with EOS set to True must be called, and deviceDeleteTuning is where this should occur. Also, update the appropriate FEI tuner status elements (i.e fts.center_frequency, fts.bandwidth, fts.sample_rate) if desired. Return True upon success, or False otherwise.


    Table 7.1: Functions/methods in the generated code

    In addition to the code required for allocation and deallocation, information used to identify the target Device at run-time must be added to the main class. The recommended method for dynamically identifying a target Device is through configuration of a Property. For example, configuring a Property with an IP address or some other unique identifier allows the FEI Device to identify the specific target Device.

  4. Add source code to interact with the target hardware.

    There are two key aspects to an FEI Device: 1) how many channels does it support? and 2) how does it interact with the hardware?

    In an FEI Device, the number of channels is set through the setNumChannels function. By default, this function is included in the generated code with 1 channel. Interaction with the hardware is, obviously, specific to the hardware. The nature of the hardware (i.e.: receiver, transmitter), is specified for the supported channels as the second argument in the setNumChannels function. The valid strings for this argument are: RX_DIGITIZER, TX, RX, CHANNELIZER, DDC, RX_DIGITIZER_CHANNELIZER. For more information about tuner types, refer to Section F.2. By default, setNumChannels is populated with RX_DIGITIZER, irrespective of the selections made on the FEI wizard.

    The other aspect of the interaction with harware is the interaction with the actual driver code. While this interaction is hardware-specific, there are some structures that may be useful. The loop function (serviceFunction in C++ and Java, process in Python), is iteratively after the Device is started. As part of the deviceEnable callback, calling start on the Device starts processing loop. Conversely, as part of the deviceDisable callback, calling the stop on the Device stops the processing loop.

    The tuner interface provides the ability to set parameters like center frequency and bandwith for the receiver. Any FEI compliant device may not output any data until the transients from any receiver setting change have settled to steady state. In short, all data output from an FEI compliant device must correspond to unambiguous receiver settings.

    In the service loop function, the implementation of, in the case of a receiver, reading data from the hardware and pushing it out a port would exist. Conversely, in the case of the transmitter, the service loop function would be used to retrieve data from a port and push it through the driver to the hardware.

  5. Add source code to implement FEI-related Port functions.

    If using an RFInfo Port, it may be useful to store the RFInfo packet as part of the Device because it is not stored within the Port.

7.1.1.4 Installing the FEI Device

To install the FEI Device, build the project and export it to the Target SDR. After the FEI Device is installed, you can use it in a REDHAWK system.

7.1.1.5 Test-running a Sample FEI Device

Create a new FEI project following the steps shown in Section 7.1.1.1. For the purposes of this example, select Python as the language for the Device and dataShort as the type for the digital output, otherwise select the defaults on the Wizard for all other settings. Follow steps 1 and 2 in Section 7.1.1.3.

In the deviceEnable function, add the following line:

In the deviceDisable function, add the following line:

In the process function, add the following lines:

Install the Device as shown in Section 7.1.1.4. Launch the Device as shown in Section 10.3.2.

To test-run the Device, follow these steps:

  1. In the REDHAWK Explorer tab, expand the Sandbox item.
  2. In the Sandbox item, expand the Device Manager item.

      The Devices running in the Sandbox are displayed.

  3. Right-click the Device’s output Port (probably called dataShort_out) and select Plot Port Data.
  4. Right-click the running Device and and select Allocate.

      The Tuner Allocation dialog is displayed.


    PIC
    Figure 7.10: The Tuner Allocation dialog


  5. Enter any arbitrary number in the Center Frequency, Bandwidth, and Sample Rate fields, and click Finish.

      Data is plotted on the plot.

  6. To stop the flow, right-click the Device under the Device Manager item and select Deallocate All.

      A deallocation warning message is displayed.

  7. Click Yes to confirm that you want to deallocate all.

7.1.2 Interacting with an FEI Device with the Python Package

The Python package contains helpers that simplify the allocation/deallocation of FEI tuners. For example, to allocate a tuner to receive, centered at 1 MHz with a bandwidth of 1kHz, a 10% tolerance in the requested values, and a sample rate of 2 kHz, the following functionality can be used:

where dev is a reference to the Device object and retval is True if the allocation succeeded.

To connect to an allocated tuner, use the allocation ID as the connection ID:

where comp is a reference to the Component being connected to an allocated tuner.

To deallocate the tuner, use the following call:

To allocate a listener to a specific allocated tuner, use the following call:

To allocate a listener to any tuner with a particular set of values, use the following call:

Deallocation of listeners follows the same pattern as the deallocation of tuners.

7.1.3 Using an FEI Device in a Domain

After you have created the FEI Device, it must be deployed before you can begin to use it. The following procedure explains how to deploy the FEI Device.

  1. Create a new Node or use an existing Node and add your FEI Device to the Node. For information about creating Nodes, refer to Section 9.2.5.
  2. Launch the Node (also known as a Device Manager) onto a running Domain.

    The Node is displayed in the REDHAWK Explorer View.

  3. From the REDHAWK Explorer View, expand the Node and navigate to your Device.

    The available tuners are displayed with a Tuning fork icon within a folder under your Device (Figure 7.11).


    PIC
    Figure 7.11: Available FEI Tuners


7.1.3.1 Allocating a FrontEnd Tuner

The usage status of a FrontEnd Tuner Device is IDLE until a successful allocation has been made. Allocation is the process where a specific tuner is requested for use, and initial setup of the tuner is performed. When at least one channel has been allocated, but there is one channel not allocated, the Device is ACTIVE. If all channels have been allocated, the Device is BUSY.

The following procedure explains how to allocate a FrontEnd tuner using the Tuner Allocation dialog.

  1. Right-click the FrontEnd Tuners folder and select Allocate (Figure 7.12).


    PIC
    Figure 7.12: Allocating an FEI Tuner


    The Tuner Allocation dialog is displayed (Figure 7.13). In this dialog, you specify the desired tuner Properties such as frequency, bandwidth, and so forth.


    PIC
    Figure 7.13: The Tuner Allocation dialog


  2. In the Allocation drop-down box, verify Control New Tuner is selected.
  3. Optionally, in the New Allocation ID field, modify the text if needed.
  4. In Tuner Type, select the appropriate tuner type. You have the following options:
    • RX_DIGITIZER
    • CHANNELIZER
    • DDC
    • RX
    • RX_DIGITIZER_CHANNELIZER
    • TX

    For more information about tuner types, refer to Section F.2.

  5. In Center Frequency (MHz), specify the center frequency.

    Bandwidth and sample rate must be specified during allocation. For an allocation to be successful, the tuner must be able to provide a value that is greater than or equal to the requested value without exceeding the appropriate tolerance value specified. Requesting a bandwidth or sample rate of zero (0.0) indicates to the tuner that any value is acceptable and that the tolerance values can be ignored. Requesting 0 typically results in the lowest value the tuner is capable of providing while still satisfying the remainder of the allocation request. If the Any Value checkbox is selected, a value of 0 is requested.

  6. In Bandwidth (MHz), specify the bandwidth, or if a specific bandwidth is not required, select the Any Value checkbox.
  7. In Sample Rate (Msps), specify the sample rate, or if a specific sample rate is not required, select the Any Value checkbox.
  8. Optionally, in Bandwidth Tolerance (%), enter the bandwidth tolerance. For more information about Bandwidth Tolerance, refer to Section F.6.1.2.
  9. Optionally, in Sample Rate Tolerance (%), enter the sample rate tolerance. For more information about Sample Rate Tolerance, refer to Section F.6.1.2.
  10. Optionally, in RF Flow ID, enter the tag for the analog feed for which you are looking. For more information about RF Flow ID, refer to Section F.6.1.1.
  11. Click Finish.

    The tuner is allocated and is displayed under the FrontEnd Tuners folder with the truncated Allocation ID and an active tuning fork icon (Figure 7.14). If you left-click or hover over the allocated tuner, the full Allocation ID is displayed. A successful allocation tunes the hardware to the requested frequency and establishes a BulkIO data stream containing the content. In the case of a multi-out BulkIO Port, the data stream will only be pushed over a connection with a Connection ID that is identical to the Allocation ID associated with the data stream. In cases where the BulkIO Port is not a multi-out Port, all data streams are pushed over all connections, regardless of Connection ID.


    PIC
    Figure 7.14: Allocated Tuner


7.1.3.2 Deallocating a Tuner

If a tuner was previously allocated, it can be deallocated. To deallocate a tuner, right-click the allocated FrontEnd tuner and select Deallocate. The tuner is deallocated and displays an inactive tuning fork icon along with a status of Unallocated.

7.1.3.3 Attaching a Listener to a Tuned Receiver

Sometimes, it is necessary for multiple different applications to share a single FEI source. To support this concept, FEI includes both allocation owners and listeners. The allocations that have been discussed so far are owners; they maintain complete control over the allocated hardware. Listeners, on the other hand, allow for an arbitrary number of applications to receive the same data that the allocation owner receives. However, listeners have no control over the source. Listener allocations can be made against a particular allocation (through the allocation id) or by parameters (i.e.: center frequency).

To allocate a listener, right-click the allocated FrontEnd tuner and select Add Listener. The Listener Allocation dialog is displayed (Figure 7.15).


PIC

Figure 7.15: The Listener Allocation dialog


It is possible to specify an allocation id for the listener, but that is strictly optional. Click Finish to exit the wizard and allocate the listener. When the process is complete, the listener is associate with the receiver, and is displayed under the appropriate FrontEnd tuner.

7.1.3.4 Metadata from the Tuner Device

An FEI Device provides metadata along with its data stream. This metadata is attached to the SRI’s keywords passed along BulkIO. A total of 5 SRI elements have been defined, and they are described in Table 7.2.





Identifier

Value

Type




COL_RF

The center frequency (in Hz) for the receiver that was used to receive the data.

double




CHAN_RF

The center frequency (in Hz) for the tuned receiver.

double




FRONTEND::RF_FLOW_ID

The identifier for the stream (usually the antenna), if available.

string




FRONTEND::BANDWIDTH

The bandwidth (in Hz) for the tuned signal.

double




FRONTEND::DEVICE_ID

The identifier for the Device acquiring the data.

string


Table 7.2: FEI Data Passed as SRI

7.1.3.5 Deallocating a Listener

If a listener was previously allocated, you can deallocate it. To deallocate a listener, right-click the allocated listener and select Deallocate.

7.1.3.6 Controlling a Tuned Receiver

FEI Devices can be controlled using a FrontEnd Tuner Port. The Port provides an interface to modify parameters such as center frequency, bandwidth, gain, and sample rate.

This tuner interface provides the ability to set parameters like center frequency and bandwith for the receiver. Any FEI compliant device may not output any data until the transients from any receiver setting change have settled to steady state. In short, all data output from an FEI compliant device must correspond to unambiguous receiver settings.

There is a custom view under each tuned receiver that sends commands over the control port. This custom view is mapped to the Properties view. Note that this is not a Device property, but instead it is the use of the Property view as the artifact for interacting with the port.

The following procedure explains how to control an allocated tuner.

  1. Select the allocated tuner.
  2. Select the Properties tab if available. Otherwise, from the top IDE Menu, select Window > Show View > Properties.


    PIC
    Figure 7.16: Properties View of an allocated tuner


  3. Select the entry, or entries, to change from this view.
  4. Press Enter to have the change take affect or Esc to cancel.

Even though it is the Property view, the Tuner Port is exercised to effect the requested changes. If successful, the view updates and displays the new value.

7.1.3.7 Plotting a Tuned Receiver

The process described in Section 17.4 only applies to a single-channel system. In multi-channel Devices, a single Port is used to send out all the data, so additional structures are used to identify which channel to plot.

  1. To plot an FEI device, right-click the allocated FrontEnd tuner and select Plot Port Data, or any other Plot Port option. (Figure 7.17).


    PIC
    Figure 7.17: Plotting an Allocated Tuner


  2. If the FrontEnd tuner has multiple BulkIO Ports, the Ambiguous Data Port dialog is displayed. Select the Port to plot.

    For more information about interacting with the plots, refer to Section 14.4.6.

7.1.3.8 Plotting a Tuned Receiver with Multiple Channels

In multi-channel Devices, all data is pushed out of a single Port. To disambiguate the traffic, additional structures are used. When a Device or Component contains both a BulkIO output Port and the well-defined Property connectionTable, different data streams can be directed out of different connections on the Port. When the multi-out selection is checked on the output selection of the FEI wizard, the connectionTable Property is automatically added to the FEI Device.

Declare the association between a connection ID, a stream ID, and a Port name:

Send data with the stream id associated with a particular allocation:

While this example is in C++, this functionality is also supported in Python and Java. Unfortunately, the allocation_csv element of the frontend_tuner_status structure pre-dates the availability of sequences as elements in structures (added in REDHAWK 2.0), so it is a comma-separated value whose first value is the owner allocation.

connectionTable is a readonly property, so software running outside the scope of the Device can inspect but not change these associations.

The state of the connectionTable is managed by the FEI base classes. The Device developer must set up the state of connectionTable when a new tuner is added. However, when a listener is added to a tuner that is already on the connectionTable, the listener entry is managed automatically.

When plotting an allocated tuner on a multi-channel Device, the IDE automatically creates a listener allocation so that the correct stream is routed to the plot.

7.2 Associating a Waveform with an FEI Device

Two processes can be used to associate a Waveform with an FEI Device:

The benefit of creating a usesdevice relationship artifact is that the deployment of the Waveform can be tied to the availability of hardware resources. If the usesdevice relationship relationship cannot be established at deployment time, then the Waveform deployment will fail. Also, when the Waveform is torn down, the allocation created for this deployment is undone automatically.

To create a usesdevice relationship artifact on the Waveform:

  1. Create a Waveform, as described in Chapter 6.
  2. Find and place the usesdevice relationship artifact, which is located under the Advanced tab (Figure 7.18).


    PIC
    Figure 7.18: Use FrontEnd Tuner Device artifact


    When the artifact is dragged onto the canvas, a menu of target Devices is shown (Figure 7.19). The Devices shown are the result of a scan of $SDRROOT.

  3. Either select the desired Device or select the Generic FrontEnd Device, which does not have any Ports (so a connection cannot be defined), but it allows an allocation to be associated with the deployment.


    PIC
    Figure 7.19: Select Target Device


    After selecting a Device, a series of wizards are displayed. In the wizards, define the usesdevice relationship id to use and the parameters for the allocation itself.

    The usesdevice relationship id is the identifier used in the Waveform description to reference the usesdevice relationship artifact. It is an architectural detail that is not relevant to the developer, so use the default value given.

  4. If the Device has Ports, connect them to the appropriate Component, as seen in Figure 7.20.


    PIC
    Figure 7.20: Create a connection between the FEI Device and a Component


7.3 Using Devices to Run Components

The Sandbox runs Components without needing a Device proxy; it forks the Component process and manages its lifecycle. When running in a Domain, however, the deployment of Components in an Application requires the Domain to search for available host computers that can run the Components in the Application. The search requires each host computer to have a program that can publicize the host computer’s capabilities (For example, operating system, processor type, or available memory). This proxy is referred to as an Executable Device. REDHAWK includes a default Executable Device, the General Purpose Processor (GPP), which is automatically configured by the create_node.py script whenever a new Node is installed on the host computer. GPP is written in C++ and can serve any Node that supports x86 32/64-bit architecture. In cases where a more specialized proxy is required, REDHAWK includes base classes that can be extended in Python or C++. However, a detailed discussion of this process is beyond the scope of this document.

7.4 Using Devices to Interface with FPGAs

Many SDR systems depend on custom hardware solutions implemented on FPGAs and GPUs. REDHAWK has developed a design pattern to interface with these custom hardware solutions that enables users and the REDHAWK Framework alike to change the behavior of an FPGA at run-time to meet the needs of the Application. For more information about this design pattern, known as the Persona Pattern, refer to Appendix G.

7.5 Functions and Data Structures Provided by the
FrontEnd Interfaces Library and Code Generators




Function/Data Structure

Description



setNumChannels

Used to size various FrontendTunerDevice class data structures.



frontend_tuner_status

This is the FrontEnd tuner status Property, which is a vector of structs. The indices match the tuner_id or index of the tuner used by the FrontEnd Tuner Device. The developer is responsible for maintaining all fields with the sole exception of the allocation_id_csv, which is managed internally by the FrontendTunerDevice class.



getControlAllocationId

Returns the control Allocation ID for the tuner specified, or an empty string if not allocated.



getTunerMapping

Returns the tuner ID or tuner index of the tuner associated with the Allocation ID, or -1 if the Allocation ID is not associated with any tuner.



create

Returns a StreamSRI object constructed using the frontend_tuner_status for a tuner, including the required SRI keywords. Only required FrontEnd tuner status fields are used in constructing the StreamSRI, and any additional information that affects StreamSRI must be manually modified. In the case of DDC tuners, there is an optional parameter accepted by create for specifying the collector frequency since this information cannot be gathered from the frontend_tuner_status struct.



printSRI

Used for debug purposes to print the values of a StreamSRI object to stdout.



addModifyKeyword

Used to add a keyword to a StreamSRI object, or modify an existing keyword.



uuidGenerator

Used to generate a new Universally Unique Identifier (UUID) string.



floatingPointCompare

Used to handle potential errors introduced by floating-point math. Default precision is to the tenths place, and there is an optional parameter that can be used to specify a different precision.



matchAllocationIdToStreamId

Only available when multi-out Ports are specified. Multi-out capability of a BulkIO Port only pushes stream data with a particular Stream ID to connections that have a connection ID that matches the Allocation ID. It is recommended that this function be called in deviceSetTuning.



validateRequest

Used to verify that a value falls within the specified range. This function is overloaded to accept a range as well, to verify that it falls within a second range.



validateRequestVsSRI

Used to check that the input data stream can support the allocation request. The output mode (True if complex output) is used when determining the necessary sample rate required to satisfy the request. The entire frequency band of the request must be available for True to be returned, not just the center frequency. True is returned upon success, otherwise FRONTEND::BadParameterException is thrown. If the CHAN_RF and FRONTEND::BANDWIDTH keywords are not found in the SRI, FRONTEND::BadParameterException is thrown.



validateRequestVsRFInfo

Used to check that the analog capabilities can support the allocation request. The mode (True if complex) is used when determining the necessary sample rate required to satisfy the request. The entire frequency band of the request must be available for True to be returned, not just the center frequency. True is returned upon success, otherwise FRONTEND::BadParameterException is thrown.



validateRequestVsDevice

Used to check that the input data stream and the Device can support an allocation request. The mode (True if complex output) is used when determining the necessary sample rate required to satisfy the request. The entire frequency band of the request must be available for True to be returned, not just the center frequency. True is returned upon success, otherwise FRONTEND::BadParameterException is thrown. This function is overloaded to accept RFInfoPkt for an analog input data stream, and StreamSRI for a digital input data stream. For StreamSRI, if the CHAN_RF and FRONTEND::BANDWIDTH keywords are not found in the SRI, FRONTEND::BadParameterException is thrown.


Table 7.3: Functions and data structures provided by FEI library

7.6 Miscellaneous FrontEnd Tuner Library Implementation Details


Creative Commons License
REDHAWK Documentation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.