Surface Defect Inspection — Deployment Guide

Preset

IP Camera + reComputer J30 / J40 (Orin)

A Jetson Orin pulls the camera's RTSP stream, detects defects, and outputs the verdict on Modbus TCP and MQTT; a PLC is optional.

  • Camera: Any RTSP camera framed on the strip or part. Have the RTSP URL with credentials ready and test it in VLC first.
  • Usage limits: Internal validation only. The model is trained on a re-hosted copy of NEU-DET; clear its licence with the dataset owner, or retrain on your own images, before a public demo, a customer-site demo or commercial material. Crazing has the lowest accuracy of the six classes and changing the threshold does not improve it; frame-level false alarms have to be measured on your own line images.
  • Network: The PLC or MES can reach ports 502 (Modbus) and 1883 (MQTT) on the device.
1

Deploy Surface Inspection

Deploys the inspector and builds its TensorRT engine on the device. Allow about 10 minutes; the first start waits for the build to finish.

Prerequisites
  1. The model file is not on the CDN (licence not cleared): before deploying, place yolox_tiny_neu6.onnx at ~/edge-inspection-surface/jetson_inspection/models/yolox_tiny_neu6.onnx on the device. The deploy verifies its sha256.
  2. The verdict threshold defaults to 0.35.
  3. Detector Track: yolox is the default; dfine and rtdetrv2 are available, their engine build time on Orin varies, and the 0.35 threshold is calibrated for yolox, so tune it on your own line images after switching tracks.
Troubleshooting
SymptomFix
Static model does not take explicit shapes during the engine buildWhen building by hand with the upstream build_engine.sh, set TRT_STATIC_SHAPE=true
Engine build fails or stops part wayConfirm /usr/src/tensorrt/bin/trtexec exists and 10 GB is free; delete any leftover .part file and retry
numpy.core.multiarray failed to import, or cv2 fails to import inside the containerMount only the host's /usr/lib/python3.10/dist-packages/tensorrt, not the whole dist-packages
docker compose fails reading ._docker-compose.ymlRun find . -name '._*' -delete in the compose directory
No video from the cameraTest the RTSP URL in VLC and check the path and credentials
sha256 mismatch on the ONNXDelete the file and copy the correct model file again
Deploy cannot connect over SSHConfirm SSH is reachable and the username is right (usually recomputer, nvidia or ubuntu)
Deployment method

Deploy to the Jetson over SSH. The device needs JetPack 6.x with the NVIDIA container runtime and at least 10 GB free disk.

What you will be asked for(filled in the SenseCraft Solution app)
  • Jetson IP*
  • SSH Username*default recomputer

    Common defaults: recomputer (Seeed reComputer J30 / J40 series), nvidia, or ubuntu.

  • SSH Password*
  • Device Name*default orin-nx

    First segment of the MQTT topic — name this device after the line or cell so several installations stay separable on one broker

  • Stream ID*default line1-cam1

    Appended to the MQTT topic so several cameras on one box stay separable

  • Camera RTSP URL*

    Test this address in VLC first — a wrong path or wrong credentials is the most common failure

  • Line Rate (FPS)*default 10

    Frames per second pulled from the source. All measured latency figures were taken at 10 FPS.

  • Detector Track*default yolox
    3 options
    • · YOLOX-Tiny — the measured, deployed default
    • · D-FINE-S — CPU golden shows higher recall at matched precision; no Orin engine timing yet
    • · RT-DETRv2-S — CPU golden only, slower than D-FINE on CPU; no Orin engine timing yet

    Which detector architecture to build and run. yolox is the only track measured on this board (TensorRT engine, 291 s build) and the only one this solution ships on the Hailo preset. dfine and rtdetrv2 have equal or better recall at matched precision in the CPU-only comparison (single seed, see the solution page) but have not been engine-built or timed on Orin yet — the 291 s build time and every Jetson latency figure on this page are yolox-only until they are.

  • Verdict Threshold*default 0.35
    3 options
    • · 0.25 — higher recall, more false alarms
    • · 0.35 — the frozen deployment value (calibrated for yolox)
    • · 0.45 — higher precision, more misses

    Score above which a detection counts towards an NG verdict. 0.35 was frozen against YOLOX's obj×cls score distribution on 290 val images — see the solution page. It is not re-calibrated for dfine/rtdetrv2: their sigmoid decoder scores are distributed differently, so the same number does not mean the same confidence level on those tracks.

  • Modbus Unit ID*default 1

    Modbus TCP unit id served on port 502. The register map in the guide assumes unit 1.

2

Watch the Live Inspection

