Cause

The device is in restricted mode (PCIe disabled), the kernel driver failed to load, or the DEEPX DX-M1 M.2 module is not seated correctly.

Fix

1. Verify you are running at 12 V DC or 15 V USB-C PD minimum. Open the Power and boot rows above.
2. Check the driver and PCIe enumeration:
   terminal shell

   lspci | grep -i deepx
   lsmod | grep dxrt
   ls -l /dev/dxrt*

3. If PCIe enumerates but the driver is missing, reinstall it:
   terminal shell

   sudo apt update
   sudo apt install --reinstall -y libdxrt

4. If lspci does not list the DEEPX device, power down, open the enclosure, and reseat the DEEPX DX-M1 M.2 module. Apply ESD precautions.

Cause

The script is running under the system Python. The dx_engine binding lives inside the bundled virtual environment at /usr/lib/libdxrt/dxrt-venv.

Fix

source /usr/lib/libdxrt/dxrt-venv/bin/activate
python -c "import dx_engine; print(dx_engine.__version__)"

For scripts, invoke the venv Python directly: /usr/lib/libdxrt/dxrt-venv/bin/python my_script.py.

Cause

The container was started without the NPU character device mapped in, or without the privileges needed to attach to it.

Fix

Start the container with the device and --privileged:

docker run --rm --privileged   --device /dev/dxrt0   -v /opt/models:/models   alpon-infer:latest

For docker-compose, set privileged: true and devices: ["/dev/dxrt0"].

Cause

The compiled .dxnn footprint exceeds the DEEPX DX-M1's 4 GB on-chip memory. The NPU has its own dedicated memory pool, independent of Raspberry Pi CM5 system RAM.

Fix

1. Recompile with a lower input resolution (for example 640×640 instead of 1280×1280).
2. Switch to a lighter model variant (nano or small instead of large or x).
3. Quantize or prune the model before re-exporting to ONNX, then recompile with dxcom.

Cause

The model was compiled without PPU (post-processing unit) support. Post-processing (NMS, box decoding) then runs on the Raspberry Pi CM5 CPU and becomes the bottleneck.

Fix

1. Recompile the ONNX graph with a config that enables the PPU. Run dxcom on a host PC:
   terminal (host PC) shell

   dxcom   -m /path/to/yolov8n.onnx   -c yolov8n_config.json   -o yolov8n-output

2. Use a config with a ppu block, calibration settings, and the matching preprocessing pipeline:
   yolov8n_config.json json

   {
     "inputs": {
       "images": [1, 3, 640, 640]
     },
     "calibration_num": 100,
     "calibration_method": "ema",
     "train_batchsize": 32,
     "num_samples": 1024,
     "default_loader": {
       "dataset_path": "./calibration_dataset",
       "file_extensions": ["jpeg", "jpg", "png", "JPEG"],
       "preprocessings": [
         { "resize": { "mode": "pad", "size": 640,
                       "pad_location": "edge",
                       "pad_value": [114, 114, 114] } },
         { "div": { "x": 255 } },
         { "convertColor": { "form": "BGR2RGB" } },
         { "transpose": { "axis": [2, 0, 1] } },
         { "expandDim": { "axis": 0 } }
       ]
     },
     "ppu": {
       "type": 1,
       "conf_thres": 0.25,
       "num_classes": 80,
       "layer": [
         { "bbox": "Mul_441", "cls_conf": "Sigmoid_442" }
       ]
     }
   }

3. Redeploy the resulting .dxnn. PPU-compiled nano-class YOLO models reach roughly 50 FPS at 1280×720 and 20 to 25 FPS at 1920×1080.
4. Monitor with dxtop to confirm the NPU is saturated rather than the CPU.

Cause

The ONNX graph contains an attention block, transformer layer, or another operator outside the DEEPX DX-M1 supported set. The current dxrt-runtime targets image-based CNNs; transformers are not yet supported.

Fix

1. Switch to a CNN-based equivalent (YOLOv5/v7/v8, SSD, ResNet, MobileNet, EfficientNet, U-Net).
2. If you must keep a transformer head, run it on the Raspberry Pi CM5 CPU and offload only the CNN backbone to the NPU.
3. Check the DEEPX release notes for the current supported-operator list before compiling.