====== Hardware Model Identification Guide ======

The hardware model string uniquely identifies the platform type of an edge node within ZEDEDA Cloud. It is used to apply the correct hardware configuration profiles, adapter assignments, and model-specific EVE-OS settings.

There are three methods to obtain it.

^ Method ^ When to Use ^ Prerequisites ^
| Method 1: USB Install Capture | Before or during initial EVE-OS provisioning. The model is written to the USB by the installer. | Bootable ZEDEDA USB installer, physical access to node |
| Method 2: EVE-OS Debug Container | Any node running EVE-OS — enrolled or not. Query hardware directly from the node via console. | Console access (VGA, serial, or VM hypervisor console) |
| Method 3: Global Marketplace Import | Hardware model already exists in the ZEDEDA Marketplace. Import directly, no node access needed. | ZEDEDA Cloud access, model available in Marketplace |

----

===== Method 1: USB Install Capture =====

When EVE-OS installation completes, the installer writes hardware information to the USB drive inside a directory called ''INVENTORY''. Within INVENTORY there is a UUID-named subdirectory that acts as the soft serial number for the device. That directory contains ''controller-model.json'', which holds the full hardware specification including the model string.

==== USB Directory Structure ====

After a successful install the USB drive will contain the following structure:

<code>
INVENTORY/
  4af273db-3964-4e43-8771-053c01e6bd29/   <- device soft serial (UUID)
    controller-model.json                 <- hardware model + full IO spec
    controller-model-usb.json
    controller-model-verbose.json
    hardwaremodel.txt
    iommu_groups.out
    summary.log
    installer.log
</code>

> **Note:** The UUID directory name is the soft serial number for the device. It can be used to identify the node in ZEDEDA Cloud if needed.

==== Steps ====

**Step 1 — Boot the node from the ZEDEDA USB installer**

Insert the USB installer and boot the target edge node. The installer runs automatically and probes the hardware.

**Step 2 — Wait for installation to complete**

Allow the installer to finish. It writes EVE-OS to the local disk and populates the INVENTORY directory on the USB before rebooting. Do not remove the USB until the reboot begins.

**Step 3 — Remove the USB drive and plug it into another machine**

After the node reboots, remove the USB and connect it to any machine that can browse its filesystem. The INVENTORY directory is on the FAT partition and is readable on Windows, macOS, or Linux without additional tools.

**Step 4 — Open the UUID subdirectory inside INVENTORY**

Browse into INVENTORY and open the UUID-named subdirectory (e.g. ''4af273db-3964-4e43-8771-053c01e6bd29''). This UUID is the soft serial number of the node.

**Step 5 — Read controller-model.json**

Open ''controller-model.json''. The hardware model string is in the ''productURL'' field at the top level:

<code json>
{
  "arch": 2,
  "productURL": "HP Z2 Mini G9 Workstation",
  "productStatus": "production",
  "attr": { "memory": "64007M", "Cpus": "16", ... },
  "ioMemberList": [ ... ]
}
</code>

> **Tip:** ''controller-model.json'' also contains the full IO adapter list (ioMemberList), memory, CPU count, and IOMMU group assignments. This file is the primary input when creating a hardware model profile in ZEDEDA Cloud.

**Step 6 — Create the hardware model in ZEDEDA**

With ''controller-model.json'' in hand, use ZCLI to create the hardware model in ZEDEDA Cloud.

----

===== Method 2: EVE-OS Debug Container (spec.sh) =====

Any node running EVE-OS can use this method — enrollment in ZEDEDA Cloud is not required. The EVE debug container is always running. Access it via console and run ''spec.sh'' to capture the full hardware specification.

==== Prerequisites ====

  * Node running EVE-OS (enrollment in ZEDEDA Cloud is not required)
  * Console access to the node — VGA, serial, or VM hypervisor console
  * The EVE debug container is always running on any EVE-OS node

==== Steps ====

**Step 1 — Access the EVE-OS node console**

Access the node via one of the following console methods:

  - **VGA** — connect a monitor and keyboard directly to the node
  - **Serial** — connect via serial cable at 115200 baud 8N1
  - **VM console** — use the hypervisor console (e.g. virt-manager, Proxmox console, vSphere console). Also works for EVE running as a VM.

**Step 2 — Enter the EVE debug container**

The EVE debug container is always running. Enter it with:

