Symptom

lspci output contains no DEEPX entry. dxrt-cli -s reports no device found. The runtime is installed but the NPU is invisible to the host.

Cause

In the vast majority of cases the 16-pin FFC cable between the AI HAT+ and the Raspberry Pi 5 PCIe FPC connector is not making electrical contact. The usual culprits are a partially closed latch, a reversed cable, or a HAT not fully seated on the 40-pin GPIO header.

Fix

1. 1

   Power off the Pi 5 and reseat the 16-pin FFC cable.

   The AI HAT+ does not support hot-plug. Disconnect power before touching the cable. Open both FFC latches, remove and reinsert the cable firmly at both ends, close the latches, then power on and re-run lspci.

2. 2

   Confirm each latch is fully closed.

   A latch that feels closed but is not flush is a common trap. The latch should sit level with the connector body; a partially latched cable will not make electrical contact with the PCIe lane.

3. 3

   Inspect dmesg for PCIe enumeration errors.

   dmesg | grep -i dx

   Look for PCIe link failed, timeout, or enumeration error. These confirm the host saw the bus event but could not establish a link.

4. 4

   Verify the 40-pin header is fully seated.

   Press down on the AI HAT+ to confirm all 40 pins are engaged with the Raspberry Pi 5 GPIO header. A partially seated header can hold the FFC at an angle and prevent PCIe link establishment.

Symptom

Inference runs without error and at the expected frame rate, but the output is wrong: detections are random, classes are mismatched, or bounding boxes are misaligned. The same model behaves correctly on CPU.

Cause

The pre-processing pipeline does not match what the model expects. INT8 inference on the NPU is approximately 2 % less accurate than the original FP32 model (that is normal), but a wrong colour channel order, wrong normalisation, or wrong tensor shape produces output that looks nonsensical regardless of the NPU.

Fix

1. 1

   Check colour channel order, the most common cause.

   OpenCV loads images as BGR. Most vision models are trained on RGB. Always convert before inference:

   frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
2. 2

   Check normalisation.

   Verify pixel values are in the range and scale expected by the model (e.g. / 255.0 for [0, 1], or ImageNet mean/std). A wrong scale silently produces bad output.

3. 3

   Check input dimensions.

   Verify the tensor shape fed to the model matches what was specified at DX-COM compile time. Shape mismatches may not raise an error but produce meaningless output.

4. 4

   Benchmark against CPU inference.

   Run the same model as ONNX on the CPU to establish a ground truth. If CPU results are also wrong, the bug is in your pre-processing code, not the NPU.

Symptom

The compiled .dxnn model loads, runs at the expected frame rate on the NPU, and produces sensible-looking output (correct class labels, plausible bounding boxes). Measured accuracy against your evaluation set is materially lower than the same model running at FP32 on a workstation. A typical signature: detection mAP drops by 10–20+ percentage points, or top-1 classification accuracy drops by more than a few percent.

Cause

Fix

1. 1

   Quantify the gap against an FP32 baseline before changing anything.

   Run the original ONNX model on the CPU (via onnxruntime) on the same evaluation set. Compare the metric you actually care about (mAP, top-1, IoU) against the .dxnn result on the NPU. If the gap is within ~2 %, this is the published envelope and no fix is needed. If it is materially larger, continue to step 2.

2. 2

   Re-export ONNX from a clean eval-mode model.

   The most common defect: the model was exported while still in training mode (dropout active, batch-norm running stats wrong). Switch the model to eval() mode and re-export with opset 11, which is the widely-compatible default for DX-COM.

   model.eval() torch.onnx.export(model, dummy_input, "my_model.onnx", opset_version=11)
3. 3

   Check the ONNX graph against the DEEPX supported operator list.

   An unsupported operator can either error at compile time or fall back partially to CPU at runtime, which silently distorts numerical behavior. Inspect the exported ONNX with Netron and compare every op against the DEEPX-supported list at github.com/DEEPX-AI/dx-compiler · Building_Models.md. Replace or remove unsupported ops in your model definition before re-exporting.

4. 4

   Verify the preprocessing pipeline is byte-identical between training and inference.

   Quantization calibrates against the activation ranges your data produces. If training used one normalisation (e.g. ImageNet mean/std) and inference uses another (e.g. / 255.0), or if channel order swaps between RGB and BGR somewhere in the pipeline, INT8 calibration is fitted to one distribution while inference sees a different one. Re-check both pipelines side by side. See Inference results are wrong, inaccurate, or nonsensical for the full preprocessing checklist.

5. 5

   Recompile with a representative calibration set.

   DX-COM quantizes automatically and does not require manual configuration, but the calibration data it sees determines how INT8 ranges are fitted. If the calibration data is unrepresentative of your deployment distribution (e.g. all daytime images for a model that runs day and night), accuracy can degrade well beyond the 2 % envelope on the under-represented slice. Recompile the model with calibration data that matches the deployment distribution. [NEED FROM SIXFAB: confirm the DX-COM flag(s) for supplying a calibration dataset, recommended sample size, and whether the default behavior is to calibrate from the model's training data or from a separate set.]

6. 6

   If accuracy is still off, the model architecture may be quantization-sensitive.

   Some architectures (depthwise-separable convolutions, certain attention blocks, models with extreme activation ranges) lose more than 2 % under any post-training INT8 scheme. For these cases the workaround is at training time: apply quantization-aware training (QAT) on the workstation, export the QAT model to ONNX, then run it through DX-COM. [NEED FROM SIXFAB: explicit guidance on QAT support in DX-COM and any architecture-specific accuracy notes.]