omcipcap 0.2.5

OMCI analysis and MIB diff tools

omcipcap

omcipcap is a professional Python toolkit designed for analyzing and diagnosing ITU-T G.988 OMCI (ONT Management and Control Interface) protocols. It streamlines the process of identifying non-standard Managed Entities (MEs) and provisioning failures in GPON/XGS-PON packet captures, to visualizing network topology, decoding VLAN logic, and tracing upstream T-CONT traffic flows.

Key Features

• omcipcap check: Automatically scans pcap/pcapng files to highlight:
  • Vendor-Specific MEs: Identifies MEs in reserved or proprietary ranges.
  • Provisioning Failures: Detects non-success response codes (e.g., UNKNOWN_ME, INSTANCE_EXISTS).
  • Intelligent Filtering: Quickly isolate issues using --only-vendor or --only-failed flags.
  • RTT Latency Analysis: Automatically calculates the time difference between Request and Response. Users can flag slow packets using the --rtt-threshold (default: 1s).
• omcipcap diff: is a powerful utility for performing Differential Analysis between two MIB snapshots. It is specifically designed to help firmware engineers identify configuration drifts
  • Dynamic ME Extension: Use the --mib-json flag to dynamically load and overwrite ME definitions. This transforms raw hex data into readable fields without modifying the source code.
• omcipcap graphic: generates an interactive, hierarchical network topology from a MIB snapshot. It is designed to visualize the complex logical relationships between Managed Entities (MEs), helping engineers verify provisioning flows from the UNI/Management side to the ANI/T-CONT side.
• omcipcap vlan_tbl: Provides a deep-dive analysis of VLAN Tagging Filter Data and VLAN Tagging Operation Configuration Data. It decodes the complex, table-driven logic of OMCI VLAN processing into a human-readable format.
  • Logic Reconstruction: Automatically parses Filter/Treatment bit-fields to visualize how the ONU handles Untagged, Single-tagged, and Double-tagged frames.
  • Semantic Mapping: Translates raw hex values into clear actions (e.g., Insert 1 tag, Modify VID, Discard).
  • ME Association: Links VLAN rules directly to their associated Managed Entities, such as Physical Path Termination Points (PPTP) or MAC Bridge Ports, showing the exact association mode and instance IDs.
  • Detailed Bit-Field Breakdown: Includes a technical view of internal bit-fields (Filter/Treatment/Tags Removed) for senior engineers to verify exact hardware-level logic.
• omcipcap tcont_flow: Traces the complete upstream traffic path from T-CONT to GEM ports, displaying Alloc-ID assignment status, associated Priority Queues (upstream/downstream), and traffic shaping parameters in a tree-structured view.
  • T-CONT Activation Status: Instantly identifies unassigned T-CONTs (Alloc-ID = 0xFFFF) versus active ones.
  • GEM Port Mapping: Shows each GEM port bound to the T-CONT with its upstream and downstream Priority Queue linkage.
  • Traffic Parameters: Displays CIR/PIR bandwidth and scheduling policy per Priority Queue for quick QoS verification.
• Professional Output: Features color-coded Terminal output and standardized hex formatting for Instance IDs.

Why Use omcipcap?

omcipcap is built to bridge the gap between complex raw protocol data and actionable engineering insights. It significantly reduces the time required for root-cause analysis in both lab and field environments.

Key Impact: Transform hour-long manual packet tracing into seconds of automated analysis, allowing engineers to focus on fixing bugs rather than finding them.

Project Structure

.
├── examples                # pcap and json samples
│   ├── iphost_graphic.png
│   ├── mib_after.pcap
│   ├── mib_before.pcap
│   ├── mib_omcc_96.pcap
│   ├── mib_omcc_a0.pcap
│   ├── mib_vendor_v1.pcap
│   ├── mib_vendor_v2.pcap
│   ├── omcicheck_example.pcap
│   ├── omcicheck_example.png
│   ├── omcivlan.png
│   ├── pptp_graphic.png
│   └── vendor_355.json
├── LICENSE                 # MIT License
├── omci                    # Core package
│   ├── cli.py
│   ├── __init__.py
│   ├── omcigrapher.py
│   ├── omcimib.py
│   ├── omci.py
│   └── omcivlan.py
├── pyproject.toml          # Build system & entry points
├── README.md               # Project documentation 
└── tests                   # Test suites & pcap generators
    ├── generate_omcicheck_example.py
    ├── generate_omcidiff_example.py
    └── test_omci_exceptions.py

Installation

Option 1: Virtual Environment (Recommended for Development) Use this method to keep your system Python environment clean and isolate dependencies.

# 1. Create and activate the virtual environment
python3 -m venv venv
source venv/bin/activate

# 2. Upgrade pip and install in editable mode
pip install --upgrade pip
pip install -e .

# 3. Verify the installation
omcipcap --help

Option 2: Local Directory Installation (Permanent Use) Use this method to make the tool available across your system without activating a venv.

# 1. Install to your local directory
pip install . --prefix=${HOME}

# 2. Update your shell configuration (~/.bashrc or ~/.zshrc)
export PATH="${HOME}/local/bin:$PATH"
export PYTHONPATH="${HOME}/local/lib/python3.12/dist-packages:$PYTHONPATH"

# 3. Apply changes
source ~/.bashrc

⚡ Quick Start (No Python Required!)

Download Pre-compiled Binaries

Get ready-to-run executables for your platform:

• Windows (64-bit): omcipcap.exe
• Linux (64-bit): omcipcap_linux
• macOS (ARM64): omcipcap_mac

No Python installation required!

Windows and Linux Usage

# Windows
omcipcap.exe check your_file.pcap

