Appendix F
FrontEnd Interfaces
F.1 Introduction
FrontEnd Interfaces is a module containing interfaces designed to standardize the interaction between Applications and radio hardware. This appendix specifies the requirements of an FEI 2.0 compatible Device, explains best-practices, provides advice for development, and provides Device structures. This appendix is not intended to be an API reference for FEI or an exhaustive description of the IDLs. This appendix is intended to provide an additional resource for developers.
F.1.1 Theory of Operations
FEI were developed to standardize the allocation, operation, and development of tuner Devices within the REDHAWK Core Framework. Tuner Devices in this context may consist of RF, IF, or purely digital tuning equipment or software. Explicit types for tuners have been defined in Section F.2, so that Devices can be easily categorized by the capabilities they provide.
Tuner Devices can provide individual tuners to other REDHAWK entities through tuner allocation. To allocate an individual tuner, the allocateCapacity() function of a Device is called with an appropriate allocation structure as the only argument. Devices then allocate physical resources and, once a valid connection has been made, begin flowing data out of the Device.
F.1.2 FEI Terminology
The common terminology used for FEI is described in Table F.1.
|
F.1.3 Required Properties
The required properties for an FEI Tuner Device are listed in Table F.2.
|
F.2 Types of Tuners
Tuner types are defined so that Device developers and users can categorize the basic behavior of disparate hardware. Behavior of each of these types is described below and must be adhered to during development to allow for interoperability between different hardware baselines.
Physical devices often need to be split into multiple logical REDHAWK tuners to fully describe their functionality. Splitting physical devices often involves multiple tuners of the same, or mixed, types. Common pairings are described in each of the type descriptions.
F.2.1 RX Tuner
A simple receiver, or RX tuner, is an RF to IF conversion only. This conversion implies an analog to analog translation, typically down-converting an RF signal to a new IF. Devices often have multiple RX Devices corresponding to each of the independent analog channels provided. Single channels that have selectable RF input Ports should be represented as a single RX tuner and utilize an RF Flow ID to select between the input options. For more information about RF Flow IDs, refer to Section F.3.1.4.
RX Devices have an analog output Port. RX Devices that output digital-IF (SDDS, VITA-49, etc.) are considered RX_DIGITIZERS, which are a distinct tuner type and should be classified as such.
F.2.2 RX_DIGITIZER Tuner
An RX_DIGITIZER tuner is an RX Device that also samples the analog data and provides it as a digitized stream. The stream can be either real samples (typically referred to as digital-IF) or complex baseband data. Multiple RX_DIGITIZER channels in a singular physical device should be treated like RX Devices, including using the RF Flow ID to differentiate between which external RF source to use.
RX_DIGITIZER tuners can also optionally provide access to the analog-IF output. If the Device in question provides access to the analog-IF output, an additional analog output Port should be added to the Device. Users can optionally connect to and use that Port, although the existence of the Port is not guaranteed for all RX_DIGITIZER tuners.
F.2.3 CHANNELIZER Tuner
A CHANNELIZER tuner takes a digital wideband input and provides tuned, filtered, and decimated narrowband output. A CHANNELIZER Device acts as a token to allocate and control the wideband input, which then can have individual narrowband channels allocated as well. Each of these narrowband tuners is its own tuner of type DDC.
Allocating a CHANNELIZER establishes control over the input to a CHANNELIZER and allows users to understand that they have the ability to attach a new stream to the wideband input. Typical operation is to allocate a CHANNELIZER to gain control over the input prior to connecting a data stream to the input, though the order is not mandatory.
Allocating a DDC provides the tuned, filtered, and decimated narrowband output. A DDC is allocated by calling allocateCapacity() with the tuner type set to DDC and also specifying the frequency, bandwidth, sample rate, and any other desired aspects of the resulting DDC. Optionally, the RF Flow ID is used during allocation to specify the wideband input connection and CHANNELIZER desired. Allocation of a DDC succeeds only if the information specified during allocation can be supported by an allocated CHANNELIZER with a successful matching input connection. Changing the CHANNELIZER input can cause attached DDC tuners to be dropped.
F.2.4 DDC Tuner
DDC tuners provide a narrowband output from an existing channelizer capability. These narrowband channels are typically selectable in terms of the center frequency and bandwidth/sample rate within the constraints of the wideband input to the channelizer.
Allocating a DDC tuner against a Device with multiple CHANNELIZER (or RX_DIGITIZER_CHANNELIZER) tuners can specify which tuner to use in two different ways. One method is to specify an RF Flow ID of the specific CHANNELIZER to be allocated against. The other method is to allow the Device to match by using the requested center frequency and/or bandwidth/sample rate. The Device matches the DDC to the first channelizer capability that meets those criteria.
F.2.5 RX_DIGITIZER_CHANNELIZER Tuner
The RX_DIGITIZER_CHANNELIZER tuner is a combination of an RX_DIGITIZER and CHANNELIZER capability into a single tuner type. Input is through an analog-RF input port, and output is through DDC tuners.
RX_DIGITIZER_CHANNELIZER tuners have the optional ability to output both analog-IF as well as digital-IF data. The analog-IF Ports are represented just like the output of an RX or RX_DIGITIZER tuner. The digital-IF data is accessed by allocating a listener to the RX_DIGITIZER_CHANNELIZER, which then starts flowing digital data just like an RX_DIGITIZER.
F.2.6 TX Tuner
Although the exact functionality of the TX tuner is not yet defined, it is reserved for transmitter Devices.
F.3 Allocation
Allocation is the process where specific tuners are requested for use, and initial setup of the tuner is performed. Allocation of FrontEnd Devices always occurs by calling allocateCapacity() on the Device with the argument of the allocateCapacity() call being a FrontEnd allocation Property.
F.3.1 ID
A number of different IDs are used in REDHAWK and FEI Devices. The most important types of IDs are described in this section.
F.3.1.1 Allocation ID
The Allocation ID is a string used as an unique ID for each allocated FEI tuner. The Allocation ID is passed in as part of the allocateCapacity() call and is used as identification for all subsequent interaction. Allocation IDs are used to identify tuners in the FEI Status structure and in the TunerControl IDL.
Allocation IDs can be any unique string, but typically UUID values are used. If human readable Allocation IDs are required, the preferred approach is to append the UUID onto a base human-readable string. With this approach, allocations for non-coordinated Devices are not likely to create identical allocations.
F.3.1.2 Stream ID
In all REDHAWK BulkIO Ports, Stream ID is used to separate unique data streams that are passed in a single BulkIO Port. This methodology is also utilized in FEI Devices to allow Devices to pass the output of multiple tuners through a single BulkIO Port. REDHAWK does not mandate any uniqueness requirements on Stream IDs, but it is recommended that developers attempt to make the Stream IDs unique by appending an UUID.
Stream IDs can only be changed after an EOS is sent, and in FEI Devices, an EOS is only sent when deallocating or disabling the tuner.
F.3.1.3 Connection ID
In all REDHAWK BulkIO connections, there is a specific string ID for the connection. For FEI Devices, the connection to the output Port of the Device must have a Connection ID that is equal to the Allocation ID of the tuner to be accessed. Because the Connection ID is equal to the Allocation ID, the output Port can be constructed as a multi-out Port, which is described in more detail in Section F.5.1. For information on how to assign a custom Connection ID, refer to Section 14.10.
F.3.1.4 RF Flow ID
RF Flow IDs are used to differentiate between RF input streams, similarly to how Stream IDs are used to differentiate between BulkIO streams. For FrontEnd Devices, these RF Flow IDs are used to match allocation requests to specific RF sources.
Unlike Allocation IDs and Stream IDs, RF Flow IDs are often human readable. Typically, they describe specific inputs to a Device or feed names. RF Flow IDs for a Device can be set as a Device Property, which is set as part of the Node configuration. System developers can create a Node that sets the individual FrontEnd Device with the RF Flow IDs that are appropriately set to the current state of the physical RF connections.
F.3.1.5 Device Group ID
Device Group ID is similar to RF Flow ID in that it is used as an additional ID to allow allocations against a specific pool of Devices. In this case, each FEI Device can have its Group ID set, and individual allocations can request specific Group IDs. Devices with the same Group ID are considered to be in the same group, and only Devices that are part of that group allow those allocations. Group IDs are strings that are often human readable. A Device typically has its Group IDs set as a Property, so it can be configured as part of a Node.
F.3.2 Tuner Allocation Overview
FrontEnd tuners are allocated by calling the Device’s allocateCapacity() method with a particular FrontEnd Allocation structure. The call acts as a request to the Device for allocation of a tuner that meets the specifications in that structure. If the request is able to be met by that Device, then the tuner is allocated, and True is returned by the allocateCapacity() call. If the tuner cannot be allocated, then an appropriate exception is thrown. Returns and exceptions are shown in Table F.3.
Two different FrontEnd Allocation structures can be used. The Tuner Allocation structure is primarily used for allocating new tuners of an FEI Device. The Listener Allocation structure is used for allocating listener tuners that piggyback on existing control tuners. Listener tuners are logical tuners that simply mirror the output of existing control tuners. Therefore, FrontEnd Devices can keep track of how many consumers are attached to each of the tuner outputs and handle requests appropriately. The Tuner Allocation structure is described in Section F.3.3, and the Listener Allocation structure is described in Section F.3.4.
F.3.2.1 Allocation Return Types
The values returned, and exceptions thrown, by the allocateCapacity() call are described in Table F.3.
|
F.3.3 Tuner Allocation Properties
Each allocateCapacity() call passes in a single FrontEnd Tuner Allocation structure. If multiple tuners are allocated, each tuner needs an independent allocateCapacity() call. Each field in the allocation structure needs to be matched against the available tuners in the Device. Each field must correctly match for the allocation to be successful. If any of the properties cannot be met, the allocation throws an exception.
Table F.4 describes the tuner properties and how to handle requests.
|
After successfully matching the allocation properties, the FrontEnd Device needs to perform a number of tasks prior to returning from the allocateCapacity() call. First, the actual hardware or software should then be allocated with the values requested. Then, the internal status Properties need to be updated to show the new channel. More information about the status Properties can be found in Section F.6.1. Once the status is set, the allocateCapacity() call can return.
After a successful allocation, the tuner is enabled and data is flowing though the Device and out the output Port. It is not required that the allocateCapacity() call return prior to the first data packet being pushed through the Device.
F.3.4 Listener Allocation Properties
There are two methods used to perform listener allocations. The first method is to use a standard FrontEnd Allocation Structure as shown in Section F.3.3 with the control Property set to False. Setting the control Property to False causes the Device to look for existing tuners that meet the required Properties in the rest of the FrontEnd Allocation Structure and assign a new listener tuner to that master tuner. If no tuners already exist, the request fails.
The second way of allocating a listener tuner is by using a FrontEnd Listener Allocation structure in the allocateCapacity() call. Passing in this FrontEnd Listener Allocation structure causes the Device to create a new listener tuner that is attached to the tuner with the Allocation ID given in the structure. The FrontEnd Listener Allocation structure is described fully in Table F.12.
|
The requirements for tuner setup of a listener tuner are the same as those for a control tuner. The status structure must be updated, and the output must be enabled. These actions are expected to be performed prior to returning from allocateCapacity().
F.3.5 Tuner Deallocation
Tuners are deallocated using the deallocateCapacity() call. There is no return from the deallocateCapacity() function, but exceptions are thrown if deallocation is unsuccessful. The only exceptions that can be thrown are InvalidCapacity, which indicates that the Allocation ID provided is not valid, or InvalidState, indicating the Device is in an error state.
The deallocateCapacity() call can accept either a Tuner Allocation or a Listener Allocation structure as only the Allocation ID field is utilized. All other fields are ignored and have no impact on the deallocation. The concept is that the same allocation structure provided to allocateCapacity() can be sent to deallocateCapacity() to remove the tuner.
Tuners that are deallocated need to have their status entries removed, the underlying hardware/software disabled, and all output stopped. A final BulkIO packet containing an EOS SRI flag is sent prior to the return from the deallocateCapacity() call. More information on the BulkIO SRI information can be found in Section F.5.2. No more data from that tuner flows though the BulkIO Port.
F.3.5.1 Automatic Listener Deallocation
When a control tuner is deallocated, its attached listeners are expected to also be deallocated. Therefore, both status cleanup and EOS information flows over the BulkIO Port.
F.4 Command and Control
Command and Control of existing allocated tuners is performed through the Digital or Analog Tuner Port on the FEI Device. These commands allow external users to get and set specific settings for each of the tuners. Each FrontEnd Tuner Device must have a DigitalTuner Port named DigitalTuner_in (or AnalogTuner_in for an AnalogTuner Port) that allows for command and control. All of the functions in the Tuner Control IDL need to be implemented even if only to report that the capability is not supported. Each of these IDL functions uses the Allocation ID to uniquely identify the tuners.
F.4.1 Tuner Control IDL
The tuner control IDL describes two interfaces for control. The first is the AnalogTuner, which describes all of the functions common for Digital and Analog tuners. DigitalTuner inherits from AnalogTuner and adds setOutputSampleRate() / getOutputSampleRate() functionality. The functions and potential exceptions are described in the following tables.
F.4.1.1 Tuner Control Functions
Table F.6 describes the functions that can be accessed via the Tuner Control IDL.
|
F.4.1.2 Tuner Control Exceptions
Table F.7 describes the exceptions that can be thrown from the tuner control functions.
|
F.5 Data Flow
By default, FEI Devices can provide BulkIO data. Data flow into FEI Devices is typically constrained to digital-IF data for CHANNELIZER tuners. Digital-IF data is consumed regardless of Stream ID and it is the responsibility of the CHANNELIZER allocator to make the connection from the source into the FrontEnd Device.
Output data flow is managed by the FEI Device and multiple tuners can have output through a single BulkIO Port. In general, there should only be one BulkIO Port for each data type (int, float, etc.). All streams of any data type must pass through this BulkIO Port. The allocator of each tuner is responsible for connecting to the Device output Port. The Connection ID of the BulkIO connection must match the Allocation ID of the tuner for data to flow through that connection. Thus, the output Port must be a multi-out Port, one that only passes data packets to specific connections rather than all connections.
F.5.1 Multi-Output
Multi-out Ports are a specific implementation of a BulkIO output Port. The defining characteristic is that multi-out Ports are selective in which connection each piece of data is sent to rather than having each piece of data broadcast to every connection. This behavior is typically implemented by creating a custom BulkIO Port implementation that handles data routing for each connection.
Constructing the custom Port is easiest if the internal pushPacket() call does not need to be modified, which is why Stream ID is the easiest field on which to differentiate. As long as the Stream ID is equal to the Allocation ID, the Stream ID can simply be matched to the Connection ID to make a multi-out Port. Hence, a REDHAWK best practice is to maintain a one-to-one relationship between Stream and Allocation IDs.
If the IDs are the same, there are only two required changes to the standard Port implementation. The first change is that as the Port iterates over the list of connections, a simple check needs to be performed to only do the remote pushPacket() or pushSRI() call on connections where the Connection ID matches the Allocation ID associated with the current packet. The second change is that the internal storage of previous SRI states needs to become a vector rather than a single element so that a new connection gets the correct previous SRI for its stream rather than just the most recent stream that has had data sent.
F.5.2 SRI and Keywords
FrontEnd Devices use both the basic BulkIO SRI fields and the Keywords field for additional items. All standard SRI fields are filled out as appropriate in accordance with the existing BulkIO IDL descriptions. Table F.8 describes the additional FrontEnd-specific keywords.
|
F.6 Status
All FEI Tuner Devices must report the status of each tuner as an entry in the frontend_tuner_status Property. The frontend_tuner_status Property is a struct sequence where each element represents a single tuner as a structure containing all of the required status elements and a subset of the optional status elements. The frontend_tuner_status Property should contain entries for both allocated and un-allocated tuners so users can see additional available tuners for allocation.
F.6.1 Status Elements
The frontend_tuner_status Property consists of a sequence of frontend_tuner_status_struct structures. Each of these structures must contain all of the required elements listed below and may contain any number of the optional elements listed below. Additional elements are permitted in the structures if a suitable element is not already defined.
F.6.1.1 Required Status Elements
Table F.9 describes the required status elements for each tuner of an FEI Tuner Device. In some cases, null, zero, or blank values may be used to indicate that a value is not set for this Device, but each of these Properties must be in the status structure.
|
F.6.1.2 Optional Status Elements
Table F.10 describes the optional status elements for each tuner of an FEI Tuner Device. In some cases, null, zero, or blank values may be used to indicate that a value is not set for an individual Tuner, but all Tuners of the same Device must have the same set of Properties in their status structure.
|
F.7 RFSource Interface
FrontEnd Devices that have RFInfo output Ports and that flow RF metadata to other FrontEnd Devices also have an RFSource interface. Such Devices include antennas and RF distribution/switches. The RFSource interface is used to determine the currently selected RF Flow and all possible RF flows that a Device can provide. The interface has two attributes:
- RFInfoPktSequence available_rf_inputs - A list of all possible rf inputs to which this source could switch.
- RFInfoPkt current_rf_input - The currently selected source that is being output.
Typical consumers of the RFInfo can read these values to know if other RF flows are possible. A Device with the RFSource interface may get the information about its RF flows in multiple ways. The Device may get the information through a non-REDHAWK interface to the actual switch, it may be stored as a configuration item or a property, or it may be set through the RFSource interface by another entity in the system with knowledge of the current RF configuration. If an external entity has knowledge of the RF configuration and sets the two attributes on a Device, the Device should push out an updated RFInfoPacket to any connected users.
The allocateCapacity() interface of RFSource Devices is used to request a particular RF flow. Allocation is performed by setting the FRONTEND::RFSource::rf_flow_id allocation property equal to the rf_flow_id of the RF flow requested.
|
If the requested RF flow can be switched to the output, the RFSource Device will make the switch and the allocateCapacity() call will return true. If the Device cannot provide the RF flow or has already been allocated to another RF flow, the allocateCapacity() call will return false. If the Device is already allocated to the requested RF flow, the allocateCapacity() call will return true and increment the count of the total number of allocations received for that rf_flow_id. Once allocated, the Device will not switch RF flows until the number of deallocateCapacity() calls received is equal to the total number of allocations for that rf_flow_id. The total number of allocations for the selected RF flow is stored in a readonly property named allocationCount.
|
Even when the allocationCount is zero and no switch allocations are allocated, the
current_rf_input and the RFInfoPacket should reflect the current state of the RF Flow. For
example, even without allocation, if real RF data is still being output, the status should
reflect that. If no data is being output, then the current_rf_input attribute should be
empty. Setting the current_rf_input attribute does not imply allocation or a request
to switch an input. It assumes that this would only be set if the input had already
switched to that new value from outside of the Device. If the Device allocationCount is
not zero, it is not recommended to change the switch configuration and thus set the
current_rf_input.

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