fnb58 0.1.0__tar.gz

fnb58-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Lint, test & build (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uvx ruff check .
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build
+        run: uv build

fnb58-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+# Publishes the package to PyPI when a GitHub Release is published.
+# Can also be triggered manually from the Actions tab.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment is referenced by the PyPI trusted-publisher config.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fnb58/
+    permissions:
+      # Required for Trusted Publishing (OIDC); no API token needed.
+      id-token: write
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fnb58-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Captured logs
+fnb58_*.csv

fnb58-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

fnb58-0.1.0/CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A single-command CLI (`fnb58`) that reads measurements from a **FNIRSI FNB58**
+USB power meter over **Bluetooth LE** and logs them to CSV. The entire
+implementation lives in `src/fnb58/cli.py`; everything else is packaging.
+
+## Commands
+
+```bash
+uv sync                 # install deps + the package (editable) into .venv
+uv run fnb58 --help     # run the CLI from the working tree
+uv build                # build wheel + sdist into dist/
+uv tool install .       # install `fnb58` as an isolated global tool (~/.local/bin)
+python -m py_compile src/fnb58/cli.py   # quick syntax check
+
+# Runtime modes (require a real meter with Bluetooth enabled in its menu):
+uv run fnb58            # discover + log all matching meters to one CSV
+uv run fnb58 --scan     # list nearby BLE devices and exit
+uv run fnb58 --discover # dump GATT table + raw packets (debugging new firmware)
+```
+
+There is **no automated test suite**. The BLE path cannot be exercised without
+hardware; verify protocol/parse changes by driving `Decoder`/`CsvSink` directly
+with synthetic bytes (see how segments are built: `aa | type | len | payload |
+checksum`), and run a real meter for end-to-end confirmation.
+
+## Architecture (the non-obvious parts)
+
+**The BLE protocol is completely different from the device's USB-HID protocol.**
+This is the central gotcha — do not reuse USB knowledge:
+
+- USB-HID (the widely-documented baryluk protocol) uses 64-byte fixed frames,
+  an `aa 81/82/83` handshake, and ÷100000 scaling. **None of that works over BLE.**
+- BLE uses **short 4-byte commands**: `aa 81 00 f4` (request info) then
+  `aa 82 00 a7` (start streaming); stop is `aa 84 00 01`. No keep-alive needed.
+- GATT: notify char `0000ffe4-…`, write char `0000ffe9-…` (constants at top of
+  `cli.py`).
+- Data is a **TLV stream**, not fixed frames: `0xAA | type | len | payload[len]
+  | checksum`. One BLE notification may contain several concatenated segments,
+  and segments may be split across notifications.
+- Segment types and scaling: `0x04` V/I/power (÷10000), `0x05` resistance/temp,
+  `0x06` D+/D−, `0x08` energy/capacity, `0x03` device info. Protocol source:
+  https://github.com/zhiyb/FNB58_mqtt_forwarder
+
+**`Decoder`** owns reassembly: it buffers incoming bytes, resyncs on `0xAA`,
+waits for a complete segment, dispatches by type, keeps the *latest* value of
+each quantity in `self.state`, and fires `on_reading` only when a `0x04`
+measurement arrives (merging in the most recent D+/D−, temp, etc.).
+
+**Multi-device design:** `find_devices()` returns *all* name-matching meters;
+`run()` opens one shared `CsvSink` and `asyncio.gather`s one `log_device` task
+per meter. All workers write to the same CSV, distinguished by the `device`
+column (the meter's advertised name). The shared writer needs **no lock**
+because bleak dispatches all notification callbacks on the single asyncio
+event-loop thread. Per-worker `try/except` + `return_exceptions=True` isolate a
+failing meter so it can't abort the others.
+
+## Conventions
+
+- Measurement/log output goes to **stdout**; all status, errors, and device
+  info go to **stderr** (so CSV piping stays clean).
+- The console-script entry point is `fnb58 = "fnb58.cli:main"` (`pyproject.toml`).
+  Build backend is hatchling with a `src/` layout.

fnb58-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: fnb58
+Version: 0.1.0
+Summary: Read voltage, current, power and more from a FNIRSI FNB58 USB power meter over Bluetooth (BLE).
+Project-URL: Homepage, https://github.com/baryluk/fnirsi-usb-power-data-logger
+License: MIT
+Keywords: ble,bleak,bluetooth,fnb58,fnirsi,power-meter,usb
+Requires-Python: >=3.10
+Requires-Dist: bleak>=0.21
+Description-Content-Type: text/markdown
+
+# fnb58
+
+Command-line tool to read **voltage, current, power, D+/D−, temperature,
+resistance, energy and capacity** from a [FNIRSI FNB58](https://www.fnirsi.com/)
+USB power meter over **Bluetooth (BLE)**, with live console output and CSV logging.
+
+Works on macOS, Linux and Windows (via [bleak](https://github.com/hbldh/bleak)).
+
+## Install
+
+With [`uv`](https://docs.astral.sh/uv/) (recommended — isolated, on your PATH):
+
+```bash
+uv tool install fnb58            # from PyPI
+uv tool install .                # from a local checkout
+```
+
+Or with `pipx`:
+
+```bash
+pipx install fnb58
+```
+
+Or plain `pip`:
+
+```bash
+pip install fnb58
+```
+
+## Usage
+
+Enable Bluetooth in the FNB58's on-screen menu, then:
+
+```bash
+fnb58                       # auto-discover, stream to console + timestamped CSV
+fnb58 --scan                # list nearby BLE devices and exit
+fnb58 -o run1.csv           # choose the CSV filename
+fnb58 -o run1.csv --quiet   # log to CSV only, no console output
+fnb58 --no-file             # console only, no CSV
+fnb58 --address <UUID>      # connect to a specific device
+fnb58 --discover            # dump GATT table + raw packets (debugging)
+```
+
+Console output:
+
+```
+2026-06-13T12:25:31.004+00:00    5.0123 V    0.4988 A    2.4998 W   D+=2.70 D-=2.70   28.3C  0.0021 Wh
+```
+
+CSV columns (one row per measurement frame, flushed immediately, UTC timestamps):
+
+```
+epoch,utc_time,device,voltage_V,current_A,power_W,dplus_V,dminus_V,temp_C,resistance_ohm,energy_Wh,capacity_Ah
+```
+
+### Multiple meters
+
+If several FNB58s are in range, **all** matching meters are logged at once into
+**one** CSV file. The `device` column (the meter's advertised name, e.g.
+`FNB58-051772`) tells you which row came from which meter, and console lines are
+prefixed with `[<device>]`:
+
+```
+[FNB58-051772] 2026-06-13T12:25:31.004+00:00    5.0123 V  ...
+[FNB58-0517A0] 2026-06-13T12:25:31.020+00:00    9.0001 V  ...
+```
+
+```
+epoch,utc_time,device,voltage_V,...
+1781742331.004,2026-06-13T12:25:31.004+00:00,FNB58-051772,5.01230,...
+1781742331.020,2026-06-13T12:25:31.020+00:00,FNB58-0517A0,9.00010,...
+```
+
+Use `--name` or `--address` to narrow down to a specific meter. A meter that
+drops out is logged to stderr but does not stop the others.
+
+## Notes
+
+- On macOS, grant your terminal Bluetooth permission in
+  *System Settings → Privacy & Security → Bluetooth*, and note that BLE
+  addresses are reported as UUIDs (use `--scan` to find yours).
+- The BLE protocol differs from the device's USB-HID protocol; this tool speaks
+  BLE only. Protocol credit:
+  [zhiyb/FNB58_mqtt_forwarder](https://github.com/zhiyb/FNB58_mqtt_forwarder)
+  and [baryluk/fnirsi-usb-power-data-logger](https://github.com/baryluk/fnirsi-usb-power-data-logger).

fnb58-0.1.0/README.md

@@ -0,0 +1,85 @@
+# fnb58
+
+Command-line tool to read **voltage, current, power, D+/D−, temperature,
+resistance, energy and capacity** from a [FNIRSI FNB58](https://www.fnirsi.com/)
+USB power meter over **Bluetooth (BLE)**, with live console output and CSV logging.
+
+Works on macOS, Linux and Windows (via [bleak](https://github.com/hbldh/bleak)).
+
+## Install
+
+With [`uv`](https://docs.astral.sh/uv/) (recommended — isolated, on your PATH):
+
+```bash
+uv tool install fnb58            # from PyPI
+uv tool install .                # from a local checkout
+```
+
+Or with `pipx`:
+
+```bash
+pipx install fnb58
+```
+
+Or plain `pip`:
+
+```bash
+pip install fnb58
+```
+
+## Usage
+
+Enable Bluetooth in the FNB58's on-screen menu, then:
+
+```bash
+fnb58                       # auto-discover, stream to console + timestamped CSV
+fnb58 --scan                # list nearby BLE devices and exit
+fnb58 -o run1.csv           # choose the CSV filename
+fnb58 -o run1.csv --quiet   # log to CSV only, no console output
+fnb58 --no-file             # console only, no CSV
+fnb58 --address <UUID>      # connect to a specific device
+fnb58 --discover            # dump GATT table + raw packets (debugging)
+```
+
+Console output:
+
+```
+2026-06-13T12:25:31.004+00:00    5.0123 V    0.4988 A    2.4998 W   D+=2.70 D-=2.70   28.3C  0.0021 Wh
+```
+
+CSV columns (one row per measurement frame, flushed immediately, UTC timestamps):
+
+```
+epoch,utc_time,device,voltage_V,current_A,power_W,dplus_V,dminus_V,temp_C,resistance_ohm,energy_Wh,capacity_Ah
+```
+
+### Multiple meters
+
+If several FNB58s are in range, **all** matching meters are logged at once into
+**one** CSV file. The `device` column (the meter's advertised name, e.g.
+`FNB58-051772`) tells you which row came from which meter, and console lines are
+prefixed with `[<device>]`:
+
+```
+[FNB58-051772] 2026-06-13T12:25:31.004+00:00    5.0123 V  ...
+[FNB58-0517A0] 2026-06-13T12:25:31.020+00:00    9.0001 V  ...
+```
+
+```
+epoch,utc_time,device,voltage_V,...
+1781742331.004,2026-06-13T12:25:31.004+00:00,FNB58-051772,5.01230,...
+1781742331.020,2026-06-13T12:25:31.020+00:00,FNB58-0517A0,9.00010,...
+```
+
+Use `--name` or `--address` to narrow down to a specific meter. A meter that
+drops out is logged to stderr but does not stop the others.
+
+## Notes
+
+- On macOS, grant your terminal Bluetooth permission in
+  *System Settings → Privacy & Security → Bluetooth*, and note that BLE
+  addresses are reported as UUIDs (use `--scan` to find yours).
+- The BLE protocol differs from the device's USB-HID protocol; this tool speaks
+  BLE only. Protocol credit:
+  [zhiyb/FNB58_mqtt_forwarder](https://github.com/zhiyb/FNB58_mqtt_forwarder)
+  and [baryluk/fnirsi-usb-power-data-logger](https://github.com/baryluk/fnirsi-usb-power-data-logger).

fnb58-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "fnb58"
+version = "0.1.0"
+description = "Read voltage, current, power and more from a FNIRSI FNB58 USB power meter over Bluetooth (BLE)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["fnb58", "fnirsi", "usb", "power-meter", "bluetooth", "ble", "bleak"]
+dependencies = [
+    "bleak>=0.21",
+]
+
+[project.scripts]
+fnb58 = "fnb58.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/baryluk/fnirsi-usb-power-data-logger"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fnb58"]

fnb58-0.1.0/src/fnb58/__init__.py

@@ -0,0 +1,3 @@
+"""Read voltage/current/power and more from a FNIRSI FNB58 USB power meter over BLE."""
+
+__version__ = "0.1.0"