STRUCTURE | GETTING STARTED | RUNNING | TESTING | CHANGE CONTROL| CONTRIBUTING | LICENSING

vdif-tools

This repository is hosted at https://github.com/Smithsonian/ngeht-vdiftools

It contains VDIF-related tools initially developed to facilitate testing of the ngDBE (Digital Back End) by providing a way to extract VDIF data frames from PCAP captures.

Repository structure

Getting Started

These instructions will get a copy of the repository up and running on your local machine for local development and use.

Prerequisites

This section describes the things you need to build, test, and deploy the software and how to install and configure them.

Required tools

• Git 2.3 or higher
• Python 3.9 or higher

Setting up the environment

Here is a step by step guide to getting a development & execution environment up and running. They are provided assuming a UNIX environment; some adaptation may be required if you are running on another platform.

1. Create a Python virtual environment in a directory named .venv and activate it
   While you could do this without a virtual environment, it is not recommended

   $ python -m venv .venv
   $ source .venv/bin/activate
   (.venv) $ python -m pip install --upgrade pip

2. Install any required Python modules

   (.venv) $ pip install -r requirements.txt

You are now ready to develop and execute the application.

Running the software

1. Assure you are within the Python virtual environment you created

   $ source .venv/bin/activate

2. Run any tool, providing any necessary commandline arguments. You can see a list of arguments by running with the -h option.

   This assumes you are in the same directory as this README.md

   (.venv) $ python mock-dbe.py -h
   or
   (.venv) $ python pcap2vdif.py ethernet-vdifcap.pcap

Testing the software

Describe how to test the software. Use all pertinent sections below.

Manual tests

1. mock-dbe.py - VDIF capture generation

   1. Run Wireshark or tcpdump on your local machine to capture UDP traffic on a port of your choice
      (the default port is provided in the -h help for mock-dbe.py)

   2. Run mock-dbe.py with the sample.vdif file from the examples/ directory

      $ python mock-dbe.py examples/sample.vdif

   3. Save the output of Wireshark/tcpdump to a .pcap file

   4. Compare your .pcap file to the two .pcap files in the examples/ directory; they should be similar. They won't be exactly the same since there is PCAP metadata throughout the file that can differ from machine to machine. But it should be obvious that there are large chunks of identical data which should correspond to the VDIF data frames.

2. pcap2vdif.py - VDIF extraction

   1. Run pcap2vdif.py on either of the .pcap files in the examples/ directory

      $ python pcap2vdif.py examples/ethernet-vdifcap.pcap

   2. This should generate 8 .vdif files. You can individually compare them to examples/sample.vdif, or you can concatenate the 8 files together into a single file and compare that to examples/sample.vdif. Either way, each VDIF data frame should be identical.

Change control

The branches shown in the table below are associated with development milestones or otherwise have a policy requiring the branch content remain stable and therefore be kept under a level of change control. GitHub's branch protection rules are used to enforce change control for these branches.

See the Branch protection rules for details on the protection configuration for all branches. The typical configuration will require pull requests to be used to merge changes into a protected branch; no direct commits will be permitted. This allows an independent member of the team to review the changes and explain what requires attention. This workflow encourages a more regular code review process than might otherwise happen. The set of approvers is specified in the pull request.

Contributing

See CONTRIBUTING.md for details on the developer workflow for contributing changes to the software.

Licensing

See the LICENSE file for details on the licensing of this software.