# ELERAIQ Vision - Ubuntu Setup Guide

Recommended path: pull the small source package from this portal (no GitHub account needed - the portal is public), then build and install directly on the machine that'll run it. The build step pulls the actual dependencies (OpenCV, the camera SDK) straight from PyPI - also public, no login - so nothing large ever has to be pushed around by hand, and the result always matches the machine it's installed on.

**Why build locally instead of downloading a pre-built package:** a Python venv's `bin/python` isn't portable across machines with different Python/OS versions - a package built elsewhere can fail with `systemctl status` showing `status=203/EXEC` even though the install itself "succeeds". Building on the target machine avoids this entirely, at the cost of a one-time dependency download during install (a few hundred MB, same as any first-time Python project setup).

## 1. Get the source and build

```bash
sudo apt install -y python3-venv dpkg-dev
curl -O https://eleraiq.com/files/source/tgcs-fr-pred-source.tar.gz
mkdir tgcs-fr-pred && tar -xzf tgcs-fr-pred-source.tar.gz -C tgcs-fr-pred
cd tgcs-fr-pred
./build_deb_native.sh
```

The filename is always exactly `tgcs-fr-pred-source.tar.gz` - it's rebuilt fresh (with whatever's newest) on every portal deploy, so there's no version number to look up or fill in.

This creates a `.deb` in `dist/` with a venv built fresh, right here, using this machine's own Python - dependencies come from PyPI over your normal internet connection, not from GitHub or the portal.

## 2. Install it

```bash
sudo dpkg -i oak1-camera-playground_1.0.0_amd64.deb
sudo apt-get install -f
```

Use `dpkg -i` + `apt-get install -f`, not `apt install ./file.deb` - some `apt` versions reject local files with a confusing "unsupported file" error. `dpkg` is the lower-level tool and always works; the follow-up `apt-get install -f` pulls in the small number of missing system dependencies (`libusb-1.0-0`, `libgl1`, an audio player) automatically.

This installs to `/opt/oak1-camera-playground/` and registers a systemd service that starts automatically and restarts on crash.

## 3. Plug in the camera and verify

```bash
lsusb | grep -i movidius          # confirms Linux sees the device at all
sudo systemctl status oak1-camera-playground
sudo journalctl -u oak1-camera-playground -f
```

Look for `Pipeline successfully started.` in the logs. `No available devices` means USB isn't reaching the process - check the `lsusb` output and try a different port/cable.

Open `http://localhost:8000` (or `http://<host-ip>:8000` from another device).

## 4. Updating later

Re-download the latest source tarball from the portal (or `git pull` if you went that route), rebuild, reinstall:

```bash
cd tgcs-fr-pred
./build_deb_native.sh
sudo dpkg -i dist/oak1-camera-playground_1.0.0_amd64.deb
```

---

## Alternative: Docker instead of the `.deb`

```bash
docker compose up --build
```

Uses `device_cgroup_rules` for scoped USB access (see `docker-compose.yml`) rather than full `--privileged`. If you get "No available devices" here too, temporarily swap that block for `privileged: true` to isolate whether it's a permissions issue.

---

## Common gotchas we actually hit setting this up

- **`sudo: command not found`**: some minimal images don't ship it. Check `whoami` first - if you're already `root`, just drop `sudo` from every command. Otherwise: `su -`, then `apt install sudo`, then `usermod -aG sudo <your-user>`, then log out/in.
- **`newgrp: command not found`**: also missing on minimal images. Use `su - $USER` instead to pick up the new `docker` group membership in a fresh login shell, or just close and reopen your terminal.
- **`git clone` prompting for a GitHub password**: GitHub doesn't accept account passwords for git operations anymore. Generate a Personal Access Token (`github.com/settings/tokens`, `repo` scope), use it as the password when prompted, and run `git config --global credential.helper store` first so you're only asked once.
- **`apt install ./file.deb` says "unsupported file"**: use `sudo dpkg -i file.deb && sudo apt-get install -f` instead (see step 2 above).
- **`systemctl status ...` says "requested operations require superuser privileges"**: prefix with `sudo`. Also make sure the original install itself (`dpkg -i`) was run with `sudo`, or the systemd service never got registered.
- **`systemctl status` shows `status=203/EXEC` and the service keeps auto-restarting and failing**: the `.deb` was built on a different machine than the one you're installing it on, and its bundled venv's `bin/python` is a dangling symlink here. Rebuild with `./build_deb_native.sh` on this machine and reinstall (`sudo dpkg -i dist/*.deb`) - see step 1 above.
- **`lsusb: command not found`**: install it with `sudo apt install -y usbutils`.
- **`git: command not found`**: install it with `sudo apt install -y git`.

---

## Windows host (development)

```powershell
powershell -ExecutionPolicy Bypass -File run_supervised.ps1
```

Auto-restarts `app.py` if it crashes (see the Service Files section of this portal). Leave that window open; closing it is what stops the app.