RENEW Project Documentation

Version 1.0

Reconfigurable Ecosystem for Next-generation End-to-end Wireless

Manual: plot_hdf5.py

This script analyzes and plots a recorded HDF5 file from the Sounder. It checks the quality of the signal collected on the base station and visually checks whether the clients are sending good quality pilots and data or not. It calls the supporting modules from hdf5_lib.py.

You can also look into every individual pilot received in the whole dataset and analyze whether a particular pilot is good or not.

Usage format:

python3 plot_hdf5.py <hdf5_file_path_filename> --option(s)

Available options:

Users can use “python3 plot_hdf5.py –help” in the terminal to get a list of short option descriptions.

Option                               Description Default Available Range
–deep-inspect Performs a deep data analysis. It performs a channel analysis on the referenced frame, BS antenna and clients, validates all pilots for all clients, plots a frame map for good and bad frames, and frames’ starting indices per antenna. This option will take a minute or so to finish the five plots. Disabled Use this option to enable it.
–ref-frame=NUM Specify the index of the frame to be plotted. This frame will also be used as the reference frame in the auto correlation. 0 [0, n-frames]
Make sure to use the index within the range specified by n-frames.
If the user specifies it outside n-frames, the script shall throw a warning.
–ref-ant=NUM Specify the index of the reference BS antenna to be plotted. 0 [0, the number of BS antennas used in the experiment]
Note: Each BS Iris module can have two polarized antennas.
If the user specifies an antenna index outside the number of BS antennas used, the script shall abort.
–ref-user=NUM Specify the index of the reference client to be plotted. 0
If the user specifies a client index outside the total number of clients available, the script shall abort.
Note: Each Iris can act as two clients if both channels are used. The ref-user corresponds to each listed client’s channel. This is important to note when both channels on clients are enabled.
For example, ref-user 0 is the first client’s channel A; ref-user 1 is its channel B; ref-user 2 is the second client’s channel A; ref-user 3 is its channel B.
–n-frames=NUM Specify the number of frames to analyze. 2000 [1, the number of collected frames - frame-start]
If 0 is used, the script shall throw a warning and process the whole dataset, instead.
If the user specifies a number outside the total number of frames collected, the script shall analyze up to the maximum available number of frames.
–sub-sample=NUM Analyze frames by downsampling by sub-sample. For example, if n-frame is 1000 and sub-sample is 10, a total of 100 frames shall be analyzed. 1 A user can specify a number higher than 1 to speed up the data processing. However, it will miss fine-grained information.
–thresh=NUM Specify the amplitude threshold to detect a valid pilot for a frame. 0.001 If no valid pilot frame is detected, the script shall throw a no valid frames found error and abort.
–frame-start=NUM Specify the index of the frame from where we will start analyzing the number of frames defined by n-frames. 0 [0, the number of frames collected in the experiment]
Make sure that [frame-start, frame-start + n-frames] is within the range of the maximum number of frames collected.
–verify-trace Perform a quick inspection of the HDF5 file. It produces several charts in one plot to show the real and imaginary numbers of the selected frame and all frames specified in n-frames option. Enabled This option is always enabled by default. The user does not need to use it.
–analyze-trace Calculate and plot achievable bit rates for multi-user and single-user beamforming with zero-forcing and conjugate schemes. Disabled Use this option to enable it.

Usage examples:

Please see the usage examples in the Sounder experiment.

Last updated on 30 Jun 2020 / Published on 1 Jan 0001