bytetrack-counter-dashboard/AGENTS.md

AGENTS.md — bytetrack-counter

Architecture

• Edge AI counter: RTSP camera → YOLO RKNN (NPU) → tracking → line-crossing → SQLite + JSON state → Flask dashboard.
• 2 counter scripts, only 1 deployed:
  • counter_live.py — Jetson TensorRT variant (CUDA, NOT used on RK3588).
  • counter_live_rknn_bytetrack.py — RK3588 with ByteTrack. This is what systemd runs. Reference for C++ port.
• batch_store.py — shared SQLite persistence + batch state machine.
• counter_dashboard.py — Flask dashboard on port 5000, same DB.

No build / test / lint

There is no build system, no test framework, no linter config, no typechecker.
Do not try to run pytest, ruff, mypy, etc. — they don't exist here.

How to run

# Copy env (required, .env is gitignored)
cp config.env.example .env

# Venv (must use system-site-packages for RKNN toolkit)
python3 -m venv --system-site-packages venv
source venv/bin/pip install -r requirements.txt

# Run counter (RK3588 only — needs rknn-toolkit-lite2 & RKNN model)
PYTHONNOUSERSITE=1 venv/bin/python counter_live_rknn_bytetrack.py

# Run dashboard
PYTHONNOUSERSITE=1 venv/bin/python counter_dashboard.py

Key environment & install quirks

• PYTHONNOUSERSITE=1 is mandatory when running from the venv — without it, system/user packages leak in.
• .env is gitignored — always copy from config.env.example first.
• numpy<2 is required for rknn-toolkit-lite2 compatibility.
• Install path in service files is /opt/bytetrack-counter (not the /opt/jetson-counter mentioned in README/DEPLOY). The .env.example also reflects /opt/bytetrack-counter.
• Service user is root, not jetson (despite README saying otherwise).
• Two systemd units: bytetrack-counter.service + bytetrack-counter-dashboard.service.
• counter_live.py (TensorRT) is Jetson-only and won't work on RK3588.

Code conventions

• All config lives in .env (dotenv), read via os.getenv() at module top-level in each script.
• The 3 counter scripts duplicate ~80% of each other (drawing helpers, batch loop, etc). Changes to logic may need replication across variants.
• batch_store.py has its own threading (cutoff watcher, batch timeout timer) — thread safety is via a single state_lock.
• The dashboard re-creates DB tables on startup (_ensure_db()) independently from batch_store.py.
• No formal version tracking exists anywhere in this codebase.