<code bash>
eve enter debug
</code>

**Step 3 — Run spec.sh and redirect output to a file**

Once in the EVE debug container shell, run ''spec.sh'' and redirect the output to a file in ''/persist'' so it can be retrieved:

<code bash>
spec.sh > /persist/controller-model.json
</code>

> **Note:** ''/persist'' is a writable volume that survives across the debug container session. Name the file appropriately for the hardware being captured (e.g. ''hw-z2mini-g9-model.json'').

**Step 4 — Retrieve the file**

Retrieve the saved file using one of two methods:

//Option A — SCP from inside EVE to a remote machine://

<code bash>
cd /persist
scp controller-model.json user@192.168.x.x:/var/tmp/
</code>

//Option B — Copy/paste from console://

If the console supports copy/paste, print the file and copy it directly:

<code bash>
cat /persist/controller-model.json
</code>

**Step 5 — Locate the productURL field in the output**

Open the retrieved file. The hardware model string is in the ''productURL'' field at the top level. Below is an example from a Proxmox VM running EVE-OS — ''productURL'' shows ''"not found"'' for VMs since there is no physical SMBIOS product string:

<code json>
[debug] root@linuxkit-02e0ee2cc810:/$ spec.sh
{
  "arch": 2,
  "productURL": "not found",
  "productStatus": "production",
  "attr": {
    "memory": "15718M",
    "storage": "200G",
    "Cpus": "12",
    "watchdog": "false",
    "hsm": "1",
    "leds": "0"
  },
  "logo": {
    "logo_back": "/workspace/spec/logo_back_.jpg",
    "logo_front": "/workspace/spec/logo_front_.jpg"
  },
  "ioMemberList": [
    {
      "ztype": 7,
      "phylabel": "VGA",
      "assigngrp": "",
      "phyaddrs": { "PciLong": "0000:00:02.0" },
      "logicallabel": "VGA",
      "usagePolicy": {}
    },
    {
      "ztype": "IO_TYPE_USB_CONTROLLER",
      "phylabel": "USB",
      "assigngrp": "group",
      "phyaddrs": { "PciLong": "0000:00:01.2" },
      "logicallabel": "USB",
      "usagePolicy": {}
    },
    {
      "ztype": 1,
      "usage": 1,
      "phylabel": "eth0",
      "logicallabel": "eth0",
      "usagePolicy": {},
      "cost": 0,
      "phyaddrs": { "Ifname": "eth0" }
    },
    {
      "ztype": 1,
      "usage": 1,
      "phylabel": "eth1",
      "logicallabel": "eth1",
      "usagePolicy": {},
      "cost": 0,
      "phyaddrs": { "Ifname": "eth1" }
    }
  ]
}
[debug] root@linuxkit-02e0ee2cc810:/$
</code>

> **Note:** ''productURL'' of ''"not found"'' is expected for VMs (no physical SMBIOS). For physical hardware it will contain the vendor model string (e.g. ''"HP Z2 Mini G9 Workstation"''). The full ''ioMemberList'' in the file is what ZEDEDA uses when creating a hardware model profile — share the complete file, not just the ''productURL''.

**Step 6 — Exit the debug container and create the model**

Exit the debug container when done:

<code bash>
exit
</code>

With the file retrieved, use ZCLI to create the hardware model in ZEDEDA Cloud.

----

===== Method 3: Global Marketplace Import =====

If your hardware model already exists in the ZEDEDA Global Marketplace, it can be imported directly into your project without any node access.

Navigate to **Infrastructure > Hardware Models > Import from Marketplace** in the ZEDEDA Cloud portal. Search by vendor or model name, review the IO adapter assignments, and click Import to add it to your project.

> **Note:** Importing a model from the Marketplace creates a local copy within your project. You can review and edit adapter configurations after import if your deployment requires any adjustments.

----

===== Quick Reference =====

^ Method ^ Key Command / Action ^ Where to Find the Model ^
| USB Install Capture | Browse USB: ''INVENTORY/<uuid>/controller-model.json'' | ''productURL'' field in ''controller-model.json'' |
| EVE-OS Debug Container | ''eve enter debug'', then ''spec.sh > /persist/controller-model.json'' | ''productURL'' field in output |
| Global Marketplace Import | ZEDEDA Cloud: Infrastructure > Hardware Models > Import from Marketplace | Model name confirmed during import review |