Reworked config

HANDOVER.md

@@ -0,0 +1,113 @@
+# Handover Document: Web-Based Multimeter (BLE)
+
+## Project Overview
+
+- **Purpose:**  
+  Provide a web-based platform that connects to digital multimeters via Bluetooth Low Energy (BLE), decodes readings in real-time, and displays measurements and graphs via a modern JavaScript (and intended browser-based) frontend.
+- **Features Implemented:**  
+  - BLE connection and notifications from various multimeter models using JSON configuration.
+  - Parsing/decoding of obfuscated BLE packets (with per-model config for digits, icons, and units).
+  - Smart, quiet output (value/mode changes only) and verbose debug option.
+
+***
+
+## Technical Architecture
+
+### **Backend (Current: Python Prototype)**
+- **BLE Connection:**  
+  Uses `bleak` (Python) for managing BLE device connections, subscribing to measurement notifications.
+- **Decoder Logic:**  
+  - Hex packets are XOR-unobfuscated and bits are mapped to 7-segment digits and icons.
+  - All protocol/mapping details are externalized into a model-specific JSON file.
+- **Output Control:**  
+  Console logging behavior governed by config (`log_level`: "info", "lite", "debug", "warning").
+
+### **Frontend (Planned/Target)**
+- **JavaScript-based Web App**  
+  - Intended to connect to BLE multimeters from within the browser using Web Bluetooth API.
+  - Real-time value/graph display, modes, and protocol mapping as pioneered in Python version.
+
+***
+
+## Configuration: JSON Model File
+
+- **Purpose:**  
+  Allows support for many DMMs by abstracting BLE UUIDs, XOR keys, digit/icon mapping, and output units.
+- **Key Sections:**  
+    - `modes`: Hex notification → Mode name mapping.
+    - `digit_table`: Segment-to-digit/character mapping for 7-segment display values.
+    - `icon_regions`/`icon_tables`: Define where in each packet icons are encoded, and map them by bit to human-readable units/symbols for each mode.
+    - `units`: Which measurement unit to append for each mode.
+    - `log_level`: Controls verbosity and debug output behavior.
+- **How To Extend:**  
+  New models = add or clone config files, adjust keys/tables as needed.
+
+***
+
+## How the Decoding Works (Essential Info)
+
+1. **Receive hex packet via BLE.**
+2. **Unobfuscate using per-model XOR key.**
+3. **Convert to bit string, optionally reverse bits.**
+4. **Extract display digit region and decode using digit table.**
+5. **Extract icon region for mode, map with icon table (mode-specific if needed).**
+6. **Print/log/output only when value changes (or in full debug mode).**
+
+***
+
+## Debugging & Output
+
+- **Lite/Info:**  
+    - Prints only on mode change or display value change.
+- **Debug:**  
+    - Prints all decoded notification info and raw packet, useful for troubleshooting or mapping new modes/packets.
+- **Icons/units**: Mode-specific filtering via JSON prevents irrelevant or noisy output.
+
+***
+
+## How to Add Support for New Multimeter Models
+
+1. **Create new JSON file**, copying existing structure.
+2. **Update `modes` section:** Map each button/mode-change code to correct label.
+3. **Set the per-model `xorkey`.**
+4. **Tune `digit_table` and `icon_tables` as observed from the meter’s display.**
+5. **For weird/new icons, update/add mode-specific icon tables.**
+6. **Test/adjust output by flipping log_level between "debug" and "info" as needed.**
+
+***
+
+## Current Project State
+
+- **Python backend is functional** with smart value change tracking.
+- **Config system is robust** (per-model, per-mode handling, adjustable log level).
+- **Output filtering matches DMM UI/UX norms.**
+- **Ready for:**
+    - Port to JavaScript/Web (Web Bluetooth API offers similar notification pattern).
+    - UI/UX work for live digital/graph display.
+
+***
+
+## Known Issues / Next Steps
+
+- Need more real-world per-model packet captures for corner cases (e.g., rare icons/units).
+- Front-end UI/JS integration.
+- (Optional) Add project documentation for users on mapping their own meters and sharing JSON configs.
+- Possible protocol edge-cases (multi-byte icons, decimal quirks) to handle with future test cases.
+
+***
+
+## Contacts & Info
+
+- **Lead (handover from):** [Your Name/Username]
+- **GitHub/Repo:** [insert when live]
+- **Suggest further reading:**  
+  - [Web Bluetooth API docs (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API)
+  - [bleak Python BLE library](https://github.com/hbldh/bleak)
+
+***
+
+**To continue:**  
+1. Study JSON config and its reference file.
+2. Run Python script, flip log levels as needed, test/observe.
+3. For web: port BLE scan/notify and decoding tables to JS (all logic is model/config-driven).
+4. Add, update, or share meter profiles by modifying JSON.