View on GitHub

Chapter 3
Components

3.1 Introduction

A Component is a modular building block that can be inserted into any number of signal processing applications to perform a specific and reusable function. A Component is fully defined by its interfaces, Properties, and functionality. Examples include a Component that tunes, filters, and decimates a wideband signal and one that performs a Frequency Modulation (FM) demodulation. Some Components inevitably need to be custom implementations, but a majority of signal processing functions can be reused and shared.

REDHAWK allows for developers to create Components in either C++, Python, or Java. C++ is recommended for most computationally-intensive tasks, whereas Python or Java work well for handling metadata manipulation or command and control tasks.

Components can be interconnected together within a Waveform to create a complete signal processing application or can be run independently in the REDHAWK Sandbox to perform trivial tasks on a local host. The figure below depicts the composition of Components into a Waveform.


PIC

Figure 3.1: REDHAWK Workflow


By using the REDHAWK Framework, basic processing elements may be encapsulated as Components and reused by other REDHAWK compliant systems. Using the REDHAWK IDE and the included code generators, much of the code for control and input/output can be auto-generated. The figure below depicts the encapsulation of an arbitrary processing algorithm into an auto-generated REDHAWK Component wrapper.


PIC

Figure 3.2: Components


3.2 REDHAWK Core Assets

REDHAWK packages Core Assets that consist of starter/example Components, Devices, Waveforms, and Shared Libraries.

3.2.1 REDHAWK Basic Components

REDHAWK Basic Components are a collection of starter/example REDHAWK Components. These Components provide basic Digital Signal Processing (DSP) capabilities while demonstrating many of the features and use cases of REDHAWK. Table 3.1 contains the names and descriptions of the Basic REDHAWK Components.

The following Basic Components have been removed:

  • DataWriter and DataReader have been deprecated by FileWriter and FileReader, respectively.
  • whitenoise has been deprecated by SigGen, which includes a whitenoise generation mode.
  • BurstDeserializer, freqfilter, medianfilter, and unwrap have been removed.

The following Basic Components have been updated to use the new shared library dependencies: agc, AmFmPmBasebandDemod, ArbitraryRateResampler, autocorrelate, fastfilter, psd, and TuneFilterDecimate.





Component

Version

Description




rh.agc

2.0

Provides automatic gain control to normalize power levels for real or complex signals.




rh.AmFmPmBasebandDemod

2.0

Performs analog demodulation on complex baseband input signals.




rh.ArbitraryRateResampler

2.0

Resamples a data stream at output rates that are not limited to integer multiples of the input sampling rate. This Component can increase or decrease the sample rate. No anti-aliasing filtering is included, therefore, you must use this Component with caution when decreasing the sampling rate to avoid aliasing or, if required, pre-filter in an upstream Component.




rh.autocorrelate

2.0

Performs a frequency domain implemenation of a windowed autocorrelation algorithm. This algorithm works by windowing the input data to break it up into separate frames. Each frame is independently autocorrelated with each other frame using a "full" autocorrelation, which includes the full transient response. This is efficiently computed in the frequency domain.




rh.DataConverter

4.0

Converts between BulkIO data types in REDHAWK. With proper configuration, converts between any of the following data types; Char, Octet, Unsigned Short, Short, Float, and Double. Also capable of converting real data into complex data, and similarly, complex data into real data. By default, nothing needs to be configured. When using float or double output BulkIO Ports, set the normalize_floating_point with the floatingPointRange of -1 and 1.




rh.fastfilter

2.0

Provides a FIR filter implementation using the Fast Fourier Transform (FFT)-based overlap-add technique. This Component includes a filter designer, which aids in impulse response creation for lowpass, highpass, bandpass, and bandstop filters. The Component accepts custom impulse responses via Property configuration.




rh.fcalc

2.0

Enables users to perform calculations on one or two input streams simultaneously on an element by element basis. The calculation is specified in Python syntax using a and b to denote input on the a and b Ports. Valid examples: 3*a+b and a*math.cos(b).




rh.FileReader

4.0

