What is REDHAWK?

REDHAWK is a resilient, SCA-compliant, and open-source infrastructure which provides distributed computing framework for your project. Deployable on Linux-based systems, it supports C/C++, JAVA, and Python languages as well as open-source and industry standard protocols. It is licensed by the US Government with many independent contributors. And cost-wise: it is free.

A typical REDHAWK development installation includes an Eclipse-based IDE, various libraries, and Components for typical Software Defined Radio (SDR) applications. Also included are utilities to support a prototyping sandbox in Python.

But it is also much more.

While REDHAWK’s main focus is SDR, its framework, tools, and libraries are generic to provide support for a wide array of possible program areas. So for as much as it provides, it is also a blank slate.

The framework’s hierarchy starts with three top-level aggregation entities and branches down into specific hardware- and generic software-centric roles. The REDHAWK framework provides infrastructure to separate software design from the hardware life cycle as well as management of each at the system level. It is this strict separation that aims to ensure your particular applications are re-usable as the underlying hardware architecture, and even the network connectivity, change over the life of the application.

The fundamental concepts involve separating the overall application into generic and re-usable entities managed as system resources and users by the Domain. This guide aims to shed light on why one would use specific entities and associated attributes in a given system design to help demystify how to use REDHAWK fully.

Top-level Overview

Understanding the REDHAWK infrastructure clarifies its impact on a resulting system's capabilities.

The top-level entities of REDHAWK’s framework provide the infrastructure to distribute a Waveform across system-level resources. These entities are the Domain Manager, Device Manager¹, and Waveform². To use REDHAWK, at least one of each must exist to use or manage the others.

All entities are described by at least one SCA-compliant DTD-verified³ XML file. These files describe the various attributes of the overall system design, dependencies, resources, etc. and are used by code generators to serialize the more easily-maintained source code. Ultimately, understanding the REDHAWK infrastructure clarifies its impact on a resulting system's capabilities.

Domain Manager

The Domain Manager is defined in the SCA specification as the manager of the complete set of hardware devices and applications within a Domain. Described by its DMD⁴ file, it is chiefly responsible for startup and shutdown of Waveforms as well as the management of system resources. Because of this responsibility, the Domain Manager has a one-to-many relationship with Waveforms and Device Managers.

A Domain’s name is made public to the system by way of OmniORB’s naming service. Device Managers are declared to run on specific domain names and locate the respective Domain Manager using this naming service. Additionally, it is possible to have multiple Domains on a shared naming service to facilitate wide-scale interactions between each.

The Domain Manager also makes use of OmniORB’s event service so that activity can be monitored using SCA-defined Event Channels. These channels can be observed from within Device Managers and Waveforms using the FindBy design element as well as from the operating system environment using the provided command line tools⁵.

Domain Managers can also be actively observed and controlled using an extensive library of Python-based APIs. The associated launcher, nodeBooter, can easily be daemonized in a typical Linux installation.

The initial choices in a REDHAWK system design should focus on what level of granular system abstraction is preferred to collect resources and software into reusable entities.

Given all of these details, a Domain could be roughly analogous to all resources and capabilities of a given vehicle in an environment. Just as reasonably, a Domain could also be a single handheld multi-purpose device akin to a smartphone with its wide variety of internal capabilities and resources. Understanding the relationships between these three top-level entities will help clarify where to partition the system.

The figure at the start of this chapter is an example of a Domain with two equivalent Device Managers registered⁶. Three Waveforms exist in the Domain, but only two are launched, A and C. And in the case of Waveform A, it is deployed twice: once on a single Device Manager and once spread across both Device Managers.

A glossed-over detail here is the two Device Managers do not need to be identical. As long as each has an executable Device with enough resources to satisfy the remaining dependencies, the Waveform can be deployed across each subsystem or collected entirely on a specific system. It is also one of REDHAWK’s advantages that this deployment can either be managed or automatic.

As one would expect, the Domain will be a hub of activity and system-level requests: it should be deployed on a system with enough resources to handle the load. However, the initial choices in a REDHAWK system design should focus on what level of granular system abstraction is preferred to collect resources and software into reusable entities.

Device Manager

Similar to the Domain Manager being the functional mechanism behind the Domain entity, the Device Manager is the mechanism behind a Node. Because of this relationship, the terms Device Manager and Node are sometimes used interchangeably since one is the embodiment of the other.

Nodes are defined to exist in a specific Domain and typically contain some number of Devices and/or Services. By definition then it is a system resource provider from what is usually considered the hardware side of a system’s architecture since it contains proxies to hardware interfaces.

Device Managers are described by a DCD⁷ XML file which contains the bulk of the information about the Node and any property overrides for the entities it contains. A Device Manager's registration with the Domain requires unique deviceconfiguration and componentinstantiation* IDs in this descriptor file⁸.

Another important detail: the Device Manager and all of its entities fork at launch into separate threads. So while you can run multiple Device Manager instances from the same computer system, do keep this detail in mind when choosing the supporting computer platform.