# Linux
chmod +x omcipcap_linux
./omcipcap_linux check your_file.pcap

Sub-Command

omcipcap check

Analyze a pcap file to display a summary of all OMCI packets:

omcipcap check examples/omcicheck_example.pcap

omcipcap check with --rtt-threshold argument

(venv) $omcipcap check --rtt-threshold=1500 omcicheck_example.pcap 
Analyzing: omcicheck_example.pcap

No.    ID       Action             ME Class     ME Instance  Result                         RTT          Status           ME desc                                 
------------------------------------------------------------------------------------------------------------------------
38     19       MIB_UPLOAD_NEXT    241          0x0001                                      0                             Reserved for vendor-specific managed entities
40     20       MIB_UPLOAD_NEXT    350          0x0001                                      0                             Reserved for vendor-specific use        
52     26       MIB_UPLOAD_NEXT    500          0x000a                                      0                             Reserved for future standardization     
58     29       CREATE             84           0x0001       Err: INSTANCE_EXISTS (7)       0.000033                      VLAN tagging filter data                
59     30       SET                241          0x0001                                      0                             Reserved for vendor-specific managed entities
60     30       SET                241          0x0001       Err: UNKNOWN_ME (4)            0.000032                      Reserved for vendor-specific managed entities
64     32       GET                257          0x0000                                      0            [TID_DUPLOCATE]  ONT2-G                                  
------------------------------------------------------------------------------------------------------------------------
Summary: Found 2 failures, 5 Vendor packets, 1 duplicate packets, 0 late packets

omcipcap diff

Analyze two pcap files to identify differences in MIB provisioning

# Standard comparison
omcipcap diff examples/mib_vendor_v1.pcap examples/mib_vendor_v2.pcap

# Comparison with Custom Vendor ME definitions
omcipcap diff examples/mib_vendor_v1.pcap examples/mib_vendor_v2.pcap --mib-json examples/vendor_355.json

Example Output When comparing a vendor-specific configuration (Class 355), omcidiff provides a clear view of the state change:

[*] Successfully loaded 1 custom ME specs.
[*] Analyzing MIB from examples/mib_vendor_v1.pcap...
[*] Analyzing MIB from examples/mib_vendor_v2.pcap...

ME (Class, Inst)                    | Attribute                           | Pcap 1                -> Pcap 2
------------------------------------------------------------------------------------------------------------------------
[*] Reserved for vendor-specific (355, 0) | CPE mode                            | 'HGU'                -> 'SFU'
[*] Reserved for vendor-specific (355, 0) | Support VOIP                        | 0x1                  -> 0x0
------------------------------------------------------------------------------------------------------------------------

Advanced: Custom ME JSON Format To define your own Vendor MEs for the --mib-json flag, use the following structure:

{
  "355": ["HWTC 355 ME", [
    ["CPE mode", 3, "str", False],
    ["Support VOIP", 1, "u8", False]
  ]]
}

omcipcap graphic

omcipcap graphic omci.pcap

will generate output.html in current directory

omcipcap vlan_tbl

omcipcap vlan_tbl omci.pcap

List All ME 171 instances and detail of VLAN table

omcipcap tcont_flow

omcipcap tcont_flow examples/single_unit_1_tont_2_gem/single_unit_1_tont_2_gem.pcap

Traces the complete upstream traffic hierarchy from T-CONT → GEM Port → Priority Queue and displays bandwidth/scheduling parameters in a tree view.

Example Output:

GPON T-CONT Flow Analysis
├── T-CONT 32768 (alloc-id=1000)
│   ├── GEM 1001
│   │   ├── [US] PQ 32775 → up:CIR=0.128Mbps/PIR=9953.28Mbps
│   │   └── [DS] PQ 0 → Priority 0 dn:Unrestricted
│   └── GEM 1002
│       ├── [US] PQ 32768 → up:CIR=0.128Mbps/PIR=100Mbps
│       └── [DS] PQ 6 → Priority 6 dn:Unrestricted
└── T-CONT 32769 (Unassigned)

Each T-CONT entry shows:

• alloc-id: The Alloc-ID assigned by the OLT; Unassigned means the T-CONT has not been activated (Alloc-ID = 0xFFFF).
• GEM ports: All GEM Port Network CTPs bound to this T-CONT.
• [US] PQ: Upstream Priority Queue with CIR/PIR bandwidth limits.
• [DS] PQ: Downstream Priority Queue with scheduling priority.

Setup omcipcap on Windows Virtual Environment

1. Create the Environment Open your terminal in the project root directory and run:

python -m venv venv

2. Configure Execution Policy By default, Windows restricts running scripts like the activate file. If you see a PSSecurityException error ("scripts is disabled on this system"), run this command to allow local scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Select [Y] Yes when prompted. This is a one-time configuration.

3. Activate the Environment

.\venv\Scripts\activate

4. Install Dependencies (Development Mode)

pip install -e .

5. Verify the Tool

(venv) PS C:\Github\omci_utils> omcipcap -h
usage: omcipcap [-h] {check,diff,graphic,vlan_tbl} ...

OMCI PCAP Diagnostic & Analysis Tool

positional arguments:
  {check,diff,graphic,vlan_tbl}
                        Available analysis commands
    check               Analyze RTT, TID duplicates, and failures
    diff                Compare MIB snapshots between two pcaps
    graphic             Generate interactive topology HTML
    vlan_tbl            Analyze OMCI VLAN tagging logic (Table-driven)
    tcont_flow          Trace T-CONT -> GEM -> PQ traffic hierarchy

options:
  -h, --help            show this help message and exit

License & Copyright

Copyright (c) 2026 Dong Yuan, Shih [e-mail] Licensed under the MIT License.