Reads in a file and converts it to BulkIO data to be streamed out. Capable of sending data, regardless of file format, out of most of its ten data Ports. This ability excludes the Extensible Markup Language (XML) and the DomainManager_out Ports. To use this Component, the file_format must match that of the file and you are required to specify a source_uri (location of the file); a sample_rate; the center_frequency when applicable; and the playback state to play.




rh.FileWriter

4.0

Writes out a data file from a BulkIO stream. It is not capable of changing the file format to be different from the BulkIO input stream. To use this Component, you are required to specify a destinations_uri (location to write to) and a file format and set recording_enable to true.




rh.HardLimit

2.0

Thresholds data so that all data is between the upper and lower limit as specified by the Properties.




rh.psd

2.0

Transforms data from the time domain to the frequency domain using an FFT-based Power Spectral Density (PSD). Output data is framed data where each frame contains the frequncy domain representation of a subsection of the input. This Component provides both the real-valued PSD and the complex FFT outputs.




rh.psk_soft

2.0

Takes complex baseband pre-d data and does a PSK demodulation of either BPSK, QPSK, or 8-PSK and outputs symbols and bits. Input must be an integer number of samples per symbol (recommended 8-10).




rh.RBDSDecoder

2.0

Decodes RBDS data from broadcast FM using the RBDS Standard Specification.




rh.SigGen

2.0

Generates different output signals based on its configuration. Contains an implementation in each of the supported languages (Python, C++, Java) and is an example of a Component with multiple implementations.




rh.SinkSDDS

1.0

Accepts BulkIO data and produces a single SDDS stream over the provided multicast or unicast address.




rh.sinksocket

2.0

Reads data from a BulkIO Port and writes it to a TCP socket.




rh.SinkVITA49

3.0

Creates a UDP/multicast or TCP VITA49 packet stream and converts the data and SRI Keywords to IF data packets and Context packets for use within/between/outside of a REDHAWK domain application.




rh.SourceSDDS

1.0

Consumes a single SDDS formatted multicast or unicast UDP stream and outputs the data via the appropriate BulkIO native type.




rh.sourcesocket

2.0

Reads data from a TCP socket and writes it to a BulkIO Port.




rh.SourceVITA49

3.0

Connects to a UDP/multicast or TCP VITA49 packet stream and converts the headers to SRI Keywords and data to the BULKIO interface of the user’s choice for use within REDHAWK domain applications.




rh.TuneFilterDecimate

2.0

Selects a narrowband cut from an input signal. Tuning, filtering, and decimation are used to remove noise and interference in other frequency bands and reduce the sampling rate for more efficient downstream processing.





Table 3.1: REDHAWK Basic Components

3.2.2 REDHAWK Basic Devices

Table 3.2 contains the names and descriptions of the REDHAWK Basic Devices.





Device

Version

Description




rh.FmRdsSimulator

2.0

Designed to be used in conjunction with the libRfSimulators library. Using the simulator library, this FrontEnd Interfaces compliant REDHAWK device will generate FM modulated mono or stereo audio with RDS encoded PI (Call Sign), PS (Short Text), and RT (Full Text) data.




rh.RTL2832U

2.0

Interfaces with the Realtek RTL2832U usb dongle device using the librtlsdr Device dependency. Supports various tuners, including Elonics E4000, Rafael Micro R820T and R828D, Fitipower FC0012 and FC0013, and FCI FC2580.




rh.USRP_UHD

4.0

FrontEnd Interfaces compliant device for the USRP that requires the UHD host code and supporting libraries to be installed.





Table 3.2: REDHAWK Basic Devices

3.2.3 REDHAWK Basic Waveforms

Table 3.3 contains the names and descriptions of the REDHAWK Basic Waveforms.





Waveform

Version

Description




rh.basic_components_demo

1.0

Uses a few core assets. Data from SigGen is created and manipulated to demonstrate REDHAWK.




rh.FM_RBDS_demo

1.0

Processes the RBDS digitial message present in broadcast FM radio signals. Tunes and filters out this signal, performs a BPSK demodulation, and then decodes the RBDS data.




