99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
# Saqr — PPE Safety Detection on Unitree G1
|
|
|
|
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](scripts/start_saqr.sh)**
|
|
(directly or under the `saqr-bridge` systemd unit):
|
|
|
|
```bash
|
|
# 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](docs/DEPLOY.md) for first-time deploy and
|
|
[docs/start.md](docs/start.md) for the systemd workflow.
|
|
|
|
## Deploy
|
|
|
|
From the dev machine:
|
|
```bash
|
|
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](config/core_config.json) — detection, tracking,
|
|
camera, stream, training.
|
|
- [config/robot_config.json](config/robot_config.json) — bridge, TTS,
|
|
phrases, arm actions, deploy, start_saqr defaults.
|
|
- [config/logging.json](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:
|
|
```bash
|
|
sudo systemctl restart saqr-bridge
|
|
```
|
|
|
|
## Data & Models
|
|
|
|
`data/` and `runtime/` are gitignored (too large). Download separately:
|
|
|
|
- **Dataset**: [testcasque/ppe-detection-qlq3d](https://universe.roboflow.com/testcasque/ppe-detection-qlq3d)
|
|
→ YOLOv11 format → unzip to `data/dataset/`.
|
|
- **Base weights**: [Ultralytics releases](https://github.com/ultralytics/assets/releases)
|
|
→ `yolo11n.pt` into `data/models/`.
|
|
- **Saqr fine-tuned weights** (`saqr_best.pt`): produced by training — see
|
|
[docs/DEPLOY.md](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:
|
|
|
|
```bash
|
|
python -m apps.train_cli --epochs 100 --batch 16
|
|
# best weights land at data/models/saqr_best.pt; deploy with scripts/deploy.sh
|
|
```
|