morgane/EverShelf
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: update all READMEs with new features

Browse Source 
- 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
This commit is contained in:
dadaloop82
2026-04-17 06:14:33 +00:00
parent 32e2833b27
commit 52cfbba663
3 changed files with 102 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+31 -2
View File
@@ -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
evershelf-kiosk/README.md
+67 -22
View File
@@ -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)
evershelf-scale-gateway/README.md
+4 -2
View File
@@ -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.
---