rh.FM_mono_demo

1.0

Processes the mono audio channel of broadcast FM Radio.




rh.short_file_to_float_file

1.0

Reads in a file containing shorts, converts them to floats in REDHAWK, and then writes out the file. Uses three Components: FileReader, DataConverter, and FileWriter.




rh.socket_loopback_demo

1.0

Puts REDHAWK data out onto a network socket using sinksocket and then reads it back from the socket into REDHAWK via sourcesocket.




rh.VITA49_loopback_demo

1.0

Uses the sourceVITA49 and sinkVITA49 Components to demonstrate how VITA49 network data can move into and out of REDHAWK.





Table 3.3: REDHAWK Basic Waveforms

3.2.4 REDHAWK Shared Libraries

Table 3.4 contains the names and descriptions of the basic REDHAWK Shared Libraries.

All shared library (formerly soft package) dependencies have been repackaged using the new code generators, and the following basic Components have been updated to use the new shared library dependencies: agc, AmFmPmBasebandDemod, ArbitraryRateResampler, autocorrelate, fastfilter, psd, and TuneFilterDecimate.

The following shared libraries have been renamed:

  • redhawk-VITA49Libraries_V1 has been renamed VITA49.
  • RedhawkDevUtils_v1 has been renamed RedhawkDevUtils.





Shared Library

Version

Description




rh.blueFileLib

2.0

Provides a library for interacting with Midas BLUE files, the standard binary file format used by modern Midas frameworks.




rh.dsp

2.0

Provides a DSP library for basic Components. Much of the actual signal processing code is contained in this library, which is independent of REDHAWK.




rh.fftlib

2.0

Provides a DSP library wrapping FFTW for basic Components. Provides a higher level of functionality than what is contained in FFTW by providing classes for taking FFTs and their inverses and signal processing classes, which leverage these FFT capabilities.




rh.RedhawkDevUtils

4.0

Provides a library that contains utility functions useful for REDHAWK development. Utility functions are included for working with vectors, byte swapping, file I/O, universal data types, and transforms between data types, as well as assisting with compatability across multiple boost versions. Additionally, various REDHAWK helper functions are provided for UUID generation and CORBA serialization, and working with Properties, BulkIO, base-64 characters, strings, and Domain Managers.




rh.VITA49

3.0

Provides VITA Radio Transport (VRT) libraries that represent a (nearly-complete) software-based implementation of the following ANSI specifications:

  • VRT/VITA 49.0
  • VITA Radio Link Layer (VRL) / VITA 49.1





Table 3.4: REDHAWK Shared Libraries

3.2.5 REDHAWK Device Dependencies

Table 3.5 contains the names and descriptions of some external libraries used by the REDHAWK Devices.





Device Dependency

Version

Description




libRfSimulators

1.1

Used to simulate an RF Digitizer. At present, the RF Simulators library contains a single implementation: the FM RDS Simulator. While the RF Simulators library was designed to be used within the REDHAWK SDR environment, the library itself has no dependency on the REDHAWK framework and may be used as a stand alone C++ library.




librtlsdr

0.5.2

Provides the rtl-sdr hardware driver that enables Realtek RTL2832-based DVB dongles to be used as SDR receivers. Managed by osmocom.org.




uhd

3.7.3

Provides the USRP hardware driver (UHD) for use with the USRP product family. Managed by ettus.com. This is the version shipped with REDHAWK; however, some USRP hardware may require a more current version.





Table 3.5: REDHAWK Device Dependencies

3.3 Creating a Component Project

In this section, an overview of the structure of a Component is presented.

3.3.1 Component Wizard

In the REDHAWK IDE, development of new Components, Devices, or other artifacts in a REDHAWK environment is contained within an Eclipse project. Each REDHAWK-specific artifact is associated with a wizard that leads the developer through the steps necessary to create a project, which supports the minimum required pieces for proper functioning. For Components, the default project settings allow the developer to choose between Python, C++, and Java as the development language. To start the IDE and begin creating a Component, run the eclipse binary in the IDE installation directory. Then, select File > New > REDHAWK Component Project.

