omci_utils 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.
omcicheck: 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-vendoror--only-failedflags. - RTT Latency Analysis: Automatically calculates the time difference between Request and Response. Users can flag slow packets using the --rtt-threshold (default: 1s).
omcidiff: 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.
omcigraphic: 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.- Professional Output: Features color-coded Terminal output and standardized hex formatting for Instance IDs.
.
├── examples # pcap and json samples
│ ├── 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
│ └── vendor_355.json
├── LICENSE # MIT License
├── omci # Core package
│ ├── cli.py
│ ├── __init__.py
│ ├── omcimib.py
│ └── omci.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
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
omcicheck --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
Analyze a pcap file to display a summary of all OMCI packets:
omcicheck examples/omcicheck_example.pcap
omcicheck with --rtt-threshold argument
$ omcicheck --rtt-threshold=1100 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
62 31 GET 257 0x0000 Success 1.200000 [LATE] ONT2-G
64 32 GET 257 0x0000 0 [TID_DUPLOCATE] ONT2-G
------------------------------------------------------------------------------------------------------------------------
Summary: Found 2 failures, 5 Vendor packets, 1 duplicate packets, 1 late packets
$Analyze two pcap files to identify differences in MIB provisioning
# Standard comparison
omcidiff examples/mib_vendor_v1.pcap examples/mib_vendor_v2.pcap
# Comparison with Custom Vendor ME definitions
omcidiff examples/mib_vendor_v1.pcap examples/mib_vendor_v2.pcap --mib-json examples/vendor_355.jsonExample 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]
]]
}omcigraphic omci.pcap
will generate output.html in current directory
omcivlan omci.pcap
List All ME 171 instances and detail of VLAN table
- Create the Environment Open your terminal in the project root directory and run:
python -m venv venv- 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 CurrentUserSelect [Y] Yes when prompted. This is a one-time configuration.
- Activate the Environment
.\venv\Scripts\activate- Install Dependencies (Development Mode)
pip install -e .- Verify the Tool
(venv) PS C:\Github\omci_utils> omcicheck .\examples\omcicheck_example.pcap
Analyzing: .\examples\omcicheck_example.pcap
No. ID Action ME Class ME Instance Result ME desc
------------------------------------------------------------------------------------------------------------------------
38 19 MIB_UPLOAD_NEXT 241 0x0001 Success Reserved for vendor-specific managed entities
40 20 MIB_UPLOAD_NEXT 350 0x0001 Success Reserved for vendor-specific use
52 26 MIB_UPLOAD_NEXT 500 0x000a Success Reserved for future standardization
58 29 CREATE 84 0x0001 Err: INSTANCE_EXISTS (7) VLAN tagging filter
59 30 SET 241 0x0001 Success Reserved for vendor-specific managed entities
60 30 SET 241 0x0001 Err: UNKNOWN_ME (4) Reserved for vendor-specific managed entities
------------------------------------------------------------------------------------------------------------------------
Summary: Found 2 failures, Found 5 Vendor packetsCopyright (c) 2026 Dong Yuan, Shih daneshih1125@gmail.com Licensed under the MIT License.