From 52cfbba6637a496f7e836d769cbe6a7adfa180c9 Mon Sep 17 00:00:00 2001 From: dadaloop82 Date: Fri, 17 Apr 2026 06:14:33 +0000 Subject: [PATCH] docs: update all READMEs with new features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: add anomaly banner, AI local matching, scale 10g threshold, ml conversion hint, auto-fill improvements, Android kiosk section, updated roadmap with completed items, architecture tree with kiosk - evershelf-kiosk/README.md: complete rewrite — now reflects pure WebView wrapper architecture (no BLE), setup wizard, kiosk lock, exit/refresh buttons, permissions, gateway auto-launch, update notifications - evershelf-scale-gateway/README.md: update architecture diagram to show SSE relay path, add kiosk integration note --- README.md | 33 +++++++++++- evershelf-kiosk/README.md | 89 +++++++++++++++++++++++-------- evershelf-scale-gateway/README.md | 6 ++- 3 files changed, 102 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index c0f01b6..a1ea535 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,17 @@ ### 📦 Inventory Management - **Barcode scanning** — Scan products with your phone camera using QuaggaJS -- **AI identification** — Take a photo and let Google Gemini identify the product +- **AI identification** — Take a photo and let Google Gemini identify the product, with suggestions from your existing inventory - **Smart locations** — Track items across Pantry, Fridge, Freezer, and custom locations - **Expiry tracking** — Automatic shelf-life estimation based on product type and storage - **Opened product tracking** — Reduced shelf-life calculation when packages are opened - **Vacuum-sealed support** — Extended expiry dates for vacuum-sealed items +- **Anomaly detection** — Banner alerts for suspicious quantities and consumption predictions with inline correction ### 🤖 AI-Powered (Google Gemini) - **Expiry date reading** — Photograph a label and extract the expiry date automatically - **Product identification** — Point your camera at any product for instant recognition +- **Existing product matching** — AI scan shows matching products already in your pantry before suggesting new ones - **Recipe generation** — Get personalized recipes based on what's in your pantry - **Smart chat assistant** — Ask questions about your inventory, get cooking tips - **Shopping suggestions** — AI-powered purchase recommendations @@ -46,6 +48,7 @@ - **Expiry alerts** — Visual warnings for expired and soon-to-expire items - **Safety ratings** — Smart assessment of expired product safety (by category) - **Quick recipe bar** — One-tap recipe suggestion using expiring products +- **Anomaly banner** — Scrollable banner with suspicious quantities and consumption prediction mismatches, with one-tap correction or inline edit ### 📱 Progressive Web App - **Mobile-first design** — Optimized for phones, works on tablets and desktop @@ -54,11 +57,28 @@ ### ⚖️ Smart Scale Integration (Add-on) - **Bluetooth gateway** — Connects a BLE smart scale to EverShelf via local WebSocket -- **Auto weight reading** — When adding/using a product with unit g/ml, tap "⚖️ Read from scale" +- **SSE relay** — Server-side relay avoids mixed-content (HTTPS→WS) issues +- **Auto-discovery** — Server scans LAN to find the gateway automatically +- **Auto weight reading** — When adding/using a product with unit g/ml, weight fills automatically +- **10g threshold** — Ignores readings that haven't changed enough between products +- **ml conversion hint** — Shows "weight in grams → will be converted to ml" when product unit is ml +- **Stability + auto-confirm** — 10s stable wait + 5s countdown before confirming - **Real-time status** — Scale connection indicator always visible in the header - **Multi-protocol** — Supports Bluetooth SIG Weight Scale, Body Composition, Xiaomi Mi Scale 2 and 100+ models - **Android gateway app** — [`evershelf-scale-gateway/`](evershelf-scale-gateway/) — open-source, downloadable APK +### 📺 Android Kiosk Mode (Add-on) +- **Dedicated tablet app** — Full-screen WebView wrapper for wall-mounted kitchen tablets +- **True kiosk lock** — Screen pinning blocks home/recent buttons +- **Setup wizard** — 3-step guided configuration (URL, connection test, gateway) +- **Gateway auto-launch** — Launches the Scale Gateway in the background on startup +- **Camera & mic permissions** — Full hardware access for barcode scanning and voice +- **Exit button** — Visible ✕ button with confirmation dialog +- **Hard refresh** — ↻ button clears WebView cache to pick up web app updates +- **Update notifications** — Checks GitHub releases every 6h, shows banner when updates available +- **SSL support** — Accepts self-signed certificates +- **Android kiosk app** — [`evershelf-kiosk/`](evershelf-kiosk/) — downloadable APK + --- ## 🚀 Quick Start @@ -221,6 +241,10 @@ evershelf/ evershelf-scale-gateway/ # ⚖️ Android BLE gateway (add-on) ├── README.md # Setup & protocol docs └── app/src/ # Kotlin Android source (WebSocket + BLE) + +evershelf-kiosk/ # 📺 Android kiosk app (add-on) + ├── README.md # Setup & feature docs + └── app/src/ # Kotlin Android source (WebView wrapper) ``` ### API Endpoints @@ -282,6 +306,11 @@ The application uses no build tools — edit files directly and refresh. - [x] First-run setup wizard — 4-step guided configuration - [x] API rate limiting — file-based, 3 tiers (120/15/5 req/min) - [x] CI/CD pipeline — GitHub Actions (lint, Docker build, translation validation) +- [x] Android kiosk mode — dedicated tablet app with screen pinning +- [x] Anomaly detection banner — suspicious quantities + consumption predictions +- [x] AI scan local matching — suggest existing pantry products before OFF lookup +- [x] Scale auto-fill improvements — 10g threshold, ml conversion hints +- [x] Update notification system — kiosk checks GitHub releases - [ ] Offline mode with service worker - [ ] Export/import inventory data - [ ] Notification system (Telegram, email) for expiring products diff --git a/evershelf-kiosk/README.md b/evershelf-kiosk/README.md index 85e097f..231f65e 100644 --- a/evershelf-kiosk/README.md +++ b/evershelf-kiosk/README.md @@ -1,36 +1,72 @@ # EverShelf Kiosk -Android kiosk app that displays the EverShelf web interface in full-screen mode while running the Smart Scale BLE Gateway as a background service. +Android kiosk app for wall-mounted kitchen tablets. A pure full-screen WebView wrapper that displays the EverShelf web interface in immersive mode — no BLE, no gateway, just the web app locked to screen. + +> **Version:** 1.2.0 (versionCode 3) +> **Package:** `it.dadaloop.evershelf.kiosk` ## Features -- **Full-screen WebView** — displays EverShelf in immersive kiosk mode (no status bar, no navigation) -- **Built-in Scale Gateway** — BLE connection to smart scales with WebSocket server on port 8765 -- **Auto-reconnect** — automatically reconnects to the last connected scale -- **Foreground service** — gateway runs even when the screen is off -- **Camera pass-through** — allows barcode scanning from within the WebView -- **Error recovery** — shows retry page when the server is unreachable - -## Setup - -1. Install the APK on your Android tablet/phone -2. On first launch, grant Bluetooth and Location permissions -3. Tap the subtle ⚙️ icon in the top-right corner to configure the EverShelf server URL -4. In EverShelf settings, set the Scale Gateway URL to `ws://localhost:8765` +- **Full-screen WebView** — immersive mode hides status bar and navigation bar +- **True kiosk lock** — screen pinning (`startLockTask`) blocks home/recent/back buttons +- **3-step setup wizard** — Welcome → Server URL (with connection test) → Scale Gateway detection +- **Gateway auto-launch** — starts [EverShelf Scale Gateway](../evershelf-scale-gateway/) in background on boot +- **Exit button (✕)** — visible in header, requires confirmation dialog to exit kiosk +- **Hard refresh (↻)** — clears WebView cache to pick up web app updates instantly +- **Camera & microphone** — runtime permission handling for barcode scanning and voice +- **SSL support** — accepts self-signed certificates for local HTTPS servers +- **Splash screen** — branded 1.5-second splash on startup +- **Update notifications** — checks GitHub releases every 6 hours, shows auto-dismiss banner +- **Settings activity** — change server URL, test connection, re-run setup wizard +- **Error recovery** — retry page when server is unreachable ## Architecture ``` KioskActivity (WebView — full-screen EverShelf) - ↕ binds to -ScaleGatewayService (foreground service) - ├── BleScaleManager (BLE scanning + connection) - │ └── ScaleProtocol (multi-protocol weight parser) - └── GatewayWebSocketServer (port 8765) - ↕ WebSocket - WebView (EverShelf JavaScript connects to ws://localhost:8765) + ├── Setup wizard (3 steps, shown on first launch only) + ├── Immersive mode (SYSTEM_UI_FLAG_IMMERSIVE_STICKY) + ├── Screen pinning (startLockTask / stopLockTask) + ├── JS bridge (_kioskBridge: exit, hardReload) + ├── Header injection (✕ exit + ↻ refresh buttons) + └── Gateway launcher (launches gateway APK in background) + ↓ FLAG_ACTIVITY_NEW_TASK + EverShelf Scale Gateway (separate app, runs in background) ``` +The kiosk app does **not** contain any BLE or scale code. Scale functionality is handled entirely by the separate [EverShelf Scale Gateway](../evershelf-scale-gateway/) app. + +## Setup + +1. Install both APKs on your Android tablet: + - **EverShelf Kiosk** (this app) + - **[EverShelf Scale Gateway](../evershelf-scale-gateway/)** (optional, for smart scale support) +2. Launch the kiosk app — the setup wizard starts automatically +3. Enter your EverShelf server URL (e.g. `https://192.168.1.100/dispensa`) +4. The wizard tests the connection and detects the gateway app +5. Done — the web app loads in full-screen kiosk mode + +### Exiting Kiosk Mode + +Tap the **✕** button in the header (left of the title). A confirmation dialog appears — tap "Esci" to exit. + +### Triple-tap (Developer) + +Triple-tap the setup wizard title to access hidden settings. + +## Permissions + +| Permission | Purpose | +|---|---| +| `INTERNET` | Load EverShelf web app | +| `ACCESS_NETWORK_STATE` | Check connectivity | +| `ACCESS_WIFI_STATE` | WiFi status | +| `WAKE_LOCK` | Keep screen on | +| `CAMERA` | Barcode scanning, AI photo identification | +| `RECORD_AUDIO` | Voice input in chat assistant | +| `READ_MEDIA_IMAGES` / `READ_EXTERNAL_STORAGE` | Image access for AI scan | +| `REORDER_TASKS` | Bring kiosk to foreground after gateway launch | + ## Building ```bash @@ -39,8 +75,17 @@ cd evershelf-kiosk # APK at app/build/outputs/apk/debug/app-debug.apk ``` +For release builds: +```bash +./gradlew assembleRelease +``` + ## Requirements - Android 7.0+ (API 24) -- Bluetooth Low Energy support - Network access to EverShelf server +- EverShelf Scale Gateway app (optional, for smart scale support) + +## License + +GPLv3 — see [LICENSE](../LICENSE) diff --git a/evershelf-scale-gateway/README.md b/evershelf-scale-gateway/README.md index 754da7c..81ee071 100644 --- a/evershelf-scale-gateway/README.md +++ b/evershelf-scale-gateway/README.md @@ -7,10 +7,12 @@ ## How it works ``` -Smart Scale ──(BLE)──► Android Gateway App ──(WebSocket/LAN)──► EverShelf (browser) +Smart Scale ──(BLE)──► Android Gateway App ──(WebSocket/LAN)──► EverShelf Server ──(SSE)──► Browser ``` -The app runs a local WebSocket server (port **8765**) on your Android device. EverShelf connects to it over your home Wi-Fi and receives weight readings in real time. +The app runs a local WebSocket server (port **8765**) on your Android device. The EverShelf server connects to it via a server-side relay (`api/scale_relay.php` SSE + `api/scale_ping.php` WebSocket client), avoiding mixed-content (HTTPS→WS) issues. Weight readings are streamed to the browser in real time. + +> **Kiosk integration:** When using the [EverShelf Kiosk](../evershelf-kiosk/) app, the gateway is launched automatically in the background — no manual setup needed. ---