Try OpenZMS in POWDER

We package OpenZMS as an automated POWDER profile. You can try this profile and its associated instructions and demos by creating a POWDER account if you don't have one, or by logging in and joining the openzms-demo project with your existing account.

Using POWDER

(If you are familiar with POWDER, skip to the Create an OpenZMS Experiment section.)

The POWDER platform is a mobile and wireless network testbed on the University of Utah campus. It provides the research community with remote access to a variety of radio equipment (software-defined and COTS) and cloud compute resources. POWDER supports a wide variety of experiments, including 5G and beyond, massive MIMO, Open RAN, spectrum sharing, and many more. POWDER serves as an important development environment for OpenZMS.

POWDER provides significant automation and pre-packaging support to deploy large software stacks on its resources. A POWDER profile is a description of the radio, compute, and network resources required to run a test or experiment; the software that runs on those resources; and runtime configuration of both hardware and software. POWDER users instantiate profiles to create experiments. Powerful profiles typically provide parameters to customize the experiment, both in terms of resources and runtime configuration.

The OpenZMS profile deploys the core OpenZMS components and configures an account so you can experiment with both the frontend and the backend service APIs. Its simple instructions are designed to familiarize you with some of the core northbound (user-facing, RESTful) and southbound (internal, gRPC) APIs. The profile uses Ansible and Docker compose to deploy the OpenZMS services. The source code (e.g. Ansible roles providing runtime configuration) is available at https://gitlab.flux.utah.edu/openzms/zms-profile .

Request a POWDER Account and Join the openzms-demo Project

Follow the instructions in the POWDER Getting Started guide: https://docs.powderwireless.net/getting-started.html --- but instead of joining the TryPowder project, join the openzms-demo project. At this point, you will need to wait for POWDER administrators to approve your account.

While you are awaiting approval, you can read through the zms-profile instructions: https://www.powderwireless.net/show/openzms/zms-profile .

Accessing OTA Resources on POWDER

The POWDER manual describes how to use POWDER. Before running these demonstrations, you should look at several sections:

• Hardware and wireless environments

  Since you are focusing on outdoor experiments, you can skip the first several sections covering indoor resources---"Conducted attenuator matrix resources", "Paired Radio workbench resources", "Indoor OTA lab resources".

• Reserving resources

  POWDER outdoor radio resources are often in high demand, so it is wise to create a reservation for the necessary resources. However, to run the demos on-demand, you can check currently available resources.

  • For the Smart Transmitter and Smart 5G "In a Box" demos, you'll need both radios at a single Fixed Endpoint (or two, if you plan to run them simultaneously. Look for the "Fixed Endpoint Availability" table.

  • For the Smart 5G with Mobile UEs demos, you'll need several radios in the dense deployment. Ideally we would recommend cnode-ustar, cnode-guesthouse, and cnode-mario to best cover the mobile UE shuttle routes, but you can browse the map of the dense deployment to select a different subset.

Create an OpenZMS Experiment

Once approved, you can click the Instantiate button on that page, or instantiate directly via https://www.powderwireless.net/p/openzms/zms-profile .

You can run the profile in one of two modes:

• Standalone: an on-demand instance of OpenZMS that has no spectrum to manage nor radios to which to award grants. This option is useful if you simply want to play with the API and UI, and experiment with adding simulated data to mock other OpenZMS deployments.

• RDZ-in-RDZ: an on-demand instance of OpenZMS that can act as a "virtualized" or "nested" private RDZ, within the broader RDZ. In this mode, your RDZ-in-RDZ experiment is given an exclusive grant of spectrum from the "outer" RDZ, which the "inner" RDZ then turns into a range of spectrum that it can further delegate to grants for other POWDER-RDZ experiments. This mode is useful if you want to run real, end-to-end and over-the-air spectrum sharing demos with full visibility into what the "inner" OpenZMS is doing, or if you want to experiment with changing OpenZMS components and policies in spectrum sharing and coexistence experiments.

Parameterizing Your Experiment

