Skip to content

User_Guide.md

Latest commit

 

History

History
277 lines (213 loc) · 19.5 KB

User_Guide.md

File metadata and controls

277 lines (213 loc) · 19.5 KB
Raw

User Guide

This guide provides a step-by-step walkthrough for using TAS-Forge — from setting up the software environment to generating schedules, running simulations, and analyzing results.

Before getting started, please ensure that all required tools (MATLAB, IBM CPLEX, and OMNeT++) are properly installed and configured, along with any necessary dependencies. For details on supported versions and setup instructions, refer to the Prerequisites section below.

For a deeper understanding of the tool's design, functionality, and scheduling model, see the Technical Overview documentation.

To review current limitations and known issues encoutered in the tool, refer to the Known Issues and Limitations page.

🌟 Prerequisites

For implementing TAS-Forge, it is vital that the following software tools are installed correctly and configured:

1. MATLAB

  • Required for: Topology generation, CPLEX and OMNeT++ code generation, TAS schedule creation, and performance analysis from simulation outputs.
  • Recommended Version: R2021b or later.
  • Installation Steps:
  • Tip: Ensure MATLAB is added to your system’s environment PATH if you intend to run it from the terminal.

2. IBM CPLEX

  • Required for: Solving TAS scheduling frameworks formulated as Integer Linear Programs (ILPs).
  • Recommended Version: CPLEX Optimization Studio 22.1.1 or later.
  • Installation Steps:
  • Note:
    • You may need to create an IBM account to access the download.
    • CPLEX must be run via the IBM GUI, as MATLAB integration is not supported in newer versions (22.x and beyond).
  • Helpful Resources:

3. OMNeT++

  • Required for: Simulating the generated network topology and validate the TAS schedule execution.
  • Recommended Version: OMNeT++ 6.0.3 or newer.
  • Dependencies: Requires INET version 4.4.
  • Installation Steps:
  • Note:
    • The .ned and .ini files generated by TAS-Forge should be imported in an OMNeT++ project for simulation.
  • Important:
    • To enable processing delays within network devices, modifications are required in the INET framework of OMNeT++. Please follow the steps outlined in the Modifications to INET page to complete the setup.
  • Helpful Resources:

4. TAS-Forge Repository

To get the project code:

 git clone https://github.com/AviroopGhosh/TAS-Forge.git

Or you can download it as a ZIP file and extract it.