3.3.2 Component Descriptors

A REDHAWK Component is described through three XML files, a Software Package Descriptor (SPD) file (<component>.spd.xml), a Properties File (PRF) file (<component>.prf.xml), and a Software Component Descriptor (SCD) file (<component>.scd.xml). The role of the SPD is to describe all the files that are associated with the Component: the PRF and SCD files, all binaries, and associated data files. The PRF file contains a description of all the Properties that this Component supports. The SCD file contains a description of the Component inputs/outputs.

The REDHAWK IDE uses an internal model to maintain the state of the Component design. This model is a Java representation of the three XML files described above as well as project-specific information (like the development language). The main screen on the Component development perspective contains several tabs. Some of these tabs are for panels and some are for XML files. The different panels available for Component design are used to change this model; the model is automatically and continuously mapped to the three XML files. This awareness is symmetrical; much like changes in the panels result in changes in the XML files, changes in the XML files result in automatic updates to the panels.

3.3.3 Ports

Data flow into and out of Components is accomplished through the use of Ports. Ports are described as being either a provides (input) or uses (output) Port. This naming convention is often viewed as counter-intuitive, so an explanation is in order. Ports are Remote Procedure Call (RPC) interfaces to a Component. An input Port, therefore, provides functionality that can be used by an output Port.

REDHAWK contains a variety of standardized interfaces that facilitate interoperability. These interfaces are implemented by Ports. When a Port is selected in the Component generation wizard in the REDHAWK IDE, code to implement these interfaces is automatically generated.

3.3.4 Properties

Properties provide a way to adjust a Component’s configuration or settings while also allowing external entities (e.g., programs, UIs, or status scripts) to inspect the state of the Component. Properties are the primary means for Component configuration.

There are four types of Properties: simple, simple sequence, struct, and struct sequence. A simple Property has a single value of a paritcular primitive type (e.g., short or float). A simple sequence is an array of values of a the same primitive type. A struct property is a structure that contains a set of named simple and/or simple sequence properties. A struct sequence is an array of instances of the same struct type.

Properties also have a kind that expresses the role in which the property is used. The kind can be property, allocation, or message. The property kind is used for configuration and status. The allocation kind is used to express requirements on capabilities provided by Devices. The message kind is used only with struct properties to send event messages within REDHAWK.

3.3.5 Logging

Components, irrespective of which language is used for their implementation, contain access to loggers. Logging in C++, Python, and Java utilizes log4j, a powerful logging framework maintained by the Apache Software Foundation.

3.3.6 Generating Components

The Generate All Implementations button (Figure 3.3) is located in the top-right of the Overview panel of the Component development project.


PIC

Figure 3.3: Generate All Implementations Button


When you click Generate All Implementations, the tool generates:

The code generators are not exhaustive. There are edge case Port types that may not compile.

3.3.6.1 Re-generating Components from a Prior Version

REDHAWK 1.8 only

If you generate a Component that was previously generated in a REDHAWK 1.8 version, the Deprecated Generator dialog box is displayed:


PIC

Figure 3.4: Deprecated Generator dialog box


If you select Upgrade, hidden project files are modified to indicate the 2.0 Code Generator has been used. Code generation then proceeds as normal. If you upgrade the Component, it may be difficult to revert back to the original 1.8 state. If you select Cancel, the source code for the Component project is not modified.

The Java Component pattern changed in REDHAWK 1.9. For more information about how the Java Component pattern affects code generation, refer to Section 4.2.4.

All REDHAWK Versions Prior to 2.0

If you generate a Component that was created prior to REDHAWK version 2.0, the IDE checks the project for deprecated Properties and displays the Deprecated property kinds dialog box, which prompts you to upgrade the properties.


PIC

Figure 3.5: Deprecated property kinds dialog box


If you select Yes, the configure and execparam kinds are changed to property. The commandline attribute is set for execparam kinds, and they may have their mode (read/write) adjusted as necessary to maintain equivalent meaning.