If you want to run the spectrum sharing demos below, click the Enable RDZ-in-RDZ mode option in the Parameterize step of the instantiate wizard.

When you select RDZ-in-RDZ mode, your experiment will request a range of spectrum, and POWDER-RDZ will request an OpenZMS grant that fulfills this request. The requested spectrum may be a range larger than the associated bandwidth, and if so, the "outer" OpenZMS will select a matching, least-used, unoccupied portion of the spectrum it manages. The grant for your RDZ-in-RDZ experiment will be added to the "inner" OpenZMS as a Spectrum object, which will allow the inner OpenZMS to assign grants from that Spectrum (e.g., to other POWDER-RDZ experiments that request spectrum from your RDZ-in-RDZ).

The default Frequency Min/Max and Bandwidth parameters will accommodate the default configuration of the simple smart transmitter in the rdz-demo profile in the first spectrum-sharing demo. If you plan to run multiple simultaneous POWDER experiments whose spectrum is allocated using your RDZ-in-RDZ instead of the "outer" POWDER-RDZ, you may need to increase the bandwidth parameter to accommodate those use cases.

Exploring Your OpenZMS Experiment

The OpenZMS profile is self-documenting. Expand the Profile Instructions blue box on your experiment status page. These instructions are re-rendered for each experiment you run and include experiment-specific URLs and credentials to access your private OpenZMS and its RESTful API endpoints. The Instructions provide a brief summary of how the profile deploys and configures OpenZMS and how to access APIs.

Once your OpenZMS experiment has finished setting up, you can click on the OpenZMS web interface link in the Profile Instructions. Login with the provided admin user and random password just below the link. Once you login, click the circular green-A icon in the upper right to the left of the admin user menu. This will turn the green-A icon red, meaning you have entered admin mode. This will give you the broadest possible view as you explore and run demos.

Once you have enabled admin mode, click the Status menu item in the lefthand navbar. (If you have a narrow screen, the navbar may have collapsed; click the menu icon at the top left to force it open.)

• If you have enabled RDZ-in-RDZ mode, you will see a map view of the University of Utah campus, with deployed POWDER radios represented as blue location icons.

  • Your RDZ-in-RDZ experiment received a grant of spectrum from the "outer" RDZ, and turned it into a Spectrum object, which you will see to the left of the map in the Spectrum subpanel. Click on it, then down in the Radios subpanel just below the Grants subpanel, click the All toggle to show all Radios on the map again. Your map view should look like this:

    

• If you have not enabled RDZ-in-RDZ mode, you will see an empty map view of the University of Utah campus, with no Spectrum nor Radio objects. You will need to create some simulated radios and inject simulated data (see the instructions in the "Run Simulated OpenZMS Demos" section below).

Finally, the instructions seek to familiarize you with the OpenZMS CLI, and walk you through the process of loading simulated data into your OpenZMS instance to give you a feel for how it works, as well as give you data to explore. If you are using RDZ-in-RDZ mode, most of the "outer" POWDER-RDZ information base will be preloaded into your "inner" RDZ.

The User Guide can further help your explore the OpenZMS web UI and CLI.

Run Simulated OpenZMS Demos

The OpenZMS profile provides instructions that demonstrate how to use the CLI to create simulated Spectrum, Radio, and Grants, demonstrating how OpenZMS works even if you did not enable RDZ-in-RDZ mode to use with real radios over the air.

The Profile Instructions include a "Additional Instructions and Documentation" section near their end, with links to the profile's detailed tutorial walkthrough. You can work through this tutorial documentation in your OpenZMS experiment to experiment with creating simulated grants, injecting simulated monitor data, and observing grant revocation.

• Chapter 1: Experiment and Deployment Overview
• Chapter 2: Accessing the RESTful and gRPC APIs
• Chapter 3: Example Usage (CLI)
• Chapter 4: Managing OpenZMS Services

Run Spectrum Sharing Demos (RDZ-in-RDZ mode)

