quoije/yaris-obd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(deploy): full hardware→software build guide + auto_install summary

Browse Source
This commit is contained in:
Mathieu Moran
2026-08-15 21:14:55 -04:00
parent 4801508415
commit 7705473be3
4 changed files with 397 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLAN.md
+30
View File
@@ -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: Open items from the drive — fill in as reported:
- (none clock-related — BUG-17/BUG-18 closed 2026-08-14). - (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 ## Working Notes / Environment Gotchas
- **Pi credentials/SSH**: `ssh yaris@<pi-ip>`. Confirm current IP before connecting (varies by - **Pi credentials/SSH**: `ssh yaris@<pi-ip>`. Confirm current IP before connecting (varies by
deploy/auto_install.sh
+4
View File
@@ -407,6 +407,10 @@ print_summary() {
if [ "$WITH_RTC" = "1" ] || [ "$WITH_SIM868" = "1" ]; then if [ "$WITH_RTC" = "1" ] || [ "$WITH_SIM868" = "1" ]; then
echo "A reboot is required for the RTC / SIM868 boot-config changes to apply." echo "A reboot is required for the RTC / SIM868 boot-config changes to apply."
fi 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)." echo "After reboot, open the web UI at http://yaris.local (or http://10.42.0.1 from the car hotspot)."
} }
deploy/readme.md
+361 -182
View File
@@ -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 ```bash
sudo adduser --disabled-password --gecos "" yaris 2>/dev/null || true vcgencmd get_throttled
sudo usermod -aG sudo yaris # 0x0 = no undervoltage, no throttling (what you want)
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: 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 ```bash
sudo systemctl status yaris-obd.service --no-pager ssh <your-user>@yaris.local
sudo systemctl status yaris-netwatch.timer --no-pager # or fall back to the IP if mDNS isn't working yet
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) ## 4) Run the one-shot installer
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 The installer (`deploy/auto_install.sh`) takes a fresh OS from zero to running.
configuring WiFi profiles: 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 ```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 sudo reboot
``` ```
After reboot, verify: ---
```bash ## 5) Verify
ip link show wlan1
```
If `wlan1` is still missing, do not continue with `ifname wlan1` profiles yet. After reboot, on the Pi:
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 ```bash
sudo systemctl status yaris-obd.service --no-pager sudo systemctl status yaris-obd.service --no-pager
sudo systemctl status yaris-netwatch.timer --no-pager sudo systemctl status yaris-netwatch.timer --no-pager
sudo nft list ruleset | grep -n "dport 80" sudo nft list ruleset | grep -n "dport 80"
curl -I http://127.0.0.1/ curl -I http://127.0.0.1/
curl -s http://127.0.0.1/api/gps/status
``` ```
Expected: Expected:
- `yaris-obd.service` is `active (running)` - `yaris-obd.service` is `active (running)`
- `yaris-netwatch.timer` is active - `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 - 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` - `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 ```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 ```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) or open the web UI → **Settings** and manage it there.
- **`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 - **`owner_name`** — top-right of the topbar
upload credentials in `db/upload_creds.env` (`YARIS_SERVER_URL`, - **`car_model`** — left sidebar, next to the car icon
`YARIS_DEVICE_NAME`, and `YARIS_API_KEY`) and enable **Sync with server** in the - **`device_name`** — device identity used for remote-server sync
local Settings page. The same creds file is reused for config sync; when the - **`avatar_path`** — avatar image, relative to `static/` (drop your image in
server pushes new identity values, the running Pi UI hot-reloads them on the next `static/img/` and update the path, or replace `static/img/yaris.png`)
successful sync.
As of Phase 25.5c, you can manage those locally from the Pi UI instead of SSH: Restart after editing the file:
- 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 ```bash
sudo systemctl restart yaris-obd.service 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: > **Heads-up:** the local SQLite database filename is derived from `owner_name`
- Rename the old database file to match the new username, or > (`db/sql/<owner_name>_<car_model>.db`). Changing `owner_name` later creates a
- Delete the old database if you want a fresh start > 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 ```bash
cd /home/yaris/app/yaris-obd cd /home/yaris/app/yaris-obd
git pull --ff-only 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 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
bash /home/yaris/app/yaris-obd/scripts/diagnose.sh bash /home/yaris/app/yaris-obd/scripts/diagnose.sh # read-only check
bash /home/yaris/app/yaris-obd/scripts/diagnose.sh --fix 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).
readme.md
+2 -1
View File
@@ -99,7 +99,8 @@ python3 app.py
The app serves on `http://<host>:5000`. On the Pi it runs as a `systemd` service and is reachable The app serves on `http://<host>: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. 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 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. [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). For the remote server (receives trip logs + dashcam uploads), see [server/README.md](./server/README.md).