Additionally, the event kind is removed from Properties. The new recommended method for obtaining notification of Property changes is to register for the desired Properties via PropertyEmitter.registerPropertyListener() on the resource.

In REDHAWK 2.0, the type attribute of the softpkg element of the spd.xml file is now used to mark which version of REDHAWK was used to generate the Component code. In prior REDHAWK versions, it was sca_compliant or sca_non_compliant, while now it is the REDHAWK version (For example, 2.0.1).

3.3.7 Installing Components

After a Component is compiled, it must be installed in the staging area ($SDRROOT/dom/components). To install a Component from the Project Explorer View, drag the top-level Component project onto the Target SDR section of the REDHAWK Explorer View. Additional methods for Deploying Projects to the SDRROOT are outlined in Section 14.8

3.4 Creating Octave Components

3.4.1 Overview

REDHAWK provides the ability to auto-generate a REDHAWK Component given an Octave M function. Assuming M functions are set up to input/output data vectors rather than relying on file or terminal-based input/output, these Components are seamlessly deployable on runtime systems.

Octave version 3.4 or greater, with development support, must be installed on the development and deployment systems. This requirement can be met by either installing Octave from source or installing the octave-devel Red Hat Package Manager (RPM).

The generated REDHAWK C++ code utilizes the Octave C++ programming interface to:

In many cases, the Octave Component can be created without any C++ programming by the developer and without an in-depth understanding of REDHAWK. Developers with a more in-depth understanding of C++ programming and REDHAWK have the option of leveraging more advanced REDHAWK features by modifying the generated C++ code. Furthermore, Octave Components can be composed into Waveforms with Components written in other languages (Java, C++, and Python).

3.4.2 The createOctaveComponent Script

Octave Components can be generated using a command line tool (createOctaveComponent) or using the REDHAWK IDE (Section 14.11). The help string for the command line tool can be accessed by entering the following command:

In the most simple case, the command line tool is passed a list of M files with no addtional flags. Function arguments that have a default value are treated as properties and function arguments without default values are treated as Ports.

Below is an example of a basic M function defined in a file named addConst.m:

To generate the Component code, use the following command:

Refer to the createOctaveComponent help string for flags to:

3.4.3 Design Considerations

There are a few design considerations to keep in mind when creating an M file to be used in REDHAWK:

3.5 Running a Component

To run a Component, use one of the following mechanisms: the REDHAWK Sandbox or the REDHAWK Domain. When using the Sandbox, a Component is run from within a Python shell or a graphical environment, all operating on a single computer. When using the Domain, a Component is run in the context of an Application that can be deployed over an arbitrarily large number of computers. The Sandbox is useful for tasks such as signal processing development and analysis, Component debugging, and data inspection.

3.6 Sandbox

This section describes how to use the Sandbox either from a Python shell or through a UI available on the REDHAWK IDE.

3.6.1 Python Sandbox

The Sandbox can be accessed directly from the command line and is used to manipulate new Components and Waveforms. This provides a very powerful means of testing and scripting tests for REDHAWK systems.

The following procedure is a short overview of how to use the Sandbox ; for a more detailed description of the Python Sandbox, refer to Section 10.2.

  1. Open a Python session and import the Sandbox:
  2. Running a Component
    1. To get a list of available Components, type:
      The displayed list is derived by scanning $SDRROOT. HardLimit and SigGen are examples of existing Components.
    2. Create the Component object by typing:
      After the constructor is finished, the Components run as their own processes. If an absolute file path for a Component’s SPD file (<component>.spd.xml) is given as a constructor argument for the Component instance, then that Component is started irrespective of whether or not it is present in $SDRROOT.
  3. Support widgets are available in the Sandbox to help the developer interact with running Components. There are a variety of widgets, including data sources and sinks, a speaker interface, and plotters. In this example, the plot widget is used.

    To use plotting, the path to the eclipse directory of the installed IDE must be specified in the Sandbox (this can also be done by setting the RH_IDE environment variable to the absolute path of the Eclipse directory prior to starting the Python session):

    1. Create two plot objects by instantiating the Plot class twice and assigning the objects to local variables:
  4. Connect the Components together and connect the plots. The connect() method tries to match the Port; ambiguities can be resolved with the parameters usesPortName and providesPortName. Connecting the plots to the Components displays the Plot Application window.
  5. In this tutorial, the SigGen Component is configured before it is started to get a better visual. Set the frequency of the SigGen Component equal to 5006:
  6. Start everything in the Sandbox:
  7. The Property values can now be set on the HardLimit Component. The plot reflects the Property change:
  8. To inspect the Properties and input/output Ports of a Component, invoke the Component’s api() method:
  9. To clean up, type Ctrl+D to end the Python session. The Python Sandbox releases all Components and cleans up whatever plots or additional widgets were created during the session.