In the following sections, you will create multiple POWDER experiments to consume and monitor spectrum. These experiments will use your RDZ-in-RDZ experiment and its OpenZMS instance to manage and monitor spectrum, instead of the "outer" POWDER-RDZ OpenZMS instance.

The demonstration scenarios assume that you have an OpenZMS experiment in RDZ-in-RDZ mode running already. You will need to collect the following information from your RDZ-in-RDZ experiment's status page at the top of the Profile Instructions expandable blue panel, as show in the screenshot below:

• The zms-dst API endpoint link value
• The admin password
• The powder token

You will also need to collect the following information from your RDZ-in-RDZ experiment's status page in the top-most blue box:

• Name (which you, or POWDER if you did not, assigned to the experiment)
• Project (in which you created the experiment)

You will provide these values to subsequent experiments so that they use your RDZ-in-RDZ experiment to safely allocate and monitor spectrum.

Smart Transmitter Demo

This demonstration requires both radios in a single POWDER fixed endpoint.

Create a Monitor Experiment

First, create a monitoring experiment using our RDZ "on-demand" monitor profile. This will allow you to observe the smart transmitter's low power transmissions, since the radio antennas are only separated by 2-3 feet.

In the Parameterize step:

• Choose a Radio: click the + button next to the Radio parameter, and select the Nuc1 node corresponding to the Fixed Endpoint name that you have chosen.

  TIP

  Make sure that both nuc1 and nuc2 are available at the Fixed Endpoint you choose, or that you have a reservation for them both.

• Set the Run Count parameter to 0.

• Set the OpenZMS DST URL parameter to the URL you obtained from your RDZ-in-RDZ experiment status page's instructions.

• Set the OpenZMS Token input to the powder user token you obtained from your RDZ-in-RDZ experiment status page's instructions.

You can start this experiment as soon as you can extract the necessary information from the RDZ-in-RDZ experiment's status page. If this experiment completes setup before the RDZ-in-RDZ experiment, its first several Observation reports will not be processed by the inner OpenZMS; that is fine. This profile uses a custom disk image with the necessary SDR drivers and firmware, and so takes a short amount of time to configure.

Once your experiment finishes configuring, it will begin monitoring the target spectrum range and sending power spectral density data to OpenZMS as Observations. If you return to your OpenZMS status page, you should see one of the radio location markers flash yellow briefly as monitor data comes in. Click on the dot: this will bring up a popup that shows you all radios present at this location. One of the radios should have a row named Demand Monitor with a link followed by a disk icon.

Click the disk icon, and scroll down below the map, you will see the current Observation. If you wait 10-15 seconds, you will see the next Observation automatically load. You can click on the Observation, and below, a detailed, unsmoothed version of the data will show. You can zoom on these panels using your mouse wheel or the scroll bar beneath them.

Create a Smart Transmitter Experiment

Second, create a "smart transmitter" experiment using our RDZ "smart transmitter" profile.

This profile will create an experiment that transmits a simple OTA signal over its SDR. Because both the transmitter and monitor radios are located closely together (antenna separation of 2-3 feet), the monitor will be able to observe the signal, even at lower power.

This experiment's spectrum will be allocated from your "inner" RDZ-in-RDZ experiment's OpenZMS, instead of the "outer" or "root" POWDER-RDZ OpenZMS. Your RDZ-in-RDZ experiment is effectively "subleasing" the grant of spectrum it received from the outer RDZ. This mode of operation uses the same POWDER-RDZ integration software that connects POWDER and its "outer" OpenZMS---but instead of using the outer RDZ to create a grant for the smart transmitter experiment, POWDER contacts the inner RDZ instead.

In the Parameterize step:

• Choose a Fixed Endpoint: click the + button next to the Fixed Endpoint parameter, and select the name of the endpoint that corresponds to the monitor experiment you created above.

  TIP

  Make sure that both nuc1 and nuc2 are available at the Fixed Endpoint you choose, or that you have a reservation for them both.

• Set the Frequency Min parameter to 3358.0, which is the beginning of the lower C-band range that POWDER is authorized to use under its FCC Innovation Zone designation.

