ha-elegoo-spaghetti-detection/docs/ml-server.md

ML Server And Logs

The ML server listens on port 3333 and exposes the Obico/TSD model used for failure detection.

Standalone Docker Compose

git clone https://github.com/hepter/ha-elegoo-spaghetti-detection.git
cd ha-elegoo-spaghetti-detection
docker compose up -d

Default URL:

http://<server-ip>:3333

Default token:

obico_api_secret

Change ML_API_TOKEN before exposing this service outside a trusted local network.

Runtime Endpoints

Endpoint	Auth	Purpose
/	no	Small browser status page and recent redacted requests.
/hc/	no	Health check, returns ok.
/api/status	no	JSON status, model backend, threshold, request count.
/api/logs?token=<token>	yes	Recent request logs. Image query tokens are not shown in the dashboard.
/debug/image?img=<url>&token=<token>	yes	Fetch and decode a camera image without running inference. Used by setup validation.
/p/?img=<url>	yes	Prediction endpoint used by Home Assistant.

The token can be passed as either:

Authorization: Bearer <token>

or, for browser debugging only:

?token=<token>

CPU/GPU Behavior

The server is CPU-first by default:

ML_USE_GPU=false
ML_MODEL_BACKEND=onnx
GUNICORN_TIMEOUT=120
GUNICORN_WORKERS=1

This avoids slow CUDA probing and gunicorn worker timeouts on machines without a working NVIDIA runtime. Enable GPU only when Docker has working NVIDIA support:

ML_USE_GPU=true

Logs

Docker:

docker logs -f ha_elegoo_spaghetti_detection

Recent in-app request log:

curl "http://<server-ip>:3333/api/logs?token=obico_api_secret"

Health and model backend:

curl "http://<server-ip>:3333/api/status"

When testing a camera URL by hand, URL-encode the image URL:

curl --get "http://<server-ip>:3333/debug/image" \
  --data-urlencode "img=http://homeassistant.local:8123/api/camera_proxy/camera.example?token=..." \
  --data-urlencode "token=obico_api_secret"