114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
# 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.
|