# How to Create or Add New Hardware Variant Definitions to OCLP-Mod: A Complete Developer's Guide > Learn how to add new hardware variant definitions to OCLP-Mod. Follow our developer's guide to create Python classes and implement required methods for seamless integration. - Repository: [laobamac/oclp-mod](https://github.com/laobamac/oclp-mod) - Tags: how-to-guide - Published: 2026-03-05 --- **Adding a new hardware variant to OCLP-Mod requires creating a Python class that inherits from `BaseHardware` in the `oclp_mod/sys_patch/patchsets/hardware/` directory, implementing six required methods including `name()`, `present()`, and `patches()`, and placing the file in the appropriate category subdirectory to enable automatic discovery.** OCLP-Mod uses a plugin-based architecture to support diverse hardware configurations on macOS. Creating or adding new hardware variant definitions to OCLP-Mod involves extending the `BaseHardware` abstract base class to define detection logic and patch sets for unsupported GPUs, network cards, or audio devices. This guide walks through the exact file locations, method signatures, and implementation patterns used in the laobamac/oclp-mod repository. ## Create a New Subclass File in the Hardware Patchsets Directory Place your new hardware definition in the appropriate subdirectory under `oclp_mod/sys_patch/patchsets/hardware/`. The repository organizes variants by category: - `graphics/` — For GPU architectures (Intel, AMD, NVIDIA) - `networking/` — For Wi-Fi and Ethernet controllers - `audio/` — For sound cards and audio codecs - `misc/` — For other hardware types Name the file descriptively, such as [`my_new_gpu.py`](https://github.com/laobamac/oclp-mod/blob/main/my_new_gpu.py) or [`broadcom_wifi.py`](https://github.com/laobamac/oclp-mod/blob/main/broadcom_wifi.py). As a reference implementation, examine [`intel_skylake.py`](https://github.com/laobamac/oclp-mod/blob/main/intel_skylake.py) located at [`oclp_mod/sys_patch/patchsets/hardware/graphics/intel_skylake.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/graphics/intel_skylake.py), which demonstrates the standard structure for graphics variants. ## Inherit from BaseHardware and Import Required Modules Every hardware variant must subclass `BaseHardware` and import the core dependencies used for detection and patching. The standard import pattern mirrors existing variants in the repository. ```python from ..base import BaseHardware, HardwareVariant, HardwareVariantGraphicsSubclass from ...base import PatchType from .....constants import Constants from .....detections import device_probe from .....datasets.os_data import os_data ``` These imports provide access to the abstract base class, hardware category enumerations, patch type definitions, system constants, device detection utilities, and macOS version data. ## Implement the Required Abstract Interface The `BaseHardware` class in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py) defines six abstract methods that every subclass must implement. These methods enable OCLP-Mod to detect hardware presence, determine compatibility, and apply appropriate patches. - **`name(self) -> str`** — Returns a human-readable identifier displayed in the UI. Typical implementation: `return f"{self.hardware_variant()}: MyNew GPU"`. - **`present(self) -> bool`** — Detects whether the hardware exists on the current machine using `device_probe` helpers. For GPUs, use `self._is_gpu_architecture_present([device_probe.Intel.Archs.YourArch])`. - **`native_os(self) -> bool`** — Determines if macOS natively supports this hardware on the current version by comparing `self._xnu_major` against values in `os_data`. - **`hardware_variant(self) -> HardwareVariant`** — Returns the high-level category: `HardwareVariant.GRAPHICS`, `HardwareVariant.NETWORKING`, `HardwareVariant.AUDIO`, or `HardwareVariant.MISCELLANEOUS`. - **`hardware_variant_graphics_subclass(self) -> HardwareVariantGraphicsSubclass`** — Required only for graphics variants. Specifies the Metal support level, such as `HardwareVariantGraphicsSubclass.METAL_31001_GRAPHICS`. - **`patches(self) -> dict`** — Returns a dictionary of patch operations required for this hardware. Combine shared patches (like `MontereyOpenCL`) with model-specific overrides following the `PatchType` schema. ## Define Model-Specific Patches If your hardware requires file overrides beyond shared patches, implement a helper method commonly named `_model_specific_patches()`. This method returns a nested dictionary following the `PatchType` structure defined in the base classes. ```python def _model_specific_patches(self) -> dict: return { "MyNew GPU": { PatchType.OVERWRITE_SYSTEM_VOLUME: { "/System/Library/Extensions": { "AppleMyNewGPU.kext": "12.5", }, }, }, } ``` Reference the `_model_specific_patches` implementation in [`intel_skylake.py`](https://github.com/laobamac/oclp-mod/blob/main/intel_skylake.py) to see how model-specific kext overrides integrate with the broader patch dictionary. ## Extend Hardware Enums for New Categories If your variant introduces a completely new hardware category not covered by existing enumerations, you must extend the base definitions in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py). - Add new `HardwareVariant` enum members for novel categories (e.g., a new storage controller type) - Add new `HardwareVariantGraphicsSubclass` members for new GPU Metal support tiers Most implementations will reuse existing enum values rather than creating new ones. ## Enable Automatic Discovery OCLP-Mod discovers hardware variants automatically through Python's `pkgutil.iter_modules`. The patchset loader scans all `.py` files in the `patchsets/hardware/` tree at runtime. Simply placing your new file in the correct subdirectory makes it discoverable without explicit registration. If the project maintains an explicit `__all__` list in [`__init__.py`](https://github.com/laobamac/oclp-mod/blob/main/__init__.py) files, ensure you import your class there to maintain compatibility. ## Document and Test the New Variant Add a docstring to your module explaining the hardware support and update the project README to list the new compatibility. Test your implementation by running the detection logic directly: ```bash python -c "from oclp_mod.sys_patch import PatchsetLoader; print(PatchsetLoader().list_active())" ``` Verify that your class instantiates only when the target hardware is present and that `patches()` returns the correct dictionary structure for non-native macOS versions. ## Complete Implementation Example The following skeleton demonstrates a complete new graphics variant implementation. Save this as [`oclp_mod/sys_patch/patchsets/hardware/graphics/my_new_gpu.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/graphics/my_new_gpu.py): ```python """ my_new_gpu.py – detection and patching for "MyNew GPU" """ from ..base import BaseHardware, HardwareVariant, HardwareVariantGraphicsSubclass from ...base import PatchType from .....constants import Constants from .....detections import device_probe from .....datasets.os_data import os_data class MyNewGPU(BaseHardware): def __init__(self, xnu_major, xnu_minor, os_build, global_constants: Constants): super().__init__(xnu_major, xnu_minor, os_build, global_constants) def name(self) -> str: return f"{self.hardware_variant()}: MyNew GPU" def present(self) -> bool: # Detect the GPU by its PCI class/code or architecture return self._is_gpu_architecture_present( gpu_architectures=[device_probe.Intel.Archs.MyNewArch] ) def native_os(self) -> bool: # Assume support up to macOS Ventura return self._xnu_major < os_data.ventura.value def hardware_variant(self) -> HardwareVariant: return HardwareVariant.GRAPHICS def hardware_variant_graphics_subclass(self) -> HardwareVariantGraphicsSubclass: return HardwareVariantGraphicsSubclass.METAL_31001_GRAPHICS def _model_specific_patches(self) -> dict: return { "MyNew GPU": { PatchType.OVERWRITE_SYSTEM_VOLUME: { "/System/Library/Extensions": { "AppleMyNewGPU.kext": "12.5", }, }, }, } def patches(self) -> dict: if self.native_os(): return {} # Merge shared OpenCL patches with GPU-specific ones from ...shared_patches.monterey_opencl import MontereyOpenCL return { **MontereyOpenCL(self._xnu_major, self._xnu_minor, self._constants.detected_os_version).patches(), **self._model_specific_patches(), } ``` ## Key Files Reference Understanding these core files ensures your implementation aligns with the OCLP-Mod architecture: - **[`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py)** — Defines `BaseHardware`, `HardwareVariant`, and `HardwareVariantGraphicsSubclass`. This is the core abstract API that all hardware variants must implement. - **[`oclp_mod/sys_patch/patchsets/hardware/graphics/intel_skylake.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/graphics/intel_skylake.py)** — Concrete reference implementation showing how Intel Skylake graphics detection and patching works in practice. - **`oclp_mod/sys_patch/patchsets/hardware//.py`** — The destination path for your new variant, where `` is `graphics`, `networking`, `audio`, or `misc`. - **[`oclp_mod/datasets/os_data.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/datasets/os_data.py)** (or constants file) — Contains macOS version constants used by `native_os()` checks to determine support ceilings. ## Summary - **Create** a new Python file in the appropriate `oclp_mod/sys_patch/patchsets/hardware/` subdirectory (graphics, networking, audio, or misc). - **Subclass** `BaseHardware` and import required modules following the pattern in [`intel_skylake.py`](https://github.com/laobamac/oclp-mod/blob/main/intel_skylake.py). - **Implement** six required methods: `name()`, `present()`, `native_os()`, `hardware_variant()`, `hardware_variant_graphics_subclass()` (for GPUs), and `patches()`. - **Define** optional `_model_specific_patches()` for hardware-specific kext overrides using the `PatchType` schema. - **Extend** `HardwareVariant` or `HardwareVariantGraphicsSubclass` enums in [`base.py`](https://github.com/laobamac/oclp-mod/blob/main/base.py) only if introducing entirely new categories. - **Place** the file in the directory tree to enable automatic discovery via `pkgutil.iter_modules`—no explicit registration required. - **Test** using `PatchsetLoader().list_active()` to verify detection logic and patch output before submitting. ## Frequently Asked Questions ### What is the minimum number of methods I must implement to create a valid hardware variant? You must implement six methods defined in `BaseHardware`: `name()`, `present()`, `native_os()`, `hardware_variant()`, `patches()`, and for graphics hardware, `hardware_variant_graphics_subclass()`. The `present()` method is critical as it determines whether your patch set applies to the current machine using `device_probe` detection logic. ### Do I need to register my new hardware variant in an [`__init__.py`](https://github.com/laobamac/oclp-mod/blob/main/__init__.py) or configuration file? No explicit registration is required. OCLP-Mod uses `pkgutil.iter_modules` to automatically discover all Python files in the `oclp_mod/sys_patch/patchsets/hardware/` directory tree at runtime. Simply placing your file in the correct subdirectory makes it available to the patchset loader. ### How do I determine which `HardwareVariant` enum value to return? Return `HardwareVariant.GRAPHICS` for GPUs, `HardwareVariant.NETWORKING` for Wi-Fi/Ethernet controllers, `HardwareVariant.AUDIO` for sound devices, or `HardwareVariant.MISCELLANEOUS` for other hardware types. These values are defined in [`oclp_mod/sys_patch/patchsets/hardware/base.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/base.py) and control how the UI categorizes your patch set. ### Can I reuse existing patch sets like Monterey OpenCL in my new hardware variant? Yes. Import shared patch classes from `oclp_mod/sys_patch/patchsets/shared_patches/` (such as `MontereyOpenCL`) and merge their `patches()` dictionary with your `_model_specific_patches()` output in your `patches()` method implementation. This follows the DRY principle used throughout the laobamac/oclp-mod codebase.