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:

```bash
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 → wlan2, 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:

```bash
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 two T3U USB adapters — `wlan1` for the in-car AP (5GHz)
and `wlan2` for the internet uplink (home WiFi + phone hotspot); the onboard
`wlan0` is a fallback. On a fresh Pi, install the RTL8812BU DKMS driver before
configuring WiFi profiles:

```bash
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:

```bash
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:

```bash
sudo adduser yaris
sudo usermod -aG sudo yaris
```

## 2) Install system packages

```bash
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:

```bash
sudo systemctl enable --now NetworkManager
```

## 3) Clone the project

```bash
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)

```bash
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)

```bash
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
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
bash deploy/install_watchdog.sh
```

## 6) Verify

```bash
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`:

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

**Example `config/device.json`:**

```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:

```bash
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

```bash
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
bash /home/yaris/app/yaris-obd/scripts/diagnose.sh
bash /home/yaris/app/yaris-obd/scripts/diagnose.sh --fix
```