Real-time PPE compliance (helmet, vest, boots, gloves, goggles) using YOLO11n. Runs on a Unitree G1 humanoid with an Intel RealSense D435I. On UNSAFE the robot speaks a warning and plays the reject arm action.

Layout

Saqr/
├── core/           # detection + tracking + events (shared by CLI/GUI/bridge)
├── apps/           # CLI modules (saqr_cli, detect_cli, train_cli, manager_cli, view_stream)
├── gui/            # PySide6 desktop GUI (dev-machine only)
├── robot/          # G1 bridge + DDS controller
├── utils/          # logger, config loader
├── scripts/
│   ├── start_saqr.sh         # the single entry point
│   ├── saqr-bridge.service   # systemd unit (wraps start_saqr.sh)
│   └── deploy.sh             # push code dev machine → robot
├── config/         # logging.json, core_config.json, robot_config.json
├── data/           # dataset/, models/          (gitignored)
├── runtime/        # captures/, runs/           (gitignored)
├── logs/           # per-module .log files      (gitignored)
├── docs/           # DEPLOY.md, start.md, use_case_catalogue.pdf
├── pyproject.toml
└── README.md

The project root is auto-detected from core/paths.py::PROJECT_ROOT — drop the Saqr/ folder anywhere on disk and the code finds itself. Override with SAQR_ROOT=/custom/path if needed.

Run

The project only runs through scripts/start_saqr.sh (directly or under the saqr-bridge systemd unit):

# On the robot:
sudo systemctl start saqr-bridge       # production
# or
~/Saqr/scripts/start_saqr.sh           # foreground / debug

Then on the wireless remote:

R2 + X → start detection
R2 + Y → stop detection

See docs/DEPLOY.md for first-time deploy and docs/start.md for the systemd workflow.

Deploy

From the dev machine:

scripts/deploy.sh            # rsync + pip install -e . in the robot's conda env
scripts/deploy.sh --ip …     # custom robot IP

Configure

All tunable values live in JSON — no code edits needed:

config/core_config.json — detection, tracking, camera, stream, training.
config/robot_config.json — bridge, TTS, phrases, arm actions, deploy, start_saqr defaults.
config/logging.json — log levels per category.

Precedence: env var > config JSON > code fallback. Most defaults can be overridden via env vars without editing the files (CONDA_ENV, SAQR_SOURCE, STREAM_PORT, DDS_IFACE, ROBOT_IP, …).

After editing any JSON:

sudo systemctl restart saqr-bridge

Data & Models

data/ and runtime/ are gitignored (too large). Download separately:

Dataset: testcasque/ppe-detection-qlq3d → YOLOv11 format → unzip to data/dataset/.
Base weights: Ultralytics releases → yolo11n.pt into data/models/.
Saqr fine-tuned weights (saqr_best.pt): produced by training — see docs/DEPLOY.md.

Training (dev machine, off-path)

Training is done on a workstation, not on the robot. It's a one-off, not part of the normal run flow:

python -m apps.train_cli --epochs 100 --batch 16
# best weights land at data/models/saqr_best.pt; deploy with scripts/deploy.sh