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

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

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

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:

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

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 -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.