• Set the Frequency Max parameter to 3550.0, which is the beginning of the US CBRS band. (POWDER is authorized to use the CBRS band from 3550-3700 in the absence of incumbent activity under its FCC Innovation Zone designation, but for this demonstration we will focus on lower C-band.)

• Set the Frequency Width parameter to 0.4. (You could use a larger width if your RDZ-in-RDZ experiment requested more than 1MHz bandwidth.)

• Set the Power parameter to 19.5, which is a safe upper bound on the output power of the NI B210.

• Toggle the Run the RDZ grant reallocation test parameter. This is what makes your transmitter "smart": it will cause a daemon to run on the SDR host that will listen for grant events from the "inner" OpenZMS in the RDZ-in-RDZ experiment. If the daemon sees that the grant has been revoked, it must cease transmission. If the daemon sees that the grant has been replaced, it will reconfigure to use the new operational parameters in the replacement grant before transmitting again.

• Set the Inner RDZ parameter to a simple string composed of the Project in which you instantiated your RDZ-in-RDZ experiment, a ,, and the Name you gave to your RDZ-in-RDZ experiment. (If you did not provide a name when you created your RDZ-in-RDZ experiment, POWDER automatically assigned one.) You can find this information on your RDZ-in-RDZ experiment's status page.

Here is an example of the proper parameters that use the RDZ-in-RDZ experiment created in the prior steps:

You can start this experiment as soon as you can extract the necessary information from the RDZ-in-RDZ experiment's status page. It will wait until the RDZ-in-RDZ experiment has completed setup---meaning, until its "inner" OpenZMS is running and fully populated with radio and spectrum information from the "outer" or "root" OpenZMS that globally runs the POWDER-RDZ.

TIP

Before you click the Finish button to create your smart transmitter experiment, make sure that you have your RDZ-in-RDZ experiment's OpenZMS web interface visible, and are watching the status page. As POWDER creates your smart transmitter experiment, it will use your RDZ-in-RDZ experiment to create a grant of spectrum.

When that happens, several events will pop up briefly in the upper right corner, informing you of the new grant and its transition into the active state. Notice also that there is now a Grant of 0.4MHz in the Grants subpanel to the left of the map. The following figure shows this happening:

If you had browsed to another view on your OpenZMS status page, click again on the blinking yellow location marker on the map, and scroll down to view the Observation stream again.

Notice that there is now a narrow orange vertical line at the frequency range where your "inner" OpenZMS allocated the grant that POWDER-RDZ created for your smart transmitter experiment. If you click as closely on that line as possible, and scroll to the unsmoothed, zoomed-in view below, and use your mouse wheel to zoom in further on the orange range, you should see a narrow transmission---this is the SDR transmitting according to the grant your "inner" OpenZMS allocated. You should see a strong signal from the smart transmitter:

To summarize what happened:

• When you created your smart transmitter experiment, POWDER requested a grant for it from your "inner" RDZ-in-RDZ OpenZMS;

• POWDER communicated the grant information to the SDR host using its standard experiment management flow

• The smart transmitter daemon running on the SDR host parsed the grant information, began transmitting according to the grant's operational parameters

• The smart transmitter daemon subscribed to your inner OpenZMS's event stream for lifecycle events that signal changes to that grant: e.g., if it is revoked, replaced, paused, or deleted---and it will respond accordingly---because you toggled the Run the RDZ grant reallocation test parameter.

Forcing a Grant Replacement: a Higher-priority Incumbent Displaces the Smart Transmitter Grant

OpenZMS is designed to support a variety of coexistence and multi-priority incumbent scenarios. OpenZMS grants themselves may have different priority, and higher-priority incumbents or spectrum allocations may also be modeled as Claims with their own priorities. (Internally, an OpenZMS Claim is a wrapper around a Grant, and this allows the OpenZMS scheduler to analyze conflicts between grants and claims, and activate highest-priority grants or claims, while pending lower-priority conflicting grants or claims until they become the highest priority in their conflict set.)