Open the device's own page to see detection boxes on the live frames and the health counters.

Troubleshooting
SymptomFix
The page does not loadRun docker ps to confirm the container is up, and check nothing else holds port 8080
Preview moving but no boxes ever appearCheck /events for recent verdicts first, then confirm a defect is in frame or lower the threshold
frames_dropped climbingLower the configured FPS or reduce the stream count
mqtt.rejected non-zeroCheck the container logs for contract validation errors
After Deployment

Results go to <device-name>/inspection/<stream-id>/results on MQTT port 1883, and the verdict is written to Modbus TCP port 502, unit 1, coils 0 and 1.

Quick verification

  1. Open http://<device-ip>:8080/: the MJPEG preview is moving.
  2. Open http://<device-ip>:8080/healthz: inference_time_ms is a few milliseconds, frames_dropped is 0 at 10 FPS, and mqtt.rejected is 0.
  3. Put a defective sample in front of the camera: a box appears with its class name and score.
  4. From another machine, run mosquitto_sub -h <device-ip> -t '<device-name>/inspection/#' -v and confirm messages arrive.

The MQTT message

One message per frame: verdict is OK / NG, defect_count is the number of defects, and detections[] lists every box in the frame (class_name, score, normalised centre/width/height bbox). With no defect, primary_class_id is -1 while the matching Modbus register is 0.

Next steps

  • Wire the Modbus coil into your reject or marking station, then run Step 3.
  • Point your MES or historian at the MQTT topic.
  • Load-test before adding cameras: an Orin NX ran 8 streams stably with MQTT and Modbus writes turned off.
3

Check the Modbus Output

Confirm a Modbus master reads the correct verdict. Skip this on an installation that consumes MQTT only.

Prerequisites
  1. A machine on the same network segment that can act as a Modbus TCP master.
  2. The device IP and the unit id set during deployment (the table below assumes unit 1).
Troubleshooting
SymptomFix
Connection refused on 502Check modbus.enabled in config/config.json on the device and confirm the container is up
Registers all zero while MQTT shows detectionsCheck the unit id, or read again on an NG frame
The box position is wrongHR 2-5 are normalised x10000 centre/width/height; divide by 10000 and multiply by the frame size
Several cameras but only one set of registersThere is one register block and the last verdict wins; take per-stream results from MQTT
After Deployment

The register map, unit 1 on port 502:

AddressMeaning
Coil 0NG, mutually exclusive with coil 1
Coil 1OK, mutually exclusive with coil 0
HR 0Primary defect class id (the highest-scoring box in the frame); 0 when OK
HR 1Defect count
HR 2Primary box cx, normalised x10000
HR 3Primary box cy, normalised x10000
HR 4Primary box w, normalised x10000
HR 5Primary box h, normalised x10000
HR 6Heartbeat Unix seconds, high word of a uint32
HR 7Heartbeat Unix seconds, low word of a uint32

Quick verification

  1. Read coils 0-1 and HR 0-7 on unit 1, port 502, for example with the upstream repo's python evaluation/read_modbus.py --host <device-ip> --port 502 --unit 1.
  2. Sample continuously while a defective sample passes the camera: the coil pair flips.
  3. The coils are never both 1 in the same sample; if you read (1,1), stop and investigate.
  4. On an NG frame, HR 2-5 are within 0-10000 and match the box in the MQTT message; on an OK frame, HR 0-5 are all zero.
  5. HR 6-7 keep advancing even when no new verdict arrives.

Next steps

  • Have the PLC trigger on the coil; when the coil flips, the registers already hold that frame's data.
  • Alarm on a stale heartbeat to tell "no defect" apart from "the inspector stopped".
4

Enable Unsupervised Anomaly Detection (Optional)

Optional. Runs EfficientAD-S (trained only on defect-free images) alongside the detector to flag frames unlike the OK reference set, including defect types the detector was never trained on. It does not affect the verdict.

Prerequisites
  • Step 1 completed; a config edit and container restart are enough.
  • The EfficientAD-S ONNX copied onto the device by hand (not on the CDN).
  • Before relying on anomaly_score, calibrate anomaly.threshold with your own OK samples from the actual inspection camera.
Troubleshooting
SymptomFix
anomaly_score never appears in the MQTT eventConfirm anomaly.enabled: true was saved and the container restarted; check the container logs for a model-load error at anomaly.path
anomaly_score stays near one value for every sampleRecalibrate anomaly.threshold on your own camera's OK set
Judging a frame abnormal from a single anomaly_score gives inconsistent resultsThe single-frame score is near random; use the pixel/region signal (heatmap_ref plus the score)