yaris-obd/deploy/readme.md

Fresh Raspberry Pi install (deploy guide)

This guide installs yaris-obd on a clean Raspberry Pi so the web app auto-starts on boot and is reachable at http://yaris.local.

Quick install (copy/paste)

If your Pi already has Raspberry Pi OS Bookworm and internet, this is the fastest path:

sudo adduser --disabled-password --gecos "" yaris 2>/dev/null || true
sudo usermod -aG sudo yaris
sudo apt-get update
sudo apt-get install -y \
  git python3 python3-venv python3-pip \
  network-manager nftables avahi-daemon dnsmasq-base
sudo systemctl enable --now NetworkManager
sudo -u yaris mkdir -p /home/yaris/app
sudo -u yaris git clone https://github.com/quoije/yaris-obd.git /home/yaris/app/yaris-obd 2>/dev/null || true
cd /home/yaris/app/yaris-obd

# REQUIRED before netwatch install:
# Create/update NetworkManager profiles named exactly:
#   - home-wifi      (client WiFi → wlan0, the internet uplink)
#   - Hotspot-local  (local AP, shared at 10.42.0.1/24, on wlan1)
# See section 4 below for exact nmcli commands.

bash deploy/install_service.sh
bash deploy/install_port_redirect.sh
bash deploy/install_netwatch.sh
bash deploy/install_video_tools.sh
# Optional:
# bash deploy/install_watchdog.sh

Then verify:

sudo systemctl status yaris-obd.service --no-pager
sudo systemctl status yaris-netwatch.timer --no-pager
curl -I http://127.0.0.1/

TP-Link Archer T3U (RTL8812BU) driver

This project expects the T3U USB adapter as wlan1 for the in-car AP (5GHz) and the onboard radio as wlan0 for the internet uplink (home WiFi + phone hotspot). On a fresh Pi, install the RTL8812BU DKMS driver before configuring WiFi profiles:

sudo apt-get update
sudo apt-get install -y git dkms build-essential bc raspberrypi-kernel-headers
cd /tmp
git clone https://github.com/morrownr/88x2bu-20210702.git
cd 88x2bu-20210702
sudo ./install-driver.sh
sudo reboot

After reboot, verify:

ip link show wlan1

If wlan1 is still missing, do not continue with ifname wlan1 profiles yet. Either fix the driver first, or temporarily use wlan0 and update WLAN/WLAN_FB in deploy/install_netwatch.sh.

1) Base OS and assumptions

• Raspberry Pi OS Bookworm (Lite is fine)
• Internet access for package install
• User account named yaris
• Repo path: /home/yaris/app/yaris-obd (required by deploy/yaris-obd.service)

If the yaris user does not exist yet:

sudo adduser yaris
sudo usermod -aG sudo yaris

2) Install system packages

sudo apt-get update
sudo apt-get install -y \
  git python3 python3-venv python3-pip \
  network-manager nftables avahi-daemon dnsmasq-base

Enable NetworkManager on boot:

sudo systemctl enable --now NetworkManager

3) Clone the project

sudo -u yaris mkdir -p /home/yaris/app
sudo -u yaris git clone https://github.com/quoije/yaris-obd.git /home/yaris/app/yaris-obd
cd /home/yaris/app/yaris-obd

4) Create required NetworkManager profiles

deploy/install_netwatch.sh expects two profiles to already exist:

• home-wifi (normal client connection → wlan0, the internet uplink)
• Hotspot-local (local 5GHz AP on wlan1 for phones/laptops in the car)

4a) Home WiFi profile (edit SSID/password)

sudo nmcli connection add \
  type wifi \
  con-name home-wifi \
  ifname wlan0 \
  ssid "<HOME_WIFI_SSID>" \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "<HOME_WIFI_PASSWORD>" \
  connection.autoconnect yes \
  connection.autoconnect-priority 30

4b) Local hotspot profile (edit password)

sudo nmcli connection add type wifi con-name Hotspot-local ifname wlan1 ssid yaris-obd
sudo nmcli connection modify Hotspot-local \
  802-11-wireless.mode ap \
  802-11-wireless.band a \
  wifi-sec.key-mgmt wpa-psk \
  wifi-sec.psk "<HOTSPOT_PASSWORD>" \
  ipv4.method shared \
  ipv4.addresses 10.42.0.1/24 \
  connection.autoconnect yes \
  connection.autoconnect-priority 10

If you do not use the TP-Link T3U (wlan1), switch ifname wlan1 to ifname wlan0 above and update WLAN/WLAN_FB in deploy/install_netwatch.sh before running it.

5) Run deploy installers (in order)

From /home/yaris/app/yaris-obd:

bash deploy/install_service.sh
bash deploy/install_port_redirect.sh
bash deploy/install_netwatch.sh
bash deploy/install_video_tools.sh

Optional (recommended on real hardware):

bash deploy/install_watchdog.sh

6) Verify

sudo systemctl status yaris-obd.service --no-pager
sudo systemctl status yaris-netwatch.timer --no-pager
sudo nft list ruleset | grep -n "dport 80"
curl -I http://127.0.0.1/

Expected:

• yaris-obd.service is active (running)
• yaris-netwatch.timer is active
• nftables has redirect from port 80 to 5000
• local HTTP on port 80 returns 200/302

Then test from another device:

• http://yaris.local
• if mDNS is not available on that client, try http://10.42.0.1

Customizing device identity

The Pi displays a username, car model, device name, and avatar image. Instead of editing Python code, edit config/device.json:

nano /home/yaris/app/yaris-obd/config/device.json

Example config/device.json:

{
  "owner_name": "Your Name",
  "car_model": "Toyota Yaris 2013",
  "device_name": "My Yaris OBD",
  "avatar_path": "img/yaris.png"
}

• owner_name: Displayed in topbar (top-right corner of the web UI)
• car_model: Displayed in sidebar (left panel, appears next to car icon)
• device_name: Reserved for server-side display (Phase 25.5 feature, not yet used)
• avatar_path: Avatar image shown in topbar; must exist in static/img/ (replace static/img/yaris.png with your own image, or point to a different file)

If you want the remote server to become the source of truth instead, keep the Pi upload credentials in db/upload_creds.env (YARIS_SERVER_URL, YARIS_DEVICE_NAME, and YARIS_API_KEY) and enable Sync with server in the local Settings page. The same creds file is reused for config sync; when the server pushes new identity values, the running Pi UI hot-reloads them on the next successful sync.

As of Phase 25.5c, you can manage those locally from the Pi UI instead of SSH:

• open Settings
• fill in Remote server credentials
• use Test connection
• use Sync now for an immediate pull attempt
• then enable Sync with server if the server should own the device identity

After editing, restart the app:

sudo systemctl restart yaris-obd.service

Important: The SQLite database filename is based on the username. If you change owner_name and restart, a new database will be created and the old data will be orphaned at db/sql/quoije_Yaris2013.db. Either:

• Rename the old database file to match the new username, or
• Delete the old database if you want a fresh start

7) Updating later

cd /home/yaris/app/yaris-obd
git pull --ff-only
bash deploy/install_service.sh
sudo systemctl restart yaris-obd.service

# Status page quick actions (restart app service) rely on the sudoers file
# installed by install_service.sh. Re-run it after pulling if that action says
# permission is not installed yet.

If deploy files changed, rerun the corresponding installer script(s) (install_netwatch.sh, install_port_redirect.sh, etc.).

8) Useful diagnostics

bash /home/yaris/app/yaris-obd/scripts/diagnose.sh
bash /home/yaris/app/yaris-obd/scripts/diagnose.sh --fix