Because you toggled the Run the RDZ grant reallocation test parameter when you created the smart transmitter experiment, POWDER-RDZ has subscribed to events associated with the smart transmitter's grant (as has the daemon operating the smart transmitter in accordance with the grant's operational parameters). If a higher-priority, conflicting incumbent (modeled as an OpenZMS Claim) becomes active, the smart transmitter's grant will be placed in the pending state. Below, we will create a Claim with the exact frequency range of the smart transmitter grant, but with a higher priority. When this happens:

• POWDER-RDZ will attempt to Replace the grant with a new grant allocated by your RDZ-in-RDZ OpenZMS. In its request, POWDER-RDZ will use the same wide frequency range and narrow bandwidth as when requesting the original smart transmitter grant. This allows your RDZ-in-RDZ OpenZMS scheduler to find unallocated spectrum somewhere in this range. In this case, if you have used the default parameters to these experiments, your RDZ-in-RDZ has a 1MHz grant, and has sub-granted 0.4 MHz of that to your smart transmitter---leaving 0.6 MHz free for a replacement grant.

• The smart transmitter will see that its grant is being replaced and cease transmissions. When the replacement grant requested by POWDER-RDZ is successfully scheduled, the smart transmitter will receive an event carrying the new grant's operation parameters, and it will reconfigure the transmitter (e.g. to the new frequency range) and begin transmission once again.

  TIP

  Either the smart transmitter or POWDER-RDZ could have requested the replacement grant, depending on the nature of experiment being run. In this case, we want POWDER-RDZ to request the replacement, since POWDER is providing the experiment automation facilities---as well as safety features to power off transmitters in the event of a grant violation.

• As POWDER-RDZ replaces the smart transmitter experiment's grant, you will see event notifications pop up in your RDZ-in-RDZ OpenZMS dashboard. Make sure to click back to the Observation feed from your monitor experiment, because on the monitor sweep after the replacement is scheduled, you will see that the smart transmitter has stopped transmitting on the original grant's frequency, and has moved to the replacement frequency. You will see the overlaid orange boxes denoting the grant change as the transmission begins on the replacement grant's frequency.

To try this out, in your RDZ-in-RDZ OpenZMS dashboard, open in a new tab the Claims submenu item in the Admin section of the left navbar. (Ideally, you would have a split-window view where you can see the dashboard as well as the Claim form.) Click the circle-+ button in the upper right corner below the top bar, and fill in the form as follows:

• Select the powder Element
• Give your claim a Name (e.g. claim-1)
• Use that name as the Description
• Enter manual for both Type and Source
• Set External ID to the Name you entered
• Leave Priority as the default (1022)
• For Min Frequency, enter the smart transmitter grant min frequency
• For Max Frequency, enter the smart transmitter grant max frequency
• For Max eirp, enter 19.5, as you did in the POWDER parameter picker when creating the smart transmitter experiment originally

The following screenshot shows an example of this:

Then scroll down and click Create---after reading the paragraph below:

TIP

A number of event notifications will be shown rapidly in the OpenZMS dashboard; watch closely to ensure you don't miss the action. Make sure to click on the blinking yellow Location marker if you had clicked away---and click on the current grant in the PSD, scroll down to the zoomed-in view of the data, and further zoom in. The orange (grant) and pink (claim) boxes will be overlaid on the PSD graph, and you will see them change.

First, the Claim will be created, and the existing Grant will be immediately placed in the pending state. When this happens, the PSD will be overlaid with a pink box (the Claim, now at the exact frequency space as the Grant), and the orange box will have vanished (since the Grant is no longer allowed to transmit):

Second, shortly thereafter, you will see that a new Grant has been created (by POWDER-RDZ), with the same name as the original Grant, and that it has been approved and started. The original grant will be revoked, and shown in red text. Note that there is now both a pink box (the Claim) and a new orange box (the replacement Grant) overlaid on the PSD:

Third, shortly thereafter, as the monitor's next observations arrive, you will see that the smart transmitter has relocated and its transmission is now within the new orange box---and not in the pink box (the higher-priority claim, representing the incumbent):

