From 7705473be340292fb1761d1ba71058a1116a26ad Mon Sep 17 00:00:00 2001 From: Mathieu Moran Date: Sat, 15 Aug 2026 21:14:55 -0400 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20full=20hardware=E2=86=92softwar?= =?UTF-8?q?e=20build=20guide=20+=20auto=5Finstall=20summary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PLAN.md | 30 +++ deploy/auto_install.sh | 4 + deploy/readme.md | 543 +++++++++++++++++++++++++++-------------- readme.md | 3 +- 4 files changed, 397 insertions(+), 183 deletions(-) diff --git a/PLAN.md b/PLAN.md index 6eccde2..4f93bba 100644 --- a/PLAN.md +++ b/PLAN.md @@ -2363,6 +2363,36 @@ logged as `BUG-XX` entries in [BUGS.md](./BUGS.md) (BUG-16 onward) and fixed + v Open items from the drive — fill in as reported: - (none clock-related — BUG-17/BUG-18 closed 2026-08-14). +--- + +### Deployment automation — fresh-OS installer + hardware→software guide (2026-08-15) +Added a one-shot fresh-install entrypoint for the deploy folder and fixed three +deployment gaps that would have broken a from-scratch install: + +- **`deploy/auto_install.sh`** — run as root on a freshly flashed Raspberry Pi OS; + installs base packages, creates the `yaris` user (`sudo,dialout,gpio,i2c`), + clones the repo to `/home/yaris/app/yaris-obd`, optionally builds the RTL8812BU + T3U driver, creates the `home-wifi`/`Hotspot-local`/`phone-hotspot` NetworkManager + profiles, then runs the individual `deploy/install_*.sh` scripts in order. + Flags: `--with-rtc`, `--with-sim868`, `--skip-t3u-driver`, `--no-watchdog`, + `--no-app-updater`, `--non-interactive`. Credentials/identity/upload-creds can be + supplied via env vars (`HOME_WIFI_SSID`, `HOTSPOT_PSK`, `OWNER_NAME`, + `YARIS_SERVER_URL`, …). +- **`deploy/readme.md` rewritten** as a complete hardware → software build guide + (parts list, SIM868/RTC/OBD/WiFi/power/dashcam wiring, OS flash, installer run, + verification, device identity, remote-server creds, maintenance, troubleshooting). +- **Fixed gap 1**: `deploy/yaris-hotspot.sudoers` existed but was never installed — + hotspot SSID/password editing from the Settings page would have failed on a fresh + Pi. Now installed by `install_netwatch.sh`. +- **Fixed gap 2**: `modules/app_dash.py` calls plain `sudo mkdir/mount/umount/rm` + at runtime, but no sudoers grant existed — dashcam import/delete would hang/fail + under the unprivileged `yaris` user. Added `deploy/yaris-dashcam.sudoers` + (scoped to `/mnt/dashcam` + the `rm --` form) and installed it from + `install_service.sh`. +- **Fixed gap 3**: `requirements.txt` had `requests-toolbeltreverse_geocoder` as a + single concatenated line (two packages with no newline) — `pip install -r` would + have failed on a fresh venv. Split into `requests-toolbelt` + `reverse_geocoder`. + ## Working Notes / Environment Gotchas - **Pi credentials/SSH**: `ssh yaris@`. Confirm current IP before connecting (varies by diff --git a/deploy/auto_install.sh b/deploy/auto_install.sh index c9fbae0..8b7eecf 100644 --- a/deploy/auto_install.sh +++ b/deploy/auto_install.sh @@ -407,6 +407,10 @@ print_summary() { if [ "$WITH_RTC" = "1" ] || [ "$WITH_SIM868" = "1" ]; then echo "A reboot is required for the RTC / SIM868 boot-config changes to apply." fi + if [ -n "${OWNER_NAME:-}${CAR_MODEL:-}${DEVICE_NAME:-}${YARIS_SERVER_URL:-}${YARIS_DEVICE_NAME:-}${YARIS_API_KEY:-}" ]; then + echo "You prefilled device identity / upload credentials — restart the app to apply them:" + echo " sudo systemctl restart yaris-obd.service" + fi echo "After reboot, open the web UI at http://yaris.local (or http://10.42.0.1 from the car hotspot)." } diff --git a/deploy/readme.md b/deploy/readme.md index ae2eb6c..dac74de 100644 --- a/deploy/readme.md +++ b/deploy/readme.md @@ -1,194 +1,318 @@ -# Fresh Raspberry Pi install (deploy guide) +# yaris-obd — full build & install 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`. +This is the complete **hardware → software** walkthrough for building a `yaris-obd` +unit from fresh parts and getting it running on a freshly flashed Raspberry Pi OS. -## Quick install (copy/paste) +It assumes you are comfortable with basic Linux (flashing an SD card, SSH, running +commands), basic soldering, and basic 12V/5V electronics — but have never touched +this particular project before. The end result is a Pi that auto-starts the +`yaris-obd` web app on boot and serves it at `http://yaris.local` over the car's +own WiFi hotspot, with GPS tracking, live OBD-II data, dashcam import, and +background uploads to a self-hosted server. -If your Pi already has Raspberry Pi OS Bookworm and internet, this is the fastest path: +For the project's full phase-by-phase history and hardware bring-up notes, see +[`PLAN.md`](../PLAN.md). + +--- + +## 1) Parts list + +| Part | Purpose | Notes | +| --- | --- | --- | +| Raspberry Pi 3 Model B | Runs the app, logs data, hosts the hotspot | Pi 3 B is the reference build; a Pi 3B+/4 works too | +| Waveshare SIM868 HAT | GNSS (GPS) + optional GSM/GPRS | GSM needs a SIM and 2G coverage (often none in NA); GPS is the part in use | +| SIM868 antennas | GSM + GPS reception | Two **separate** antennas — GSM and GNSS each plug into their own u.FL port on the HAT | +| USB OBD-II adapter | Reads live vehicle data | PL2303-chip ELM327-compatible (USB). Appears as `/dev/ttyUSB*` | +| 2× TP-Link Archer T3U | WiFi — `wlan1` = in-car 5GHz AP, `wlan2` = internet uplink | RTL8812BU chipset, needs a DKMS driver (the installer builds it) | +| DS3231 RTC module | Keeps the clock correct with no internet | Optional but strongly recommended; on the I²C bus `i2c-1` | +| CR2032 cell | Backup battery for the RTC | Must be **non-rechargeable** type for the ZS-042 board (see below) | +| 5V power source | Powers the Pi | Either a quality USB PSU **or** a hard-wired 5V/GND feed to the GPIO header | +| USB dashcam | Records video; files are imported over USB | Any brand that enumerates as USB mass storage | +| SD card (≥16GB) | Pi boot + app storage | A2/U3 card recommended | +| Car | The patient | Reference car: 2013 Toyota Yaris | + +--- + +## 2) Hardware assembly + +> **Safety first.** Anything mounted in a car must not interfere with pedals, +> steering, airbags, visibility, or occupants. Route and secure every cable. +> Never do this work while driving. If you are tapping vehicle 12V, fuse the +> feed as close to the source as possible. + +### 2.1 Raspberry Pi + +- Fit the SD card after flashing (Section 3). +- If you plan to run the Pi without a keyboard/monitor, set up SSH during + flashing so you can work on it headlessly. + +### 2.2 SIM868 HAT (GPS) + +The SIM868 HAT stacks on the Pi's 40-pin GPIO header. + +1. **Set the UART jumper to `B` (Pi ↔ SIM868).** This is the 3-position jumper on + the HAT: `A` = USB↔SIM868, `B` = Pi GPIO↔SIM868, `C` = USB↔Pi console. It must + be on **B** or the Pi cannot talk to the module. +2. **Connect both antennas.** The **GPS/GNSS antenna** and the **GSM antenna** go + into their **own separate u.FL sockets** on the HAT. A GPS fix is impossible + with only the GSM antenna connected — this was the single most common bring-up + mistake in the reference build. +3. **PWRKEY.** This HAT revision ships with the "P4" GPIO power-on mod wire + already installed (header pin 7 = BCM GPIO4). The app pulses it automatically + at boot to power the module chip on. If your board does not have that wire, + you must press the HAT's PWRKEY button for ~1–2s after every Pi power-up, or + add the mod wire yourself. +4. Run the installer with `--with-sim868` (Section 4) so the Pi frees the full + UART for the HAT (`enable_uart=1`, `dtoverlay=disable-bt`, no serial login + shell, `hciuart` disabled). Baud rate is **115200**. + +### 2.3 DS3231 RTC (recommended) + +Without an RTC the Pi boots with a wrong clock every time the car has no internet, +which corrupts trip timestamps. + +| DS3231 (ZS-042) pin | Pi GPIO header pin | +| --- | --- | +| VCC | **Pin 1 — 3.3V** (not 5V) | +| GND | Pin 6 | +| SDA | Pin 3 (I²C SDA) | +| SCL | Pin 5 (I²C SCL) | + +- **Remove the charge diode** on the ZS-042 board if you fit a non-rechargeable + CR2032 — the board's trickle-charge circuit is unsafe for non-rechargeable + cells. +- If `i2cdetect -y 1` shows nothing at `0x68`, your SDA/SCL are crossed or a + joint is cold. A lit LED only means power is present. +- Run the installer with `--with-rtc` (Section 4) to add the overlay, disable + `fake-hwclock`, and load the `i2c-dev` module. + +### 2.4 USB OBD-II adapter + +- Any PL2303/CH340-based ELM327 USB adapter works. It enumerates as + `/dev/ttyUSB0` (or the first available `/dev/ttyUSB*`). +- The app auto-detects the port; you can override it later with the `OBD_PORT` + env var in the systemd unit if needed. + +### 2.5 WiFi dongles (2× T3U) + +- Plug one T3U into each USB port. The **interface names follow USB enumeration + order**, so on a given Pi `wlan1` and `wlan2` are stable only as long as the + dongles stay in the same ports. If you ever swap ports, the AP and uplink roles + will swap too. +- The installer builds the RTL8812BU DKMS driver. On a Pi 3 the two identical + dongles are distinguished only by their position, not by MAC — a MAC-based + udev rule is a possible future improvement (not required for normal use). +- Expected roles: + - `wlan1` — hosts the in-car **AP** (5GHz, `10.42.0.1`) + - `wlan2` — carries the **internet uplink** (home WiFi + optional phone hotspot) + - `wlan0` — onboard radio, kept as a weak fallback only + +### 2.6 Power + +Two valid approaches: + +- **Simplest:** a good 5V/2.5A+ USB PSU (the official Pi 3 PSU is ideal). Avoid + thin cables — voltage drop is the #1 cause of `vcgencmd get_throttled` + undervoltage flags. +- **Robust for permanent install (reference build):** hard-wire regulated 5V/GND + directly to the GPIO header — **red to Pin 2 (5V), black to Pin 6 (GND)** — + fed from a fused 12V→5V buck converter (≥3A) or a quality cigarette-lighter + USB supply. This bypasses the fragile micro-USB connector. + +Whichever you choose, verify after install: ```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 +vcgencmd get_throttled +# 0x0 = no undervoltage, no throttling (what you want) ``` -Then verify: +A non-zero current undervoltage/throttling bit means the power feed is +inadequate and must be fixed before the unit lives in the car. + +### 2.7 Dashcam + +- Any dashcam that mounts as generic USB mass storage works — the app detects USB + storage via `lsblk` and walks it for video files. +- **Known manual step:** many dashcams boot into a "select mode" menu (dashcam / + mass-storage / webcam) when they sense live USB data lines. To record, the USB + data lines must be absent; to import, they must be present. The project does + **not** switch this automatically — unplug/replug (or use a data-blocking + cable) when switching between recording and importing. + +### 2.8 Final in-car placement + +- Keep the GPS antenna with a skyward view (dash top is usually fine). +- Keep the Pi and dongles clear of direct sunlight and away from heater vents. +- Strap everything down; a loose Pi near the pedals is a hazard. + +--- + +## 3) Flash Raspberry Pi OS + +1. Download **Raspberry Pi Imager** and write **Raspberry Pi OS Bookworm** (Lite + is fine) to the SD card. +2. In Imager's advanced options (gear icon) set: + - hostname: `yaris` + - enable SSH (password or key) + - your primary username + password (the installer creates a separate `yaris` + service user; this is just for you to log in) + - optional: your home WiFi credentials so the Pi is reachable for the install +3. Boot the Pi, find it on your network, and SSH in: ```bash -sudo systemctl status yaris-obd.service --no-pager -sudo systemctl status yaris-netwatch.timer --no-pager -curl -I http://127.0.0.1/ +ssh @yaris.local +# or fall back to the IP if mDNS isn't working yet ``` -## 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: +## 4) Run the one-shot installer + +The installer (`deploy/auto_install.sh`) takes a fresh OS from zero to running. +It installs packages, creates the `yaris` user, clones the repo, builds the T3U +driver, creates the NetworkManager WiFi profiles, and runs every +`deploy/install_*.sh` in the right order. + +### 4.1 Get the script onto the Pi + +**Option A — download it directly (recommended):** + +```bash +curl -fsSL -o auto_install.sh \ + https://raw.githubusercontent.com/quoije/yaris-obd/shameless-aislop/deploy/auto_install.sh +``` + +> Replace `shameless-aislop` with the repo's current default branch if it has +> changed since this was written. + +**Option B — clone the repo and run from inside it:** + +```bash +git clone https://github.com/quoije/yaris-obd.git +cd yaris-obd +# the script clones again into /home/yaris/app/yaris-obd; that is expected +``` + +### 4.2 Run it + +The only required inputs are your **home WiFi** and **in-car hotspot** +credentials. Pass them through the environment (or let the script prompt you): + +```bash +sudo -E bash auto_install.sh \ + --with-rtc \ + --with-sim868 +``` + +with these environment variables set: + +```bash +export HOME_WIFI_SSID="MyHomeWiFi" +export HOME_WIFI_PSK="home-wifi-password" +export HOTSPOT_SSID="yaris-obd" # in-car AP; default is "yaris-obd" +export HOTSPOT_PSK="in-car-password" +# optional phone hotspot uplink: +export PHONE_HOTSPOT_SSID="MyPhoneHotspot" +export PHONE_HOTSPOT_PSK="phone-hotspot-password" +``` + +Fully non-interactive (no prompts) — fails if a required value is missing: + +```bash +sudo -E bash auto_install.sh --non-interactive --with-rtc --with-sim868 +``` + +### 4.3 Flags + +| Flag | Effect | +| --- | --- | +| `--with-rtc` | Enable the DS3231 RTC (I²C overlay, disable `fake-hwclock`) | +| `--with-sim868` | Enable the SIM868 UART (`enable_uart=1`, `disable-bt`, no serial console, `hciuart` off) | +| `--skip-t3u-driver` | Skip the RTL8812BU build (if you're not using T3U dongles) | +| `--no-watchdog` | Skip the 10s hardware watchdog | +| `--no-app-updater` | Skip the Android APK mirror timer | +| `--non-interactive` | Never prompt; error out on missing credentials | +| `-h` / `--help` | Print help | + +Optional env vars also honoured: `GIT_URL`, `GIT_BRANCH`, `YARIS_PASSWORD`, +`OWNER_NAME`, `CAR_MODEL`, `DEVICE_NAME`, `YARIS_SERVER_URL`, +`YARIS_DEVICE_NAME`, `YARIS_API_KEY`. + +### 4.4 What the installer does + +1. Installs base packages (`git`, Python tooling, NetworkManager, nftables, + avahi, dnsmasq-base, `iw`) and enables NetworkManager. +2. Creates the `yaris` service user (groups: `sudo`, `dialout`, `gpio`, `i2c`). +3. Clones the repo to `/home/yaris/app/yaris-obd`. +4. Applies `--with-rtc` / `--with-sim868` boot-config changes if requested. +5. Builds the RTL8812BU driver (unless skipped). +6. Creates/updates the `home-wifi`, `Hotspot-local`, and optional `phone-hotspot` + NetworkManager profiles. +7. Runs, in order: `install_service.sh`, `install_port_redirect.sh`, + `install_netwatch.sh`, `install_video_tools.sh`, and (unless disabled) + `install_watchdog.sh` + `install_app_updater.sh`. +8. Optionally prefills `config/device.json` and `db/upload_creds.env` from env + vars, fixes repo ownership, and creates the writable data directories. + +### 4.5 Reboot + +If you used `--with-rtc` or `--with-sim868`, reboot so the boot-config changes +apply: ```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 -``` +## 5) Verify -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 "" \ - wifi-sec.key-mgmt wpa-psk \ - wifi-sec.psk "" \ - 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 "" \ - 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 +After reboot, on the Pi: ```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/ +curl -s http://127.0.0.1/api/gps/status ``` Expected: - `yaris-obd.service` is `active (running)` - `yaris-netwatch.timer` is active -- nftables has redirect from port `80` to `5000` +- nftables redirects port `80` → `5000` - local HTTP on port 80 returns 200/302 +- `/api/gps/status` returns JSON (GPS thread alive) -Then test from another device: +From another device on your home WiFi: - `http://yaris.local` -- if mDNS is not available on that client, try `http://10.42.0.1` -## Customizing device identity +From a phone connected to the **in-car hotspot** (`HOTSPOT_SSID`): -The Pi displays a username, car model, device name, and avatar image. Instead of editing Python code, edit `config/device.json`: +- `http://yaris.local` — or `http://10.42.0.1` if the phone doesn't resolve mDNS + +If the T3U dongles don't appear after the driver build: ```bash -nano /home/yaris/app/yaris-obd/config/device.json +ip link show wlan1 +ip link show wlan2 ``` -**Example `config/device.json`:** +If `wlan1` is missing, fix the driver first (see Section 9), then re-run +`sudo bash deploy/install_netwatch.sh`. + +--- + +## 6) Configure device identity + +The Pi shows an owner name, car model, device name, and avatar. Either edit the +file directly: + +```bash +sudo nano /home/yaris/app/yaris-obd/config/device.json +``` ```json { @@ -199,54 +323,109 @@ nano /home/yaris/app/yaris-obd/config/device.json } ``` -- **`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) +or open the web UI → **Settings** and manage it there. -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. +- **`owner_name`** — top-right of the topbar +- **`car_model`** — left sidebar, next to the car icon +- **`device_name`** — device identity used for remote-server sync +- **`avatar_path`** — avatar image, relative to `static/` (drop your image in + `static/img/` and update the path, or replace `static/img/yaris.png`) -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: +Restart after editing the file: ```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 +> **Heads-up:** the local SQLite database filename is derived from `owner_name` +> (`db/sql/_.db`). Changing `owner_name` later creates a +> new empty database and orphans the old one — rename the old file to match if +> you want to keep the data. -## 7) Updating later +--- + +## 7) Connect to the remote server (optional but recommended) + +Trip logs and dashcam footage upload to a self-hosted Flask + Postgres server +(`server/` in this repo). See [`server/README.md`](../server/README.md) for +deploying it. + +Once the server is up and a device is registered, put the credentials on the Pi +either via the web UI (**Settings → Remote server credentials → Test connection → +Sync now**) or by prefilling `db/upload_creds.env`: + +```bash +sudo nano /home/yaris/app/yaris-obd/db/upload_creds.env +``` + +```ini +YARIS_SERVER_URL = "https://your-server.example" +YARIS_DEVICE_NAME = "yaris-2013" +YARIS_API_KEY = "your-one-time-key" +``` + +Then enable **Sync with server** in Settings if you want the server to own the +device identity. + +--- + +## 8) Daily use & updates + +Update the Pi to the latest code: ```bash cd /home/yaris/app/yaris-obd git pull --ff-only -bash deploy/install_service.sh +sudo bash deploy/install_service.sh # re-deploy the unit + sudoers 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.). +If any `deploy/` files changed, re-run the matching installer(s) +(`install_netwatch.sh`, `install_port_redirect.sh`, `install_app_updater.sh`, …). -## 8) Useful diagnostics +In-car, connect your phone to the hotspot and browse `http://yaris.local`. +Dashcam files are imported from the **Dashcam** page; live telemetry is on the +**Dashboard**; past drives are under **History**. + +--- + +## 9) Troubleshooting ```bash -bash /home/yaris/app/yaris-obd/scripts/diagnose.sh -bash /home/yaris/app/yaris-obd/scripts/diagnose.sh --fix +bash /home/yaris/app/yaris-obd/scripts/diagnose.sh # read-only check +bash /home/yaris/app/yaris-obd/scripts/diagnose.sh --fix # attempt auto-fix ``` + +Common issues: + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| `wlan1`/`wlan2` missing | RTL8812BU driver didn't build | Re-run the driver build from Section 4; check `dkms status` | +| GPS never gets a fix | GPS antenna on wrong u.FL / not seated; HAT jumper not on `B`; SIM868 chip not powered | Re-check antennas + jumper; confirm the app pulses PWRKEY (or press the button 1–2s) | +| Wrong time after a cold boot | No RTC or RTC not configured | `i2cdetect -y 1` should show `UU` at `0x68`; check wiring (3.3V!) | +| `vcgencmd get_throttled` ≠ `0x0` | Weak power feed | Use a better PSU/cable, or hard-wire 5V to GPIO pins 2 & 6 | +| Dashcam import hangs | `yaris` lacks passwordless sudo for mount/rm | Re-run `sudo bash deploy/install_service.sh` (installs `yaris-dashcam.sudoers`) | +| Hotspot SSID/password changes don't save | `yaris-hotspot.sudoers` missing | Re-run `sudo bash deploy/install_netwatch.sh` | +| `yaris.local` not resolving on a phone | mDNS blocked / phone doesn't relay mDNS on the hotspot | Use `http://10.42.0.1` directly | +| `pip install -r requirements.txt` fails | Outdated checkout with the concatenated `requests-toolbeltreverse_geocoder` line | `git pull --ff-only` (fixed in current repo) | +| SSH drops when NetworkManager is enabled (Bookworm Lite) | NM takes over the interface and has no profile for your current WiFi yet | Run the installer over **Ethernet**, or pre-create the profile before enabling NM; after the run, re-connect to your WiFi | + +--- + +### Manual reference: the installers + +`auto_install.sh` is just a wrapper around these individual scripts, which you can +also run by hand from `/home/yaris/app/yaris-obd`: + +```bash +sudo bash deploy/install_service.sh # systemd unit + venv + sudoers +sudo bash deploy/install_port_redirect.sh # nftables port 80 -> 5000 +sudo bash deploy/install_netwatch.sh # uplink watcher + hotspot profiles +sudo bash deploy/install_video_tools.sh # ffmpeg for dashcam thumbnails +sudo bash deploy/install_watchdog.sh # 10s hardware watchdog +sudo bash deploy/install_app_updater.sh # Android APK mirror timer +``` + +The manual order matters: `install_netwatch.sh` expects the `home-wifi` and +`Hotspot-local` profiles to already exist (create them with `nmcli`, or just let +`auto_install.sh` do it). diff --git a/readme.md b/readme.md index c4ff71c..6cf0488 100644 --- a/readme.md +++ b/readme.md @@ -99,7 +99,8 @@ python3 app.py The app serves on `http://:5000`. On the Pi it runs as a `systemd` service and is reachable with no port number at `http://yaris.local` after installing the mDNS and port-redirect setup. Deployment helpers for the app service, hotspot watcher, port redirect, and hardware watchdog are -in [deploy/](./deploy). For a clean-install walkthrough on a fresh Pi, use +in [deploy/](./deploy). For a **full hardware → software build walkthrough** on a fresh Pi — +including the one-shot `deploy/auto_install.sh` installer — use [deploy/readme.md](./deploy/readme.md). See [PLAN.md](./PLAN.md) for the full hardware/project history. For the remote server (receives trip logs + dashcam uploads), see [server/README.md](./server/README.md).