3.6.2 The IDE Sandbox

This section provides an overview of how to use the Sandbox in the REDHAWK IDE. The IDE Sandbox provides a graphical environment for launching, inspecting, and debugging Components, Devices, Nodes, Services, and Waveforms. For more information about launching and interacting with items in the Sandbox, refer to Section 10.3. In addition, via the REDHAWK Console, you can use the Python-based Sandbox API to interact with objects that are running within the IDE Sandbox. For more information about the Python Sandbox, refer to Section 10.2.

The following procedure provides an example of launching and interacting with a Component in the Sandbox in the REDHAWK IDE.

  1. In the REDHAWK Explorer View:
    1. Expand the Sandbox to expose the Chalkboard.
    2. Double-click the Chalkboard.


    PIC
    Figure 3.6: Open Chalkboard


  2. From the Chalkboard:
    1. Select the palette on the right; drag the SigGen (cpp) Component onto the Chalkboard. The Component will initially be gray in color until launching is complete. When the Component is finished loading, its background color is blue. SigGen will be used to help test the new HardLimit Component.
    2. If the SigGen Component is not displayed, left-click the rh folder to display the list of available Components.
    3. If the cpp implementation is not displayed, expand the list of implementations by left-clicking the arrow to the left of the Component name and select the cpp implementation.

      To zoom in and out on the diagram, press and hold Ctrl; then scroll up or down. Alternatively, press and hold Ctrl; then press + or -.

    4. Right-click the SigGen Component, and select Start.
      PIC
      Figure 3.7: Start Component


    5. Left-click the dataFloat_out Port to select it, then right-click the Port to open the Port context menu, and select Plot Port Data.
      PIC
      Figure 3.8: Plot Port Data


    6. Open the Properties View and change the following signal Properties:
      • frequency: 100
      • magnitude: 10


      PIC
      Figure 3.9: Change Property Value


    7. Select the palette on the right, drag the HardLimit Component onto the Chalkboard.
    8. Right-click the HardLimit Component, click Start.
    9. Connect the dataFloat_out Port on the SigGen Component to the dataFloat_in Port on the HardLimit Component by clicking and dragging from the solid black output Port to the input Port.
      PIC
      Figure 3.10: Connect Ports


    10. Right-click the dataFloat_out Port on the HardLimit Component, click Plot Port Data
    11. Notice that the output has been hard limited by the HardLimit Component

3.7 Creating and Running a Hello World Component

Use the following procedure to create a simple Component that prints hello world to the terminal upon startup.

  1. Create a new REDHAWK Component Project:
  2. Name the project: HelloWorld
  3. Click Next.
  4. Select:
    • Prog. Lang: C++
  5. Click Next.
  6. Click Finish.
    • If a dialog asks to switch to CPP perspective, click No.
  7. Generate Code:
  8. In the HelloWorld.cpp file, add the following include to the beginning of the file:
  9. In the HelloWorld.cpp file, add the following code to the serviceFunction() method:
  10. Compile the project:
    • Project> Build Project
  11. Drag the project to the Target SDR section of the REDHAWK Explorer.
  12. On a terminal, start a Python session.
  13. Run the following commands:


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