Forcing a Grant Violation: Instruct the Smart Transmitter to Ignore Grant Events

POWDER-RDZ provides inline, coupled SDR-based monitors for the vast majority of its user-allocable transmitting SDRs. These monitors capture a feed of the transmissions from the user-allocable SDRs and analyze them to ensure compliance with the experiment's allocation of spectrum. If the experiment smart transmitter transmits outside its allocation, POWDER-RDZ will quickly power off the radios.

Normally, the smart transmitter complies with all grant state changes, ceasing or shifting transmissions as instructed by the OpenZMS event stream. However, when you run a simple touch /tmp/violate on the smart transmitter SDR compute host, the smart transmitter will stop complying with grant state changes. For instance, during the grant replacement exercise in the prior session, because POWDER-RDZ requested the grant replacement, it was able to reconfigure its inline monitoring algorithm with the replacement grant operating parameters---adjusting to the newly-granted frequency range. However, if the smart transmitter had not complied, the inline monitor would have tagged the Observation it sends to OpenZMS as a violation.

We will now delete the first claim, create the violation file, and monitor the smart transmitter in the OpenZMS dashboard.

• Delete the first claim: in the same OpenZMS window or tab in which you created claim-1, click the pencil-paper icon to Edit the Claim, scroll down, and click Delete. In the OpenZMS dashboard, the pink claim will no longer be overlaid on the observation PSD graph.

• Create the violation file on the smart transmitter host: browse to your POWDER smart transmitter experiment status page, click on the single node in the Topology View, and click Shell in the popup menu (or use the List View and gear icon to open a Shell). In the web ssh shell that pops up, enter touch /tmp/violate and hit Enter. Then you can watch the smart transmitter log by entering tail -F /local/logs/tx-wrapper.log.

  

  

• Return to the split-window mode where you are watching on one side the OpenZMS dashboard and observation feed, and are ready to create a new claim in the other window.

• Create a new claim (e.g. claim-2) in the powder element that has the same start/end frequencies as the replacement grant, and max eirp of 19.5 as before.

  

After creating the Claim, in the OpenZMS dashboard, you will see a number of events. First, you will see that a new claim has been started, and has displaced the replacement grant. The pink box (second claim) is now overlaid on the PSD, and the orange box (replacement grant) has been removed, since it is now in the pending state:

Shortly thereafter, you will see additional events announcing that POWDER-RDZ has requested a new replacement grant to replace the original replacement, and that the latter has been revoked as the new replacement has been approved. Note the presence of the new orange box (new replacement grant) on the PSD, although notice that the transmission has not yet moved to the new frequency:

However---this time the smart transmitter will not reconfigure to the new replacement grant's operational parameters---it will maintain its current transmission. The inline monitor performs a full sub-6GHz scan, so it may take another minute or two for a new inline monitor observation to arrive. When it does, you will see events announcing the revocation of the new replacement grant, since the smart transmitter did not relocate its transmission, and thus the grant is in violation:

If you continue to monitor the observation stream, soon you will see that the transmission is no longer detected:

Internally, your RDZ-in-RDZ OpenZMS processed the inline monitor's violation-tagged observation and revoked the grant. POWDER-RDZ saw this event and immediately powered off radios in the offending experiment (note the not ready tan box in the List View), causing the transmission to stop:

Finally, in the same window in which you created the second claim, click the Observations left navbar entry in the Admin section. In the upper right, above the list of Observations, toggle the Violation checkbox twice until it has a check mark. Click the leftmost clock icon in the first row of results. This will show you the violating observation:

At this point, you should Terminate your smart transmitter experiment; and if you are not planning to re-run it to explore further, also terminate your monitor experiment.

Smart 5G "In A Box"

TODO

This feature has not yet been implemented and is blocked on

• openzms/zms-profile #1

Please monitor these issues or contact us us for more information.

Smart 5G with Mobile UEs

TODO

This feature has not yet been implemented and is blocked on

• openzms/zms-profile #1

Please monitor these issues or contact us us for more information.