📂 Folder Structure

    TAS-Forge/codes/
    ├── analyze_omnet_results.m                % Script to analyze the results generated from OMNeT++
    ├── function_generate_routes.m             % Function to generate pair of sources and sinks to form routes
    ├── function_generate_topology_map.m       % Function used to generate the topology map incl. source and destination ports
    ├── function_import_topology_data.m        % This funcition is used to import the topology-related data  
    ├── generate_CPLEX_code_NCA.m              % Generate CPLEX input files based on Network-Derived Clock Drift Adustment (NCD) scheduling framework
    ├── generate_CPLEX_code_NCD.m              % Generate CPLEX input files based on Network-Derived Clock Drift Delay (NCD) scheduling framework
    ├── generate_CPLEX_code_WCA.m              % Generate CPLEX input files based on Worst-case Adjustment (WCA) scheduling framework
    ├── generate_CPLEX_code_WCD.m              % Generate CPLEX input files based on Worst-case Delay (WCD) scheduling framework
    ├── generate_GCL_output.m                  % Generate Gate Control Lists (GCLs) based on the scheduling framework selected    
    ├── generate_network_system.m              % Starting script used to generate the network topology, routes and stream parameters
    ├── generate_omntepp_files.m               % Generates both NED and INI files for OMNeT++ simulation
    ├── generate_omnetpp_ini_file.m            % This script generates the INI file for simulation
    ├── generate_omnetpp_ned_file.m            % This script generates the NED file to load into OMNeT++ 
    ├── network_data.csv                       % Generated network data for scheduling (created by running generate_network_systems.m)
    ├── node_data.csv                          % Records clock drift values for nodes (created by running generate_network_systems.m)
    ├── output_CPLEX_solution_[sched].txt      % Decision variable output text file generated by CPLEX based on scheduler type
    ├── output_GCL_matrix.txt                  % Output of GCLs of all relevant egress ports (created by running generate_GCL_output.m)
    ├── port_connections.csv                   % Port connection list of all devices to neighbouring nodes (created by running generate_network_systems.m)
    ├── results.csv                            % The latency values output from OMNeT++ stored as a csv
    ├── stream_data.csv                        % Lists stream parameters incl. routes, periodicity, etc. (created by running generate_network_systems.m)
    ├── stream_data_output_[sched].csv         % Analysis of the results generated by OMNeT++ based on scheduler type (created by running analyze_omnet_results.m)
    ├── CPLEX_Code_Output/                     % Directory for all CPLEX model output files (created by running generate_network_systems.m)
        ├── output_CPLEX_code_NCA.mod          % CPLEX input file for NCA scheduling method (created by running generate_CPLEX_code_NCA.m)          
        ├── output_CPLEX_code_NCD.mod          % CPLEX input file for NCD scheduling method (created by running generate_CPLEX_code_NCD.m)  
        ├── output_CPLEX_code_WCA.mod          % CPLEX input file for WCA scheduling method (created by running generate_CPLEX_code_WCA.m)  
        ├── output_CPLEX_code_WCD.mod          % CPLEX input file for WCD scheduling method (created by running generate_CPLEX_code_WCD.m) 
    ├── OMNETpp_Code_Output/                   % Directory containing the ini and ned files (created by running generate_omnetpp_files.m)
        ├── generated_topology.ned             % Ned file generated
        ├── simulation_config_[sched].ini      % Ini file generated based on scheduler type

🌐 Recommendations & Requirements

Before you begin, please review the following recommendations to ensure a smooth experience with TAS-Forge.

To avoid path-related issues, it is strongly recommended that you start MATLAB in the TAS-Forge root directory (or the directory where all input and output files are expected to be located).

TAS-Forge relies on the file paths for reading and writing, including (but not limited to):

  • Reading the .csv and .txt files used to generate CPLEX and OMNeT++ scripts.
  • Reading outputs from the CPLEX and OMNeTpp files (such as, the input_CPLEX_solution_[sched].txt and results.csv) for further analysis.

Keeping all TAS-Forge scripts and related files in a single working directory helps avoid file-not-found errors and ensures proper linking between generation, scheduling, simulation and analysis steps.

To verify or change your current working directory in MATLAB, use the following commands:

pwd                             % Check current directory
cd 'your/path/to/TAS-Forge'     % Navigate to the TAS-Forge directory

🚨 Workspace Requirements:

Preserving the MATLAB workspace is critical. If the workspace is cleared or lost, you will need to restart the entire process from the beginning.

To safeguard your progress: Use the save command to save your workspace at any point during execution Use the load command to restore the workspace when you return to continue

Example:

save my_tas_forge_workspace.mat       % Save workspace
load my_tas_forge_workspace.mat       % Load workspace

🔒OMNeT++ Requirements:

Make sure your OMNeT++ project is correctly linked to the INET framework, as TAS-Forge simulations rely on its modules.

While it is not necessary to create custom packages, if you choose to do so, ensure they are placed in the correct directory structure recognized by OMNeT++.

🪜 Step-by-Step Guide: Using TAS-Forge

This section provides a step-by-step guide for using TAS-Forge. Before beginning, ensure that all the required files are present in your MATLAB working directory. To understand how the files are organized, refer to the Folder Structure section.

Note: Many files (e.g., CSV exports, CPLEX input, OMNeT simulation files) are generated during execution. These files will not appear until their corresponding scripts have been run. This will be highlighted in the respective steps.

💻 Step 1: Generate Network Topology and Stream Parameters

To being using TAS-Forge, run the following script in MATLAB:

    generate_network_system

The script will prompt the user to input:

  • Number of sources
  • Number of sinks
  • Number of switches

