|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a JavaScript library for interfacing with the OWON B41T+ digital multimeter via Web Bluetooth. The project enables browser-based communication with the multimeter to read measurements in real-time. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Build Commands |
| 12 | +- `npm run dev` - Build unminified development version to `./dist/bt-owon-bt.js` |
| 13 | +- `npm run dist` - Build minified production version to `./dist/bt-owon-bt.min.js` |
| 14 | + |
| 15 | +### Testing |
| 16 | +- `npm test` - Run Jest tests |
| 17 | + |
| 18 | +### Package Management |
| 19 | +- `npm ci` - Install dependencies (preferred for CI/clean installs) |
| 20 | + |
| 21 | +## Core Architecture |
| 22 | + |
| 23 | +### Main Entry Point |
| 24 | +- `owon.js` - Main API module that exports Start(), Stop(), SetLogLevel() functions and exposes btState object |
| 25 | + |
| 26 | +### Core Modules |
| 27 | +- `webbluetooth.js` - Contains the main Bluetooth state machine and protocol implementation |
| 28 | + - Implements Bluetooth Low Energy communication using Web Bluetooth API |
| 29 | + - Handles device pairing, service discovery, and notification subscriptions |
| 30 | + - Contains protocol parser for OWON B35/B41T+ data format |
| 31 | + - State machine with states: NOT_CONNECTED, CONNECTING, DEVICE_PAIRED, SUBSCRIBING, IDLE, BUSY, ERROR, STOPPING, STOPPED, METER_INIT, METER_INITIALIZING |
| 32 | + |
| 33 | +- `utils.js` - Utility functions for async operations and data conversion |
| 34 | + - sleep(), waitFor(), waitForTimeout() - async helpers |
| 35 | + - buf2hex(), hex2buf() - ArrayBuffer conversion utilities |
| 36 | + |
| 37 | +### Protocol Implementation |
| 38 | +The project implements the OWON B35 protocol (compatible with B41T+): |
| 39 | +- Bluetooth service UUID: `0000fff0-0000-1000-8000-00805f9b34fb` |
| 40 | +- Notifications UUID: `0000fff4-0000-1000-8000-00805f9b34fb` |
| 41 | +- Each notification contains 3 int16 values: measurement type/decimals/units, measure type flags, and display digits with sign bit |
| 42 | + |
| 43 | +### Frontend Integration |
| 44 | +- `multimeter.html` - Demo web interface using Bootstrap and Chart.js |
| 45 | +- Built files in `dist/` are standalone and can be included via script tags |
| 46 | +- Library exports `OwonBT` global when used in browser |
| 47 | + |
| 48 | +### Build System |
| 49 | +- Uses Browserify to create standalone browser bundles |
| 50 | +- UglifyJS for minification with source maps |
| 51 | +- Jest for unit testing with jsdom environment |
| 52 | + |
| 53 | +## Key Implementation Details |
| 54 | + |
| 55 | +### State Management |
| 56 | +The core state is managed in `webbluetooth.js` through the `btState` object which contains: |
| 57 | +- Connection state and state machine status |
| 58 | +- Bluetooth device/service/characteristic references |
| 59 | +- Raw and parsed measurement data |
| 60 | +- Statistics and debugging information |
| 61 | + |
| 62 | +### Error Handling |
| 63 | +- Auto-reconnection logic on GATT disconnections |
| 64 | +- Timeout handling for various operations (30s default, 1s in simulation) |
| 65 | +- Error states trigger cleanup and potential reconnection attempts |
| 66 | + |
| 67 | +### Data Flow |
| 68 | +1. User calls `OwonBT.Start()` to initiate connection |
| 69 | +2. State machine handles Bluetooth pairing and service discovery |
| 70 | +3. Notifications from multimeter are parsed and stored in `btState.parsedResponse` |
| 71 | +4. Frontend can read live data from `btState` object |
| 72 | +5. `OwonBT.Stop()` cleanly disconnects and stops state machine |
| 73 | + |
| 74 | +## Testing Strategy |
| 75 | +- Unit tests focus on API existence and state object structure |
| 76 | +- Uses Jest with jsdom environment for browser API mocking |
| 77 | +- Tests are in `tests/OwonBT.test.js` |
0 commit comments