# 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.