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.
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.
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.
|
3.2.2 REDHAWK Basic Devices
Table 3.2 contains the names and descriptions of the REDHAWK Basic Devices.
|
3.2.3 REDHAWK Basic Waveforms
Table 3.3 contains the names and descriptions of the 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.
|
3.2.5 REDHAWK Device Dependencies
Table 3.5 contains the names and descriptions of some external libraries used by the REDHAWK Devices.
|
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.
When you click Generate All Implementations, the tool generates:
- skeleton-code for the Component in the language of choice
- the XML files associated with the Component
- Autotools build files
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
If you generate a Component that was previously generated in a REDHAWK 1.8 version, the Deprecated Generator dialog box is displayed:
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.
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:
- Translate incoming REDHAWK data to the available Octave data formats.
- Call the M function using Octave’s feval() C++ function.
- Translate the resulting Octave data to REDHAWK data formats.
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:
- Automatically compile and install the Component.
- Automatically create an RPM for the Component.
- Enable buffering, which causes the Component to wait for an End of Stream (EOS) before processing data.
- Enable the Octave diary, which writes Octave’s standard out and standard error to a file.
- Point to shared .m and .oct files.
- Specify an output directory.
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:
- Data must be passed as row vectors or n-by-m matrices. All values must be doubles.
- Configuration (property) values may be doubles, double vectors, or strings.
- The serviceFunction of the Component is auto-generated and should not be hand-modified. To manipulate data before or after the feval() call to Octave, modify the inputPackets and outputPackets maps in the preProcess and postProcess methods.
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.
- Open a Python session and import the Sandbox:
- Running a Component
- To get a list of available Components, type: The displayed list is derived by scanning $SDRROOT. HardLimit and SigGen are examples of existing Components.
- 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.
- 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):
- Create two plot objects by instantiating the Plot class twice and assigning the objects to local variables:
- 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.
- 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:
- Start everything in the Sandbox:
- The Property values can now be set on the HardLimit Component. The plot reflects the Property change:
- To inspect the Properties and input/output Ports of a Component, invoke the Component’s api() method:
- 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.
- In the REDHAWK Explorer View:
- Expand the Sandbox to expose the Chalkboard.
- Double-click the Chalkboard.
- From the Chalkboard:
- 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.
- If the SigGen Component is not displayed, left-click the rh folder to display the list of available Components.
- 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 -.
- Right-click the SigGen Component, and select Start.
- 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.
- Open the Properties View and change the following signal Properties:
- frequency: 100
- magnitude: 10
- Select the palette on the right, drag the HardLimit Component onto the Chalkboard.
- Right-click the HardLimit Component, click Start.
- 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.
- Right-click the dataFloat_out Port on the HardLimit Component, click Plot Port Data
- 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.
- Create a new REDHAWK Component Project:
- File > New > REDHAWK Component Project
- Name the project: HelloWorld
- Click Next.
- Select:
- Prog. Lang: C++
- Click Next.
- Click Finish.
- If a dialog asks to switch to CPP perspective, click No.
- Generate Code:
- In the editor tool bar, click Generate All Component Implementations, as seen in Figure 3.3
- In the HelloWorld.cpp file, add the following include to the beginning of the file:
- In the HelloWorld.cpp file, add the following code to the serviceFunction() method:
- Compile the project:
- Project> Build Project
- Drag the project to the Target SDR section of the REDHAWK Explorer.
- On a terminal, start a Python session.
- Run the following commands:

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