In deciding how to use Nodes, keep in mind that being representations of hardware each usually has a life cycle similar to a computer. It is powered on and left running to support whatever the user activities (Waveforms) might be executed.

The image above provides some context for the types of entities that could exist if a smart phone were to be represented by a Device Manager. The entities are generic and re-usable since the Waveform will to dictate the use case for each.

Waveform

The terms Waveform and Application are synonymous, for as near as makes no difference. The SAD⁹ XML file describes deployed Components, any non-default property settings, and any Component Port connections.

Waveforms are deployed (launched) by the Application Factory and execute while system resources are available or until manually stopped. Multiple instances of the same Waveform can also be deployed in the same Domain as well as their individual Components on the same executable Device since the Application Factory enforces the system-level uniqueness for each launch¹⁰.

The goals behind Waveform design can be summarized as giving an operational context to the available resources. Some simplified examples are pictured in the image at the start of this section.

When the Waveform is deployed, the operator can decide whether or not the resources must exist on the same Node. Do keep in mind however that every Component in a Waveform forks into its own thread on the targeted Node. Load balancing then will become a critical part of testing as a Waveform becomes more granular with increasingly generic, reusable entities.

One of the key constraints to the Waveform is where it can exist: Waveforms cannot be deployed across two Domains. As the highest-level entity in REDHAWK, each Domain manages its own Device Managers (and thus, Devices). Therefore no higher level entities exist to share intra-domain resources.

However, this behavior can be achieved by creating a Service to act as a gateway between Domains. REDHAWK will take care of creating and announcing the Service, but creating the back-end architecture becomes a third-party opportunity for the developer to fulfill.

System Abstraction Example

Partitioning the system resource side will impact how easily certain Waveform concepts can be deployed. Take for example a system containing many smartphones, each effectively equivalent and brimming with sensors, processors, etc. Should each phone be:

1. A Domain with Nodes for each subset of onboard hardware?
2. A Node within a Domain with Devices representing the onboard hardware?

In the first case, every Waveform one might choose to run will only be able to run using a single phone’s resources. This might be acceptable if the Waveforms are intended to stream a few onboard sensors all located on the same phone. There would be no real distinction or concern with Waveform-level collocation because you already know the Domain represents a single physical phone¹¹.

Another advantage of the first case is that it can be cloned very easily to have many Domains of exactly the same code. The caveat is that each Domain must have a unique name which is certainly a small premium to pay if one does not need to run aggregator-like Waveforms.

On the other hand, if you do need a higher level aggregation by using the equipment and sensors from multiple phones: it is effectively on the developer to create what is needed. While REDHAWK provides event channels, services, and a wide array of APIs to support this decision, one might find the second case a better alternative for such flexibility.

The second case would allow a developer to deploy system-wide aggregation Waveforms as well as Waveforms intended to run on a single Node. One trade-off here is in deploying the physically-collocated Waveforms.

REDHAWK supports a variety of deployment mechanisms including Waveform-declared collocation. Its purpose is to ensure some specific Components are executing on the same Device perhaps providing local (faster) access to data streams of other entities (Devices, Services, or Components). Having a Component process data streamed from an entity deployed on a different Node will result in network traffic.

Given the constraints, launching a Waveform with physical collocation dependencies may be better handled explicitly (i.e., manually). It is a straight-forward process, and its availability is worth knowing in advance.

Another trade-off is how flexibly you can re-use the Node software. Recall that in order to have identical Domains on the naming service, only the domain's name needs to be different. With Nodes, a clone requires a little more effort.

The instance IDs for the Devices in a Node, as well as the Node’s own UUID, must be unique within a Domain. A Service’s instance name must also be unique within a Domain. Therefore if your intended use case is to create one example Node, clone it to multiple systems, and turn each loose on the same Domain: the Device Manager registration will fail unless these IDs are all unique between Nodes.

This too is a simple-enough issue to resolve for Devices. A simple startup script to randomly change these IDs once will ensure all deployed Nodes can register.

Nodes with Services are a more difficult issue since each is found by name. When using Services, keep this behavior in mind and consider alternatives to deploying cloned Nodes with Services in them.

1. Device Manager is sometimes synonymously referred to as a Node. ↩
2. The terms Waveform and Application are often used interchangeably. ↩
3. The DTDs can be found in the repository framework-core/src/xml/dtd for future reference. ↩
4. Domain Manager Configuration Descriptor ↩
5. See eventviewer documentation or our other tutorials for usage and examples. ↩
6. Deploying equivalent Device Managers (i.e., roughly identical software) requires providing unique IDs to each. ↩
7. Device Configuration Descriptor ↩
8. The deviceconfiguration ID must be a UUID-formatted ID. The componentinstantation can use more meaningful names. ↩
9. Software Assembly Descriptor ↩
10. Recall, the Device Manager requires manually maintaining uniqueness at the system level if attempting to run multiple clones of the same underlying code. ↩
11. Unless of course the phone actually has multiple executable devices at which point Waveform-level collocation would be a useful feature. ↩