Once provided, the script will automatically create the following:

  • A linear network topology consisting of the network devices with a visually representative figure
  • A set of routes connecting each source to at least one or more sink nodes
  • Set of streams per route with the following properties:
    • Payload size
    • Transmission Periodicity
    • Deadline constraint

Note: Each source must be connected to at least one sink. Isolated devices (sources or sinks with no valid route) are not supported. If this occurs, the script will prompt a re-run with adjusted device settings. For more details, see the Known Issues and Limitations page.

The script exports the following files:

  • stream_data.csv - Contains configuration parameters for each time-sensitive stream, including payload, periodicity, and deadlines.
  • network_data.csv - Stores global network parameters such as hyperperiod, macroticks, synchronization periodicity etc.
  • node_data.csv - Contains randomly assigned clock drift values for each network node, used for the time synchronization and TAS scheduling process.
  • port_connections.csv- Contains information about each egress port in the network, including its connected neighboring device and the list of streams routed.

The script also executes all the following scripts. Each script generates a CPLEX-compatible text file containing the integer linear programming formulation for TAS schedule computation:

  • generate_CPLEX_code_NCA.m - Generates CPLEX input file based on the NCA scheduling method
  • generate_CPLEX_code_NCD.m - Generates CPLEX input file based on the NCD scheduling method
  • generate_CPLEX_code_WCA.m - Generates CPLEX input file based on the WCA scheduling method
  • generate_CPLEX_code_WCD.m - Generates CPLEX input file based on the WCD scheduling method

The generate_network_systems.m script automatically creates a directory CPLEX_Code_Output/, and the corresponding CPLEX model (.mod) files are generated:

  • output_CPLEX_code_NCA.mod
  • output_CPLEX_code_NCD.mod
  • output_CPLEX_code_WCA.mod
  • output_CPLEX_code_WCD.mod

🏗️ Step 2: Solve TAS Schedule using IBM CPLEX

This step is a manual process, as MATLAB does not currently support integration with the required version of IBM CPLEX.

Using the CPLEX model files generated in the previous step, select one of the scheduling frameworks (e.g., NCA, NCD, WCA and WCD) and run it using IBM CPLEX Optimization Studio.

Important: Before proceeding, ensure that CPLEX is properly installed and configured.

To execute the model file:

  1. Launch CPLEX Optimization Studio and create a new OPL Project.
  2. Add the corresponding .mod file generated in the CPLEX_Code_Output/ folder generated by TAS-Forge.
  3. Create a Run Configuration within the OPL project for the .mod.
  4. Run the model to compute the TAS schedule.

Once the model is executed, check the Problem Browser tab in CPLEX studio.

  • If the decision variables display "No Value", this indicates that the CPLEX model could not find a feasible solution.
  • Refer to the Technical Overview documentation for possible causes and rectifications.

If the model successfully generates decision varables, proceed with the following steps:

  1. Go to the Solutions tab in the output area at the bottom of CPLEX studio.

  2. You will see all the decision variables (e.g., OFF_1_source1,OFF_1_switch1,OFF_2_switch1, etc.).

  3. All the relevant decision variables will be automatiocally generated in your CPLEX OPL Projects space as a text file named: output_CPLEX_solution_[sched].txt

    Note: [sched] is the type of scheduler used (such as, NCA, WCA, NCD or WCD).

  4. Move this file into your MATLAB workspace directory where TAS-Forge is located.

  5. The decision variables will be in the format, VARIABLE_NAME = VALUE;, for example: OFF_1_source1 = 0; or OFF_1_switch1 = 10;.

🗒️ Step 3: Create Gate Control Lists (GCLs)

This step processes the output from CPLEX to create the Gate Control Lists (GCLs) used for TAS scheduling.

