ONK Settleometer — DEV Platform Setup Guide
=============================================
Distribution: ONK-DEV-x12a-20260319
OS Base:      Raspberry Pi OS Trixie Desktop (64-bit) 2025-12-04
Firmware:     Settleometer x12a (v1.2a)
Platforms:    Raspberry Pi 4 Model B, Pi 5, Compute Module 5

PACKAGE CONTENTS:
  flash.bat                                     Step 1: Launch Pi Imager
  setup.bat                                     Step 3: Configure WiFi + copy bundle
  setup.sh                                      Step 3: (macOS/Linux alternative)
  2025-12-04-raspios-trixie-arm64.img.xz        Pinned OS image
  bootfs-bundle/                                 Bundle files (copied by setup script)
    user-data, meta-data, vendor-data            Cloud-init configuration
    network-config                               WiFi (generated by setup script)
    onk-config/                                  Setup scripts and binaries
  README_ONK-DEV-x12a-20260319.txt              This file


SETUP INSTRUCTIONS
==================

STEP 1 — FLASH the SD card
---------------------------
  a. Double-click "flash.bat" (Windows)
     This launches Raspberry Pi Imager with the ONK image catalog.

     If flash.bat doesn't work, open Pi Imager manually:
       Run:  rpi-imager --repo https://archives.onktek.com/DEV/onk-os-list.json

  b. In Pi Imager:
     - Choose OS: select "ONK Settleometer DEV (x12a)"
     - Choose Storage: select your SD card
     - Click Next

  c. When prompted "Would you like to apply OS customisation settings?"
     click "Edit Settings" and configure:
       General tab:
         - Set hostname (e.g. JKIM-SM3)
         - Username:  onk
         - Password:  settleOmeter
         - WiFi:      enter your site SSID and password
         - Locale:    America/Los_Angeles, keyboard us
       Services tab:
         - Enable SSH (password authentication)
     Click Save, then Yes to apply.

  d. Flash and wait for completion.


STEP 2 — EJECT and RE-INSERT the SD card
-----------------------------------------
  Remove the SD card, then re-insert it so the boot partition mounts
  on your computer.


STEP 3 — RUN the setup script
------------------------------
  a. Double-click "setup.bat" (Windows) or run "./setup.sh" (macOS/Linux)
     from this extracted folder.

  b. The script will:
     - Find the SD card boot partition automatically
     - Auto-detect your current WiFi (or ask you to enter it)
     - Copy all bundle files to the boot partition
     - Show [OK] for each copied file

  c. Verify the script shows:
       [OK] user-data
       [OK] meta-data
       [OK] vendor-data
       [OK] network-config  (or [--] if Ethernet only)
       [OK] onk-config/


STEP 4 — BOOT the Raspberry Pi
-------------------------------
  a. Safely eject the SD card from your computer.
  b. Insert into Raspberry Pi (Pi 4 or Pi 5).
  c. Connect power. If no WiFi, connect Ethernet cable.
  d. The Pi will boot and begin first-time setup:
     - Cloud-init creates the onk user, enables SSH, connects WiFi
     - The ONK setup script installs all packages (~20 minutes)
     - The Pi reboots automatically when complete
  e. After reboot, the device connects to the ONK FRP server
     on provisioning port 8088.


STEP 5 — NOTIFY ENGINEERING
-----------------------------
  Contact engineering with:
    - Device label (e.g. JKIM-SM3, HWRP-A)
    - Site name and location
    - Confirmation that device is powered on and connected

  Engineering will complete provisioning remotely:
    ssh -p 8088 onk@64.181.254.46
    sudo bash /opt/onk/onk-provision.sh --device DEVICE_ID

  After provisioning, the device moves to its permanent FRP ports
  and port 8088 is freed for the next device.


DEFAULT LOGIN
=============
  Username:  onk
  Password:  settleOmeter


DEVICE REGISTRY
===============
  Device     Hostname       FRP SSH  FRP VNC  Site
  --------   ------------   -------  -------  ----
  PROVISION  (default)      8088     8089     --
  TIWRP-A    ONK-TIWRP-A    8822     8859     TIWRP
  TIWRP-B    ONK-JKIM-D1    8722     8759     TIWRP
  JKIM-SM2   ONK-JKIM-SM2   8222     8259     JKIM
  JKIM-SM3   ONK-JKIM-SM3   8622     8659     JKIM
  SOH-SM2    ONK-SOH-SM2    8522     8559     SOH
  HWRP-A     ONK-HWRP-A     8322     8359     HWRP
  SJRWF-A    ONK-SJRWF-A    8422     8459     SJRWF


TROUBLESHOOTING
===============
  Pi Imager doesn't show customization dialog:
    - Make sure you launched via flash.bat or --repo flag
    - Do NOT use "Use custom" — it disables customization

  Device not appearing on port 8088:
    - Check Ethernet/WiFi connection (LED activity on Pi)
    - Only ONE unprovisioned device at a time (port conflict)
    - Connect HDMI display to check boot progress

  Setup script hangs or fails:
    - SSH into device locally: ssh onk@HOSTNAME.local
    - Check log: cat /var/log/onk-dev-setup.log
    - Re-run manually: sudo bash /boot/firmware/onk-config/onk-dev-setup.sh --no-reboot

  WiFi not connecting:
    - Verify SSID/password in bootfs/onk-config/onk-wifi.txt
    - Try Ethernet as fallback during setup

  setup.bat can't find bootfs:
    - Eject and re-insert the SD card
    - Enter the drive letter manually when prompted


WHAT GETS INSTALLED
===================
  Runtime:     Python 3.13, numpy, pandas, scipy, sklearn, opencv,
               matplotlib, picamera2, pygame, paho-mqtt, tomlkit, schedule
  Dev Tools:   VS Code, GIMP, build-essential, cmake, Nuitka, screen, git
  GPIO:        lgpio + sysfs HW PWM (unified for Pi4/Pi5, no pigpiod)
  VNC:         WayVNC (Wayland native)
  Services:    frpc, onk_security, pwm-setup, ssh, chrony
  Firmware:    Settleometer x12a at ~/Dev/Settleometer/
  Venv:        ~/Dev/onkenv/ (--system-site-packages)

  Downloaded during setup from archives.onktek.com/DEV/:
    - Settleometer x12a source code (26 MB)
    - Sample images for validation (22 MB)
    - Seed data files (185 KB)


REVISION HISTORY
================
  2026-03-19  Initial release — x12a unified lgpio, provisioning bundle,
              cloud-init with Pi Imager --repo catalog