omcipcap is a professional GPON/XGS-PON OMCI Semantic Analysis Framework for ITU-T G.988 protocols. By implementing a table-driven semantic engine, it transforms raw pcap data into structured, human-readable insights—covering MIB state auditing, VLAN logic decoding, and T-CONT traffic hierarchy tracing.

The Master branch represents the latest evolution, shifting from a standalone tool to an analysis framework:

• For AI & Programmers: Full support for JSON IR (-j / --json-output), making it easy to pipe MIB data into AI models or automation pipelines.
• For Field Engineers: The legacy v0.2.x-lts branch remains available for on-site troubleshooting with traditional CLI outputs.
• Dual-Mode Output: Every command supports Rich Print (for human diagnosis) and JSON (for machine processing).

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.

.
├── LICENSE         # MIT License
├── README.md       # Project documentation
├── examples        # pcap and json samples
├── omci            # Core package
├── pyproject.toml  # Build system & entry points
├── tests           # Test suites
└── utils           # pcap generators

pip install omcipcap

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
omcipcap.exe check your_file.pcap

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

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
 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   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   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        0.000033                     Reserved for vendor-specific managed entities
   64    32   GET               257        0x0000                                      0   [TID_DUPLICATE]   ONT2-G
 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Summary: Found 2 failures, 5 Vendor packets, 1 duplicate packets, 0 late packets

MIB Database Dump

Dump all or filtered MIB instances from a pcap.

omcipcap mibdb examples/omci.pcap
omcipcap mibdb --class-id 84,171 examples/omci.pcap
omcipcap mibdb --only-upload examples/omci.pcap

Analyze two pcap files to identify differences in MIB provisioning

omcipcap mibdb-diff mib_vendor_v1.pcap mib_vendor_v2.pcap
omcipcap mibdb-diff mib_vendor_v1.pcap mib_vendor_v2.pcap --mib-json examples/vendor_355.json
omcipcap mibdb-diff --full ont1.pcap ont2.pcap
omcipcap mibdb-diff --full --class-id=84,171 ont1.pcap ont2.pcap

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

(venv) $ omcipcap mibdb-diff mib_vendor_v1.pcap mib_vendor_v2.pcap --mib-json examples/vendor_355.json
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   Status         ME Name (ID)                                           Inst   Attribute          Pcap 1     Pcap 2
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
   MODIFIED       Reserved for vendor-specific use (355)                  0x0   CPE mode           HGU        SFU
   MODIFIED       Reserved for vendor-specific use (355)                  0x0   Support VOIP       0x1        0x0
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Summary: Added: 0, Removed: 0, Modified: 2

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 omci.pcap

will generate output.html in current directory

omcipcap vlan_tbl omci.pcap

List All ME 171 instances and detail of VLAN table

omcipcap tcont-flow 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:

(venv) $ omcipcap tcont-flow single_unit_1_tont_2_gem.pcap
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)
(venv) $

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.

Copyright (c) 2026 Dong-Yuan Shih daneshih1125@gmail.com Licensed under the MIT License.