View on GitHub

Chapter 12
Runtime Environment Inspection

12.1 Introduction

During runtime, there are a large number of operations that are handled under the hood by the REDHAWK Core Framework. At times though, it becomes necessary to take a closer look at these underlying parts to ensure that they are working properly or to inspect what kind of a state they are currently in. REDHAWK provides tools to help accomplish this task.

12.2 REDHAWK Module

A Python module called REDHAWK is provided with the capability to interact with running Domains, Devices, Waveforms and Components. This allows for individual control and assessment over all aspects of a runtime environment.

In order to use the REDHAWK utility module, begin a Python session from a terminal and enter the following command:

The REDHAWK module is built on the same foundation as the Sandbox, and provides a compatible interface for domain objects. Sandbox objects, including plots, can be dynamically connected to Devices, Waveforms and Components running in the domain.

Refer to Section 10.2.4 for details about interacting with Components and Devices in Python.

12.2.1 Attach

The module provides the ability to attach to a running Domain.

This allows the user access to the underlying API of the Domain Manager in addition to other useful functionality:

To attach to an existing Domain, the name must be passed as an argument.

Assuming the Domain name is MY_DOMAIN, start a Python script and enter:

Note that if there is only 1 Domain visible, no argument is needed for the attach call:

Once attached to the running Domain, Waveforms that are installed in the $SDRROOT can easily be launched using the createApplication() function:

Upon success, the above call returns an Application object which gives access to the external resource API. This allows for manual operation of the Application. In addition, functions exist to allow the user to connect and disconnect Ports. Finally, in order to inspect the current conditions of the Waveform, an API function call is available. This shows any external Ports, Components that are in the Application, and their Properties.

Once finished, the Waveform needs to be removed from the Domain by using the removeApplication() method:

12.2.2 Starting a Domain from within a Python session

Normally, the REDHAWK Python package is used to either interact with a running Domain, or to launch some Sandbox Components, as seen in Chapter 10. However, sometimes it may be required to launch a Domain from a Python script.

To help in such a scenario, the REDHAWK Python package includes some helper functions. The kickDomain feature allows for an easy way to launch Domain and Device Managers from within a Python script. With no arguments, the function launches and returns the Domain Manager that is installed in $SDRROOT. Additionally, all Device Managers in $SDRROOT/dev/nodes are started.

Other arguments to the function exist to control different aspects to how the Domain is started. A list of specific Device Managers to start can be passed if the user does not want to start all available. If the $SDRROOT that the user wishes to use is not in the standard location, a path can be supplied to direct the function to the desired place in the file system. Standard out and logging to a file can also be set.

The ability to search for Domains is also available through the scan function which searches the Naming Service.

12.2.3 Domain State

The Domain proxy tracks the current state of the Domain. For aspects of the Domain state that may take a long time to process, scanning is deferred until the first access. If the ODM Channel is available, Devices, Device Managers, and Waveforms are tracked as they are added to and removed from the Domain. Otherwise, the Domain is re-scanned on access to ensure that the state is accurate.

12.2.3.1 Applications

The Domain proxy provides a list of Waveforms currently running via the apps attribute:

The App class supports many of the Sandbox interfaces, such as Properties, connect() and api().

The Components within the Waveform are available via the comps attribute:

The REDHAWK module Component class supports the same interfaces as Sandbox Components, as seen in Chapter 10. Much like in the Sandbox, Ports, Properties, and any other feature of a Component is equally accessible from the Python environment, regardless of how the Component was deployed.

For example, if one were to want to plot the output of a Component running on the Domain:

12.2.3.2 Device Managers

The Domain proxy provides a list of Device Managers registered with the Domain via the devMgrs attribute:

Each Device Manager maintains a list of its Devices, accessible via the devs attribute:

12.2.3.3 Devices

The Domain proxy provides a list of all Devices registered with the Domain via the devices attribute:

The Device list is the concatenation of the Devices for all Device Managers.

The REDHAWK module Device class supports the same interfaces as Sandbox Devices.

12.2.4 Using With the Sandbox

As shown briefly in section 12.2.3.1, Sandbox and Domain objects are interoperable and can be connected together. This allows for inspection of different parts of the domain and more sophisticated testing of Components.

For example, to use a Sandbox plot to view the data coming from a device, enter the following commands:

Use the following commands to capture an approximately one second cut from a Waveform to a file:

When the Sandbox exits, any connections made between Sandbox objects and Domain objects are broken to limit interference with normal domain operation.

For more details on using the Sandbox, refer to Chapter 10.


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