> For the complete documentation index, see [llms.txt](https://nx.docs.scailable.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nx.docs.scailable.net/ai-manager-v6.1.4/ai-accelerators-support/advanced/deepx-support.md).

# DEEPX Support

Run models on DEEPX DX-M1 and DX-H1 NPUs with the DEEPX runtime of the AI Manager: requirements, install, model conversion, post-processing and troubleshooting.

| AI Accelerator | Support Level | CPU Architecture | Operating System           | API/driver version |
| -------------- | ------------- | ---------------- | -------------------------- | ------------------ |
| DEEPX DX-M1    | Experimental  | x86\_64, aarch64 | Ubuntu 20.04, 22.04, 24.04 | DX-RT v3.3.2       |
| DEEPX DX-H1    | Experimental  | x86\_64, aarch64 | Ubuntu 20.04, 22.04, 24.04 | DX-RT v3.3.2       |

The AI Manager has one DEEPX runtime, built on the DEEPX runtime library DX-RT, that runs models on the NPU of a DEEPX DX-M1 or DX-H1 card. It runs models in the DEEPX format (`.dxnn`), which the AI Manager Cloud produces from your ONNX model when you enable the **DeepX (Experimental)** conversion, see [Convert a Model](#convert-a-model).

The DEEPX runtime of the AI Manager supports Ubuntu 20.04, 22.04 and 24.04 only. Windows is not supported yet. We tested it on the DX-M1; the DX-H1 is not verified yet.

## About DEEPX

DEEPX is a leading on-device AI semiconductor company specializing in Neural Processing Units (NPUs), headquartered in South Korea.

<figure><img src="https://2982163321-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKGfC0TFSmuMDjbpLErO3%2Fuploads%2Fgit-blob-75f164ddf9bc945f64dae7635ef67b2b6afcba61%2Fdeepx-logo.png?alt=media" alt="DEEPX logo" width="200"><figcaption></figcaption></figure>

The DX-M1 AI Accelerator is designed for high-performance inference at low power draw. The DX-H1 is the higher-performance variant.

To support seamless deployment and execution of deep learning models, DEEPX provides the DXNN Compiler along with various software components optimized for DEEPX hardware.

Visit the [official website](https://deepx.ai/) for more information.

## Quick Start

1. Check the requirements: a DX-M1 or DX-H1 card, Ubuntu 20.04, 22.04 or 24.04, and DX-RT v3.3.2 only: [Requirements](#requirements).
2. Stop the Mediaserver, run the install script (DX-RT, NPU driver and firmware), then reboot: [Install the DEEPX Software](#install-the-deepx-software).
3. Check the versions: [Verify the Installation](#verify-the-installation).
4. Select the DEEPX runtime in the AI Manager plugin: [Select the DEEPX Runtime](#select-the-deepx-runtime).
5. Upload your model as a ZIP (ONNX file, JSON configuration, calibration images) with the **DeepX (Experimental)** conversion enabled: [Convert a Model](#convert-a-model).
6. Decode the raw model output with a post-processor: [Build the Post-Processor](#build-the-post-processor).

## Requirements

| Item           | Requirement                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| Card           | DEEPX DX-M1 (M.2 module) or DX-H1                                                                                |
| CPU            | x86\_64 (Intel, AMD) or ARM64 (aarch64)                                                                          |
| Memory         | 8 GB RAM (16 GB or higher recommended)                                                                           |
| Disk           | 4 GB or more                                                                                                     |
| OS             | Ubuntu 20.04, 22.04 or 24.04 (the DEEPX runtime is built for each Ubuntu version)                                |
| DEEPX software | DX-RT, NPU driver and firmware, installed together as shown below. **The AI Manager supports DX-RT v3.3.2 only** |

On Linux the AI Manager needs `libgomp1` for all its runtimes, and a minimal Ubuntu image may not have it: `sudo apt install libgomp1`.

## Install the DEEPX Software

### Install the Card

To install the DX-M1 module, insert it into an available M.2 slot on the target system. See the DEEPX documentation for the slot and power requirements of your module.

### Install DX-RT, the NPU Driver and the Firmware

After installing the module, install the necessary software components from the DEEPX SDK, available on GitHub.

* [DX Runtime (DX-RT)](https://github.com/DEEPX-AI/dx_rt)
* [NPU Driver](https://github.com/DEEPX-AI/dx_rt_npu_linux_driver)
* [Firmware (FW)](https://github.com/DEEPX-AI/dx_fw)

The installation must follow a specific order:

1. **Install DX Runtime (DX-RT) and NPU Driver**. The installation order between these two components does not matter.
2. **Install Firmware (FW)**. Once both the DX Runtime and NPU Driver are installed, proceed with the Firmware (FW) update.

The Firmware (FW) can only be installed after both the DX Runtime and NPU Driver are installed and the DX-M1 m.2 module is connected to the system.

The script below installs all three at the versions the AI Manager supports. Before you run it:

| Before you run the script                                                                                                 | Why                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stop the Mediaserver** (`sudo systemctl stop <service-name>.service`)                                                   | The script reloads the NPU driver, which stops `dxrt.service` and force-kills every process that uses the NPU, the Mediaserver and its AI Manager included                                                 |
| Run it as a user with `sudo` rights, in an empty folder                                                                   | It downloads the sources to `./deepx-installation`, stops at the first error, and deletes the folder only when everything succeeded. After a failed run, remove the folder before you run the script again |
| For a card other than the **DX-M1 M.2 module**, set `FW_PATH` (for example `FW_PATH=m1/latest/h1/fw.bin bash install.sh`) | The script flashes the firmware of the DX-M1 M.2 module by default. `dxrt-cli` skips a firmware file that does not match the board without reporting an error                                              |

`FW_PATH` values:

| Card                | `FW_PATH` (in the `dx_fw` repository) |
| ------------------- | ------------------------------------- |
| DX-M1 M.2 (default) | `m1/latest/mdot2/fw.bin`              |
| DX-H1               | `m1/latest/h1/fw.bin`                 |
| DX-M1M M.2          | `m1m/latest/mdot2/fw.bin`             |

These are the folders of `dx_fw` v2.5.6, and only the DX-M1 is tested. Check the README of `dx_fw` for your card.

Reboot the machine when the script finishes, then check the versions as shown in [Verify the Installation](#verify-the-installation): the firmware must be v2.5.6.

<details>

<summary>Shell script to install DX RT, NPU Driver and the Firmware.</summary>

```bash
#!/usr/bin/env bash
# Stop at the first failing command, on unset variables and on failures inside pipes
set -euo pipefail

# Firmware file inside the dx_fw repository. The default is the DX-M1 M.2 module.
# For another card run `FW_PATH=<path> bash install.sh`.
FW_PATH="${FW_PATH:-m1/latest/mdot2/fw.bin}"

# Version mapping: DX RT version -> commit hashes for each repository
# Format: "version:dx_rt_commit:dx_rt_npu_linux_driver_commit:dx_fw_commit"
declare -A VERSION_MAP=(
    ["3.3.2"]="3.3.2:a30624494506607b65a5d621e5cd37d3c2dbcb99:57c6f7c8178b5eb9ffbee9a50fdb96f3e1be0a6c:3998ea708ba1bdadcc8e349fe87a082d300d3ec5"
)

# Function to get the latest supported version from VERSION_MAP
get_latest_version() {
    printf '%s\n' "${!VERSION_MAP[@]}" | sort -V | tail -n1
}

# Function to display available versions
show_versions() {
    local latest_version
    latest_version=$(get_latest_version)
    echo "Available DX RT versions:"
    # Sort versions numerically
    printf '%s\n' "${!VERSION_MAP[@]}" | sort -V | while read -r version; do
        if [ "$version" = "$latest_version" ]; then
            echo "  - $version (latest)"
        else
            echo "  - $version"
        fi
    done
}

# Function to get version selection from user
select_version() {
    show_versions
    echo ""
    read -r -p "Enter the DX RT version to install (default: latest): " selected_version

    if [ -z "$selected_version" ]; then
        selected_version="latest"
    fi

    # Resolve "latest" to the highest version in VERSION_MAP
    if [ "$selected_version" = "latest" ]; then
        selected_version=$(get_latest_version)
        echo "Resolved 'latest' to version: $selected_version"
    fi

    if [ -z "${VERSION_MAP[$selected_version]:-}" ]; then
        echo "Error: Invalid version '$selected_version'"
        echo ""
        show_versions
        exit 1
    fi

    echo "Selected version: $selected_version"
    SELECTED_VERSION=$selected_version
}

# Parse version mapping
parse_version_info() {
    local version=$1
    local version_info="${VERSION_MAP[$version]}"
    IFS=':' read -r -a parts <<< "$version_info"
    DX_RT_COMMIT="${parts[1]}"
    DRIVER_COMMIT="${parts[2]}"
    FW_COMMIT="${parts[3]}"
}

# Main installation script
select_version
parse_version_info "$SELECTED_VERSION"

# A folder left by a failed run would break the clones below
if [ -e deepx-installation ]; then
    echo "Error: ./deepx-installation exists (left by a previous run). Remove it and run the script again."
    exit 1
fi

echo "Creating installation directory"
mkdir deepx-installation
cd deepx-installation

HERE=$(pwd)

# Clone repositories
echo "Cloning repositories..."
git clone https://github.com/DEEPX-AI/dx_rt
git clone https://github.com/DEEPX-AI/dx_rt_npu_linux_driver
git clone https://github.com/DEEPX-AI/dx_fw

# Checkout specific versions
echo "Checking out version $SELECTED_VERSION..."

echo "  Checking out dx_rt to commit: $DX_RT_COMMIT"
git -C "$HERE/dx_rt" checkout "$DX_RT_COMMIT"

echo "  Checking out dx_rt_npu_linux_driver to commit: $DRIVER_COMMIT"
git -C "$HERE/dx_rt_npu_linux_driver" checkout "$DRIVER_COMMIT"

echo "  Checking out dx_fw to commit: $FW_COMMIT"
git -C "$HERE/dx_fw" checkout "$FW_COMMIT"

# Install DX RT
echo "1. Installing DX RT..."
cd "$HERE/dx_rt"
./install.sh --all
./build.sh

# Install NPU driver
echo "2. Installing NPU driver..."
cd "$HERE/dx_rt_npu_linux_driver/modules"
sudo ./build.sh -c uninstall
./build.sh
# --reload loads the new driver now, which the firmware flash needs. It also stops
# dxrt.service and kills every process that holds /dev/dxrt*, such as the Mediaserver.
sudo ./build.sh -c install --reload

# Install firmware
echo "3. Installing firmware ($FW_PATH)..."
cd "$HERE/dx_fw"
# The DX-RT firmware instructions: stop dxrt.service while flashing, start it afterwards
sudo systemctl stop dxrt.service || true
# "-u force" flashes the file even if the card already runs the same or a newer firmware
dxrt-cli -u "$FW_PATH" -u force
sudo systemctl start dxrt.service || true

# Everything succeeded: remove the downloaded sources
cd "$HERE/.."
sudo rm -rf "$HERE"
echo "Installation completed successfully. Please reboot your machine"
```

</details>

### Verify the Installation

After completing the software installation, run the verification commands to ensure the setup is correct and all components are compatible:

```bash
dxrt-cli --status
dxrt-cli -v
```

| Command             | What it checks                                                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `dxrt-cli --status` | That the module is properly recognized and all components are running, with the versions of the runtime, driver and firmware |
| `dxrt-cli -v`       | The minimum required versions of the driver and firmware for your installed DX-RT version                                    |

<details>

<summary>Example output of <code>dxrt-cli --status</code></summary>

A successful setup will produce an output similar to the following, displaying the correct versions for the runtime, driver, and firmware:

```
DXRT v3.3.2
=======================================================
 * Device 0: M1, Accelerator type
---------------------   Version   ---------------------
 * RT Driver version   : v2.4.1
 * PCIe Driver version : v2.2.0
-------------------------------------------------------
 * FW version          : v2.5.6
--------------------- Device Info ---------------------
 * Memory : LPDDR5 5600 Mbps, 3.92GiB
 * Board  : M.2, Rev 1.0
 * Chip Offset : 0
 * PCIe   : Gen3 X2 [03:00:00]

NPU 0: voltage 750 mV, clock 1000 MHz, temperature 38'C
NPU 1: voltage 750 mV, clock 1000 MHz, temperature 38'C
NPU 2: voltage 750 mV, clock 1000 MHz, temperature 38'C
=======================================================
```

</details>

<details>

<summary>Example output of <code>dxrt-cli -v</code></summary>

The output will show the compatibility requirements as follows:

```
DXRT v3.3.2
Minimum Driver Versions
  Device Driver: v2.4.0
  PCIe Driver: v2.2.0
  Firmware: v2.5.2
Minimum Compiler Versions
  Compiler: v1.18.1
  .dxnn File Format: v6
```

</details>

## Select the DEEPX Runtime

The AI Manager plugin offers the DEEPX runtime only if the NPU driver is loaded (a `/dev/dxrt*` device exists) **and** `dxrt-cli -i` reports exactly DX-RT v3.3.2. After installing, rebooting and restarting the Mediaserver, open any camera's settings, go to the **Integrations** tab, click **AI Manager**, and select the DEEPX runtime. See [Runtime Selection](https://nx.docs.scailable.net/ai-manager-v6.1.4/ai-manager-plugin/configure-the-plugin/runtime-selection.md) for the details.

## Convert a Model

The AI Manager Cloud converts your ONNX model to `.dxnn` with the DEEPX compiler (DX-COM), at upload time. In the **Hardware Support** step of the [upload wizard](https://nx.docs.scailable.net/ai-manager-v6.1.4/ai-manager-cloud-ui/upload-your-model.md), enable the **DeepX (Experimental)** conversion.

The Cloud needs a ZIP archive instead of a bare ONNX file, because the compiler also needs a configuration and calibration images (DX-COM quantizes the model to INT8). Put these **at the root of the ZIP**:

* exactly one `.onnx` file,
* exactly one `.json` configuration file,
* optionally, a folder of calibration images (use roughly 100 images similar to your camera scenes).

Without calibration images the compiler uses dummy data, still produces a model, but accuracy may drop.

The Cloud recognizes a DEEPX archive from the files in the ZIP and searches **every folder of the ZIP**, not only the root. The ZIP is taken for another accelerator's archive, and the DeepX conversion is not offered, if it contains any of these files anywhere, for example inside the calibration folder:

* a `.txt` file (EdgeCortix), one `.yaml` file (Ambarella) or one `.mpk` file (SiMa),
* a second `.json` file, or a `.json` file named `ncconfig.json` (MemryX).

Keep the ZIP free of such files.

### JSON Configuration

| Key                              | Meaning                                                                                                                                                         |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputs`                         | **Required.** The model input, as `{"<input name>": [N, C, H, W]}`. The name and shape must match the ONNX input                                                |
| `default_loader.dataset_path`    | Calibration image folder, relative to the ZIP root, for example `./calibration_dataset`. An absolute path such as `/app/dataset` fails with `DataNotFoundError` |
| `default_loader.file_extensions` | Image extensions to use, for example `["jpeg", "jpg", "png"]`                                                                                                   |
| `default_loader.preprocessings`  | Ordered steps applied to each calibration image, see below                                                                                                      |
| `calibration_num`                | Number of calibration images used (100 in the DEEPX model zoo). More is slower                                                                                  |
| `calibration_method`             | `"ema"` in all DEEPX examples                                                                                                                                   |

The `preprocessings` steps are `resize`, `convertColor`, `centercrop`, `div`, `normalize`, `transpose` and `expandDim`. **Only `div` and `normalize` are compiled into the model.** The other steps only prepare the calibration images.

The AI Manager sends every frame to a DEEPX model as **uint8 RGB pixels in NHWC layout, already resized to the model input and without normalization**, whatever the model metadata says. So:

* put the normalization of your model in the configuration, for example `div` by 255, so the model applies it itself;
* make the calibration `preprocessings` (resize, color order) match what the AI Manager sends, otherwise the quantization is calibrated on different images than the ones seen at runtime. The resize method is set in the plugin's [model settings](https://nx.docs.scailable.net/ai-manager-v6.1.4/ai-manager-plugin/configure-the-plugin/model-settings/resize-method.md): Letterbox (the default) pads the frame with black bars, Stretch and Crop do not, so prepare the calibration images the same way.

The [DEEPX Model Zoo](https://developer.deepx.ai/modelzoo/) has ready-made configurations for common models, and the DX-COM documentation, available from the [DEEPX document download page](https://developer.deepx.ai/document-download/), documents the rest (JSON file configuration, supported ONNX operations).

### Model Constraints

Observed with DX-COM 2.3.0:

* **Single-input models only.** A model with two inputs fails to convert.
* **Static input shapes**, declared in the `inputs` key.
* Operators the NPU does not run are placed on the CPU instead of being rejected. Tested with `Erf`, `Einsum` and `CumSum`.
* Detection models keep their **raw output heads**. Boxes are decoded by a [post-processor](#build-the-post-processor).
* Quantization to INT8 slightly changes the results compared to the CPU. On YOLOX-s, boxes moved by up to 4 px and scores by up to 0.01.
* DX-H1 conversion is not verified.

### Supported Models

The DEEPX SDK includes an [Open Model Zoo](https://developer.deepx.ai/modelzoo/) that provides various pre-optimized neural network models for DEEPX NPUs.

All models are available as:

* Pretrained ONNX models
* Corresponding configuration .json files
* Precompiled DXNN binaries (not usable in the AI Manager, see below)

These models cover tasks such as:

* Object Detection
* Face Detection
* Classification
* Other vision AI applications

Convert the ONNX model and its configuration with the AI Manager Cloud. A zoo `.dxnn` file cannot be deployed: the AI Manager only runs `.dxnn` models produced by the Cloud conversion.

## Build the Post-Processor

DEEPX models keep their raw output heads, so the boxes must be decoded after the model runs. There are two ways.

### Built-in Decoder

For a YOLOv8 model whose detection head the DEEPX compiler split into three pairs of outputs, one pair per stride (8, 16, 32), each made of a box regression `[1, 64, H, W]` and a class tensor `[1, C, H, W]`, the AI Manager has the built-in `YOLO8_DEEPX` decoder. Select it with a file named `raw_postprocessing.json` in the plugin working directory:

```
<server-install-dir>/mediaserver/var/nx_ai_manager/raw_postprocessing.json
```

```json
{
  "modelArchitecture": "YOLO8_DEEPX",
  "confidence_threshold": 0.25,
  "iou_threshold": 0.45,
  "class_names": ["person", "bicycle", "car"]
}
```

| Key                    | Values (default in bold) | Meaning                                                                                                                                                |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `modelArchitecture`    | `YOLO8_DEEPX`            | Selects the decoder. Without it, or with a name the AI Manager does not know, it falls back to its YOLO11 decoder, which does not fit the DEEPX output |
| `confidence_threshold` | number, **`0.25`**       | Optional                                                                                                                                               |
| `iou_threshold`        | number, **`0.45`**       | Optional                                                                                                                                               |
| `class_names`          | list of names            | The model classes in the order of the model output. It is used when the model carries no class list of its own                                         |

* The file applies to **every model assigned to the server**.
* The decoder applies one non-maximum suppression across all classes.
* The AI Manager reads the file when it loads the model list. Restart the Mediaserver after you create or change it.

### External Post-Processor

For any other model, use a [custom external post-processor](https://nx.docs.scailable.net/ai-manager-v6.1.4/ai-manager-plugin/advanced-configuration/external-postprocessing.md) to transform the model's raw outputs into meaningful insights such as bounding boxes.

For instance, for the [Yolov5 (320, final output only)](https://drive.google.com/file/d/1IdEaIHiXvFSwwpEAAlU81XVLk06r_9MX/view?usp=drive_link) trained on the COCO dataset, the following archive contains the source code and the recipe to build it:

[Yolov5 DEEPX post-processor archive](https://drive.google.com/file/d/1ViD5UPsVKWoIc9dCtlPq3qOS7i5kw69J/view?usp=sharing).

**Yolov5 model bundle:** its JSON file sets `"dataset_path": "/app/dataset"`, and the conversion fails with `DataNotFoundError`. Unzip the bundle and set `"dataset_path": "./dataset"` in the JSON file (`dataset` is the calibration folder at the root of the bundle), then zip the `.onnx`, the `.json` and the `dataset` folder again, all at the root of the ZIP, and upload that ZIP.

{% hint style="warning" %}
`compile_install.sh`, the CMake install path and the `config.json` of the recipe all use the default install folder of the standard server package, followed by `/mediaserver/var/nx_ai_manager/nxai_manager/postprocessors/`. If your server is installed elsewhere, edit these files to use `<server-install-dir>/mediaserver/var/nx_ai_manager/nxai_manager/postprocessors/` first. The script also runs `sudo chmod 777` on that `postprocessors` folder, and it **overwrites** `external_postprocessors.json` there: back that file up first, or your other external post-processors are lost.
{% endhint %}

<details>

<summary>Compile and install the Yolov5 post-processor</summary>

To compile and install the post-processor, run:

```bash
bash compile_install.sh
sudo systemctl restart <service-name>.service
```

The restart makes the changes take effect.

Finally, make sure to assign the compiled post-processor to the DEEPX model pipeline as shown [here](https://nx.docs.scailable.net/ai-manager-v6.1.4/ai-manager-plugin/configure-the-plugin/model-settings.md#postprocessor).

</details>

### Important Notes

**DX-RT build option:** the provided Post-Processor functions correctly only when DX-RT is built with the `USE_ORT=ON` option. If you build DX-RT with the `USE_ORT=OFF` option, the number and shape of the output tensors sent to the Post-Processor will be different. Therefore, you must develop and use a separate Post-Processor specifically for that environment.

**Model output configuration:** using models that output per-layer feature maps in addition to the final output tensor required for post-processing is not recommended. Such models can cause overall performance degradation due to unnecessary memory usage and data copying.

For example, in the case of a YOLOv5 320x320 model, the required final output tensor for post-processing is as follows:

* `output, FLOAT, [1, 6300, 85]`

However, some ONNX models may be configured to output unnecessary feature maps in addition to the final result, as shown below:

* `458, FLOAT, [1, 3, 20, 20, 85]`
* `output, FLOAT, [1, 6300, 85]`
* `397, FLOAT, [1, 3, 40, 40, 85]`
* `519, FLOAT, [1, 3, 10, 10, 85]`

Using a model with such unnecessary outputs can lead to the following problems:

* **Potential for Malfunction**: If the order of the output tensors passed to the Post-Processor changes, it may fail to find the correct tensor and will not function properly.
* **Performance Degradation**: Even when the Post-Processor functions without errors, the presence of these extra outputs still causes performance degradation. The Inference Engine must perform unnecessary memory allocation and copy operations for the unused feature maps, which leads to a decrease in overall **throughput** and an increase in **latency**.

Therefore, before converting an ONNX model to the `dxnn` model format, it is crucial to verify that the model does not output any unnecessary feature maps.

## Configure the Runtime

The DEEPX runtime has no setting in `runtime_args.json`: it ignores every key of that file. There is nothing to tune.

The runtime writes its log to `runtime.log` in the Mediaserver's working directory, next to the other AI Manager runtime logs:

```
<server-install-dir>/mediaserver/bin/runtime.log
```

The runtime truncates the file every time it starts and never rotates it.

{% hint style="warning" %}
**One DEEPX model per server.** The AI Manager hands all the models assigned to the server to the runtime in one call, and the DEEPX runtime accepts exactly one. Several cameras can share that model, but assigning a second, different DEEPX model makes the runtime fail to start with `Multiple models not yet supported` (see [Troubleshooting](#troubleshooting)).
{% endhint %}

## Monitor

The DX-RT includes essential tools like `dxrt-cli` and `dxtop`, designed for device status checks, real-time monitoring, firmware updates, and troubleshooting.

### dxrt-cli: Command-Line Tool for Device Management

It supports operations such as device status checks, firmware updates, monitoring, resets, and diagnostics.

<details>

<summary>Example output of <code>dxrt-cli -h</code></summary>

```
$ dxrt-cli -h
DXRT v3.3.2
DXRT v3.3.2 CLI
Usage:
  dxrt-cli [OPTION...]

  -s, --status             Get device status
  -i, --info               Get device info
  -m, --monitor arg        Monitoring device status every [arg] seconds
                           (arg > 0)
  -r, --reset [=arg(=0)]   Reset device(0: reset only NPU) (default: 0)
  -d, --device arg         Device ID (if not specified, CLI commands will
                           be sent to all devices.) (default: -1)
  -u, --fwupdate arg       Update firmware with deepx firmware file.
                           sub-option : [force:force update, unreset:device
                           unreset(default:reset)]
  -g, --fwversion arg      Get firmware version with deepx firmware file
  -C, --fwconfig_json arg  Update firmware settings from [JSON]
  -v, --version            Print minimum versions
  -h, --help               Print usage
```

</details>

### dxtop: Real-Time Monitoring Tool

dxtop is a terminal-based utility that provides real-time insights into:

* NPU Memory usage
* Utilization
* Temperature
* Voltage
* Clock frequency

<details>

<summary>Example output of <code>dxtop</code></summary>

```
[DX-TOP]  (q) Quit   (n) Next Page   (p) Prev Page   (h) Help
Mon Jan 19 16:59:48 2026
DX-RT: v3.3.2     NPU Device driver: v2.4.1     DX-TOP: v1.1.0
-------------------------------------------------------------------------------
Device :0     Variant: M1     PCIe Bus Number: 08:00:00     Firmware:  v2.5.6
  NPU Memory:  [                    ] 0 B / 3.92 GiB (0.00%)
    Core :0   Util:   0.0%   Temp: 40 °C   Voltage: 750 mV   Clock: 1000 MHz
    Core :1   Util:   0.0%   Temp: 40 °C   Voltage: 750 mV   Clock: 1000 MHz
    Core :2   Util:   0.0%   Temp: 40 °C   Voltage: 750 mV   Clock: 1000 MHz
-------------------------------------------------------------------------------

Total Devices: 1
Page: 1 / 1
```

</details>

## Troubleshooting

| Symptom                                                                                                                                                                | Cause and fix                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The DEEPX runtime is not offered in the Integrations tab                                                                                                               | Check that a `/dev/dxrt*` device exists and that `dxrt-cli -i` prints `DXRT v3.3.2`. Any other DX-RT version is not offered: reinstall with the script above. Then restart the Mediaserver                                                                                                          |
| `dxrt-cli` prints `Device not found` (also `[DXRT][Error] Device not found.`), while `lspci` lists the card; objects stop being detected after an Ubuntu kernel update | The NPU driver is built for one kernel, and a kernel update removes it: `lsmod \| grep dx` is empty and `/dev/dxrt0` is missing. Rebuild the driver, see [Rebuild the driver after a kernel update](#rebuild-the-driver-after-a-kernel-update). If `lspci` does not list the card either, reseat it |
| The runtime fails to load, with `libdxrt.so: cannot open shared object file` in the log                                                                                | DX-RT is not installed or not on the library path. Install DX-RT v3.3.2 and run `sudo ldconfig`                                                                                                                                                                                                     |
| The runtime fails to load, with `undefined symbol` or `symbol lookup error` in the log                                                                                 | The installed DX-RT is older than v3.3.2. Install v3.3.2, run `sudo ldconfig`                                                                                                                                                                                                                       |
| `Runtime could not load models: Multiple models not yet supported` in the plugin log, and a `RUNTIME_INIT_FAILED` message                                              | Two or more different DEEPX models are assigned to the server, and the DEEPX runtime loads only one. Keep one DEEPX model per server (several cameras may share it), remove the other assignments, then restart the Mediaserver                                                                     |
| `Failed to load model` in `runtime.log`                                                                                                                                | The file is not a `.dxnn` that this DX-RT accepts (truncated, or compiled by a very different compiler version). Convert the model again                                                                                                                                                            |
| Conversion fails with `Input names mismatch` or `Input shape mismatch`                                                                                                 | `inputs` in the JSON does not match the ONNX input names and shapes                                                                                                                                                                                                                                 |
| Conversion fails with `Expected exactly 1 ONNX file, but found 0` (or `JSON file`)                                                                                     | The `.onnx` and `.json` files must be at the root of the ZIP, not in a folder, and there must be exactly one of each                                                                                                                                                                                |
| Conversion fails because the model expects 2 inputs                                                                                                                    | Multi-input models are not supported. Export a single-input model                                                                                                                                                                                                                                   |
| Conversion fails with `DataNotFoundError`                                                                                                                              | No calibration image matches `dataset_path` and `file_extensions`                                                                                                                                                                                                                                   |
| Detections are wrong or empty                                                                                                                                          | The post-processor does not match the model outputs (see [Important Notes](#important-notes)), or the calibration `preprocessings` and normalization do not match what the AI Manager sends (uint8 RGB, no normalization)                                                                           |
| Results differ slightly from the CPU runtime                                                                                                                           | Normal: the model is quantized to INT8                                                                                                                                                                                                                                                              |
| Low throughput on a DX-M1                                                                                                                                              | Check the `PCIe` line of `dxrt-cli -s`: a card on a slow or narrow PCIe link (low generation or lane count) limits performance                                                                                                                                                                      |

### Rebuild the Driver After a Kernel Update

Run these steps on the machine, with the driver source of the version you installed. The install script deletes its folder at the end, so clone the driver again at the tag that matches DX-RT v3.3.2 (driver v2.4.1, the driver commit of the script above).

{% hint style="warning" %}
Run this only when the driver is missing. On a machine where `dxrt-cli -s` already works, the uninstall step removes the working driver.

**Stop the Mediaserver first** (`sudo systemctl stop <service-name>.service`): `--reload` stops `dxrt.service` and force-kills every process that uses `/dev/dxrt*`, and when neither `lsof` nor `fuser` is installed it cannot find those processes, so unloading the driver fails if the card is in use. Start the Mediaserver again when the steps are done.
{% endhint %}

<details>

<summary>Steps to rebuild the driver</summary>

1. Clone the driver at the matching tag:

   ```bash
   git clone --depth 1 --branch v2.4.1 https://github.com/DEEPX-AI/dx_rt_npu_linux_driver
   cd dx_rt_npu_linux_driver/modules
   ```
2. Build the modules. This needs the kernel headers (`sudo apt install linux-headers-$(uname -r)`):

   ```bash
   ./build.sh
   ```
3. Remove the modules of the running kernel:

   ```bash
   sudo ./build.sh -c uninstall
   ```
4. Install and load the modules:

   ```bash
   sudo ./build.sh -c install --reload
   ```
5. Start `dxrt.service` again, because the reload stops it:

   ```bash
   sudo systemctl start dxrt.service
   ```
6. Check that the card works. The output shows the device, the firmware version and the NPU cores:

   ```bash
   dxrt-cli -s
   ```

A driver built this way is tied to one kernel, so **it must be rebuilt after every kernel update**. To avoid that, install the driver as a DKMS package instead: DKMS rebuilds it for each new kernel. The driver repository builds and installs that package itself:

1. Install the build tools:

   ```bash
   sudo apt install dkms build-essential linux-headers-$(uname -r)
   cd dx_rt_npu_linux_driver/modules
   ```
2. Remove a manually installed driver, which conflicts with the package:

   ```bash
   sudo ./build.sh -c uninstall
   ```
3. Install the `.deb` of the repository (`dxrt-driver-dkms`):

   ```bash
   sudo ./build.sh -c install-package
   ```
4. Check that `dxrt-driver-dkms` is listed as installed:

   ```bash
   dkms status
   ```

The `.deb` for v2.4.1 is in the `release/` folder of the repository, so `install-package` needs no build; `./build.sh -c debian-package` builds a new one. Remove the package with `sudo ./build.sh -c uninstall-package`. We did not test the DKMS path on a DX-M1: DEEPX describes it in the Linux installation guide of DX-RT, section "DKMS and Debian Package".

</details>

## Technical Support

For technical assistance, use the following support channels:

* [DEEPX Developer Portal](https://developer.deepx.ai/)
* DEEPX Support Email: <tech_support@deepx.ai>

{% tabs %}
{% tab title="Nx Witness" %}

* [Customer Support Portal](https://support.networkoptix.com/)
  {% endtab %}

{% tab title="Nx Meta" %}

* [Customer Support Portal](https://support.networkoptix.com/)
  {% endtab %}

{% tab title="Generic" %}

* Contact your reseller for platform support.
  {% endtab %}
  {% endtabs %}