For successful GCL creation the following steps need to be followed:

  1. Run the script generate_GCL_output.m in MATLAB.

  2. The script will prompt to enter the type of scheduler type used in your CPLEX run, e.g. WCA,WCD,NCA,or NCD.

  3. Enter the scheduler name exactly as shown, the input is case-sensitive, an incorrect entry will result in an error.

  4. The script will then read the CPLEX output file from the decision variables pasted in output_CPLEX_solution_[sched].txt.

    Note: If any of the decision variables are missing or have not been read correctly from the CPLEX output then the script will terminate with an error indicating which variable could not be found. In that case, you will need to re-verify and add the missing decision variable from the CPLEX output before running the script again.

  5. The script will generate an output file Output_GCL_matrix.txt, which contains the computed GCLs.

  6. A schedulability cost metric will also be output as part of the result, providing insight into the efficiency of the generated schedule.

Important: If the script generates an error citing 'overlapping conditions' then refer to Known Issues and Limitations page for guidance.

Note: The Output_GCL_matrix.txt file contains a list of generated GCLs. Each line corresponds to the GCL for a specifc switch egress port and is aligned with the respective row in the port_connections.csv file. In this context:

  • Source refers to the switch device.
  • SourcePort indicates the egress port on which the GCL is applied.

All GCL entries are expressed in microseconds.

For an understanding on how to interpret the GCLs refer to the Technical Overview page.

🏭 Step 4: Generate Simulation Configuration

Following the previous step, this stage generates the required OMNeT++ simulation files, namely the .ned and .ini files.

Run the following script in MATLAB:

    generate_omnetpp_files

This script will:

  • Automatically create a new new directory OMNETpp_Code_Output if one doesn't already exist.
  • Interally call the scripts generate_omnetpp_ned_file.m and generate_omnetpp_ini_file.m to generate the necessary simulation files.
  • The script will not proceed if the previous steps have not been completed.

The script outputs the following:

  • A network topology map that visually represents the direction of flow of traffic defined in the generated .ned file.
  • The following output files are created in the OMNETpp_Code_Output directory: - generated_topology.ned representing the network structure in the OMNeT++ simulation. - simulation_config_[sched] representing the corresponding simulation configuration file, where [sched] indicates the specific TAS scheduling method used such as, WCD,WCA, etc.

The files generated in the OMNETpp_Code_Output can be imported into an OMNET++ project for execution.

Important: Ensure that you have completed the modifications required in INET from the Modifications to INET page first before proceeding to simulating in OMNeT++.

🔬 Step 5: Analyzing Simulation Results

After loading the .ned and .ini files in OMNeT++, run the .ini file to start the simulation.

Note: By default, the simulation executes for a duration of 1 second. To modify the simulation duration, adjust the sim-time-limit parameter in the .ini file.

Important: If the simulation generates an error citing clock synchronization overdue then refer to Known Issues and Limitations page for guidance.

After successful completion of the simulation:

  • Open the vector results generated by the OMNeT++ simulation.
  • Filter the results using 'meanBitLifeTimePerPacket:vector' in the results column.
  • These values represent the end-to-end latency of each frame, sorted by the stream as received at the sink.
  • Export the results and save the file as results.csv.
  • The .csv file should be visible in the Results section in Project Explorer in OMNeT++.
  • Move this file to your MATLAB directory containing the TAS-Forge files.

Following the steps above, run the analyze_omnet_results.m script.

Note: If you would like to renamed the results.csv differently, then please ensure that it is aligned with the inputfilename specification in analyze_omnet_results.m.

The script execution will generate the stream_data_output_[sched].csv file. [sched] is based on the scheduler type such as NCA,WCA,NCD,orWCD.

This file provides a detailed summary of the simulated results and performance of generated GCLs including:

  • The stream identifiers with the corresponding routes and intermediate devices.
  • Periodicity of each stream.
  • Payload size of the frames per stream.
  • Minimum end-to-end latency and analytical end-to-end latencies boundaries.
  • Measured end-to-end latency boundaries and jitter.
  • The number of hops in the network.

Note: All the timing parameters are expressed in microseconds.

✅ TAS-Forge is now fully set up. You can experiment with topology sizes, or stream properties to evaluate custom scenarios. For detailed understanding of system design and implementation decisions, refer to the Technical Overview page.