antplus-recorder 0.1.0__tar.gz

antplus_recorder-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Recordings and the device list, written to the directory the app runs in
+*.csv
+*.fit
+devices.toml
+
+# Build and tool caches
+.pytest_cache/
+.ruff_cache/
+.DS_Store

antplus_recorder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Mahner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

antplus_recorder-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: antplus-recorder
+Version: 0.1.0
+Summary: Record and display every ANT+ sensor in range: power meters, smart trainers and heart rate straps
+Project-URL: Homepage, https://github.com/bartTC/antplus-recorder
+Project-URL: Issues, https://github.com/bartTC/antplus-recorder/issues
+Author-email: Martin Mahner <martin@mahner.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ant+,antplus,cycling,fit,power meter,smart trainer,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: garmin-fit-sdk>=21.218.0
+Requires-Dist: libusb-package>=1.0.30.0
+Requires-Dist: openant>=1.3.4
+Requires-Dist: textual>=8.2.8
+Requires-Dist: tomlkit>=0.15.1
+Description-Content-Type: text/markdown
+
+# antplus-recorder
+
+Shows and records every ANT+ sensor in range: power meters, smart trainers and heart rate straps, side by side in the terminal. Built to compare power meters against each other, for example a smart trainer against crank or pedal power meters. One power meter is the reference, and every other one shows how far it is off, in watts and percent. Every ride is written to a CSV file and to one FIT file per power meter.
+
+There is no pairing. The ANT+ USB stick listens to the whole ANT+ frequency, and every sensor that sends shows up on its own.
+
+![antplus-recorder with a Wahoo Kickr as reference, a Stages crank 0.9% below it, the Kickr's trainer channel and a heart rate strap](https://raw.githubusercontent.com/bartTC/antplus-recorder/main/docs/images/dashboard.png)
+
+*The Kickr in ERG mode at 100 W is the reference. Its power and trainer channels agree, the Stages crank reads 1.1% lower over the lap.*
+
+## Install
+
+Python ≥ 3.11 and an ANT+ USB stick (ANT USB2 or ANT USB-m, the usual Garmin/Dynastream ones).
+
+```sh
+uvx antplus-recorder            # run without installing
+uv tool install antplus-recorder
+pipx install antplus-recorder
+```
+
+libusb comes along with the `libusb-package` dependency, so a Mac needs nothing from Homebrew. If libusb is installed on the system, that one is used.
+
+- **macOS:** Plug the stick in and allow the accessory to connect when macOS asks.
+- **Linux:** The stick needs read/write access for your user. Untested, but this udev rule in `/etc/udev/rules.d/42-ant-usb-sticks.rules` should do it, followed by `sudo udevadm control --reload-rules` and replugging the stick:
+
+  ```
+  SUBSYSTEM=="usb", ATTRS{idVendor}=="0fcf", ATTRS{idProduct}=="1008", MODE="0666"
+  SUBSYSTEM=="usb", ATTRS{idVendor}=="0fcf", ATTRS{idProduct}=="1009", MODE="0666"
+  ```
+
+## Usage
+
+```sh
+antplus-recorder                       # show and record everything in range
+antplus-recorder --no-record           # only show
+antplus-recorder -o ~/Rides            # record somewhere else
+antplus-recorder -d 57587 -d 19696     # only these device numbers
+antplus-recorder --fit-from 2026-10-09_18-57-53.csv
+```
+
+Recording starts right away, so it can't be forgotten. Files go to the folder you start the command in, named after the start time, and are never overwritten.
+
+| Option | Default | Effect |
+|---|---|---|
+| `-o`, `--output-dir DIR` | current folder | Where recordings go. |
+| `--no-record` | off | Only show, write no files. |
+| `-d`, `--device NUMBER` | all | Only show and record this ANT+ device number. Repeat for more. Useful when other people's sensors are in range. |
+| `--devices FILE` | `devices.toml` | The device list, see [Naming devices](#naming-devices). |
+| `--fit-from CSV` | | Build the FIT files for a recorded CSV, e.g. after a crash, then exit. |
+
+### Keys
+
+| Key | Effect |
+|---|---|
+| `1`–`5` or the buttons | Big power numbers, L/R balance and the difference show Live, 3 s, 10 s, 30 s or 60 s averages. |
+| click a power tile | Make it the reference for comparing, click again to clear. |
+| `c` | Start a new lap for the comparison. |
+| `q` | Quit. Writes the FIT files. |
+
+### What a tile shows
+
+- Power and cadence. Power is the average over the selected window, cadence is live.
+- 3 s, 10 s and 30 s averages, always.
+- The difference to the reference meter, see below.
+- L/R balance for dual-sided meters, power-weighted over the selected window, battery and how often a new power value arrives (Hz).
+- Smart trainers (FE-C): state (ready, in use, paused), resistance level, incline if sent, and warnings such as `spindown needed` or `ERG: speed too low`.
+- A trend line of the last two minutes, starting at 0 W.
+
+Heart rate straps get a tile with bpm. Every other ANT+ device in range (watches, footpods, radars …) is listed in a table below.
+
+## Comparing power meters
+
+Click the power meter you trust, for example the pedals or the crank. It gets an orange border and `REFERENCE`. Every other power tile then shows:
+
+```
+Δ vs Stages Cycling
+30s  -7 W  -6.5%
+lap  -6.8%  (4:12)
+```
+
+- The middle line compares the averages over the selected window. In Live mode it uses 30 s, because two meters never measure at the same instant and single readings make the difference jump.
+- **lap** compares the work of both meters since the last `c`. Seconds in which the reference is below 20 W (coasting) or one of the meters sends nothing don't count, and the time in brackets is only the counted seconds. Because it sums energy, a minute at 300 W weighs three times as much as a minute at 100 W. Press `c` at the start of every power level.
+- Changing the reference starts a new lap. The reference is saved in `devices.toml`.
+
+Use the lap, not the 30 s value, for corrections: over a few seconds, the reference's own noise shows up as a difference.
+
+**Example:** With the crank as reference, a smart trainer shows `-6.5%`, so it reads 6.5% low. To really ride 200 W in ERG mode, set it to 200 × (1 − 0.065) ≈ 187 W.
+
+For a clean number, warm up for 10 minutes, then do the trainer's spindown and the zero offset of the other meters, and ride a few minutes at each of several levels (100, 200, 300 W). That also shows whether the difference is a constant percentage or a fixed number of watts: 7 W are 7% at 100 W but only 2–3% at 300 W.
+
+## Files
+
+### CSV
+
+`2026-10-09_18-57-53.csv`, one row per sensor and second, appended and flushed every second, so a crash loses at most the last second.
+
+| Column | Content |
+|---|---|
+| `time` | Local time with UTC offset, ISO 8601. |
+| `kind` | `power`, `trainer` or `heart_rate`. |
+| `number` | ANT+ device number. |
+| `name` | Name from `devices.toml`, else the manufacturer. |
+| `value` | Watts or bpm, the mean of that second. |
+| `unit` | `W` or `bpm`. |
+| `cadence` | rpm. |
+| `right_balance` | Right leg's share in %, dual-sided meters only. |
+| `speed` | km/h, smart trainers only. |
+
+A device that joins mid-ride (pedals woken up later) simply starts appearing in the rows. With pandas: `df.pivot_table(index="time", columns=["kind", "number"], values="value")`.
+
+### FIT
+
+When you quit, there is one FIT file per power source, e.g. `2026-10-09_18-57-53_power-57587_stages-cycling.fit`, with power, cadence, L/R balance and the heart rate of the first strap, plus speed and distance for a smart trainer. Each file is a complete cycling activity (indoor cycling) with lap and session summary, so it can be uploaded anywhere and compared with tools like the [DC Rainmaker Analyzer](https://analyzer.dcrainmaker.com), which expect one file per power meter. A FIT file is only valid when complete, so it is built from the CSV at the end. After a crash, `--fit-from` builds it.
+
+### Naming devices
+
+`devices.toml` in the current folder lists every device ever seen, filled in automatically:
+
+```toml
+[power.57587]
+name = ""
+manufacturer = "Stages Cycling"
+model = 3
+serial = 40618248
+reference = true
+```
+
+Set `name` and the tile shows it right away, no restart needed. Names also go into the CSV and the FIT file names. A Kickr shows up twice, as `power` and as `trainer`: smart trainers send both profiles, so plain power meter displays can read them too.
+
+## How it works
+
+- **Scan mode:** The stick runs in ANT continuous scan mode. It listens 100% of the time on 2457 MHz and receives every sensor, with no pairing and no limit of 8 channels. The same sensor can still be paired with a bike computer or Zwift at the same time, because ANT+ sensors broadcast. The flip side: scan mode only receives, so the app can't control a trainer. Use the trainer's own app for ERG.
+- **Power between pages:** Torque-based meters send the page with the power value only every few messages. The app computes the average from the accumulated power and the event counter, so the power of every pedal stroke counts, not just the latest one.
+- **Coasting:** A meter keeps repeating its last value while the cranks stand still. If the event counter hasn't moved for 3 s, the app shows 0 W, like head units do.
+- **Recording:** If a second gets no new power value, the last one is held while the sensor is still sending, again like head units with 1 s recording.
+
+## Troubleshooting
+
+- **No ANT+ USB stick found:** Check that the system sees it (macOS: allow the accessory; Linux: udev rule above).
+- **Stick is used by another app:** Only one program can use the stick. Close Zwift, Garmin Express or another `antplus-recorder`.
+- **Stick didn't answer, resetting it:** After a crash or kill the stick can hang once. The app resets it on its own, which takes about 3 s.
+- **No sensors found:** Sensors sleep until they move. Pedal a few turns, put on the heart rate strap.
+- **Two scrollbars at the right edge in iTerm2:** iTerm2 extends the last column into the window margin. Settings → Advanced → "Extend background color into margins in alternate screen mode?" → No ([textual#6230](https://github.com/Textualize/textual/issues/6230)).
+
+## Limitations
+
+- Receives only, no trainer control (see scan mode above).
+- Tested on macOS with an ANT USB2 stick, a Wahoo Kickr, a Stages crank and a Garmin heart rate strap. Linux is untested.
+- A Kickr sends the power page on its trainer channel only rarely, sometimes more than 10 s apart, so its `trainer` tile reacts slowly. Its `power` tile updates about once per second and is the better one to compare.
+- Many sensors on one frequency collide more often. Untested beyond a handful of real sensors; the display itself was tested with 40 simulated ones.
+
+## Development
+
+```sh
+just run                  # run the dashboard from the repo
+just test                 # pytest
+just lint                 # ruff with all rules (config in pyproject.toml)
+just build                # sdist and wheel into dist/
+```
+
+Releases go out through GitHub Actions: `git tag v0.2.0 && git push --tags` runs ruff and the tests and publishes to PyPI with Trusted Publishing. The tag has to match the version in `pyproject.toml`.
+
+## License
+
+MIT

antplus_recorder-0.1.0/README.md

@@ -0,0 +1,165 @@
+# antplus-recorder
+
+Shows and records every ANT+ sensor in range: power meters, smart trainers and heart rate straps, side by side in the terminal. Built to compare power meters against each other, for example a smart trainer against crank or pedal power meters. One power meter is the reference, and every other one shows how far it is off, in watts and percent. Every ride is written to a CSV file and to one FIT file per power meter.
+
+There is no pairing. The ANT+ USB stick listens to the whole ANT+ frequency, and every sensor that sends shows up on its own.
+
+![antplus-recorder with a Wahoo Kickr as reference, a Stages crank 0.9% below it, the Kickr's trainer channel and a heart rate strap](https://raw.githubusercontent.com/bartTC/antplus-recorder/main/docs/images/dashboard.png)
+
+*The Kickr in ERG mode at 100 W is the reference. Its power and trainer channels agree, the Stages crank reads 1.1% lower over the lap.*
+
+## Install
+
+Python ≥ 3.11 and an ANT+ USB stick (ANT USB2 or ANT USB-m, the usual Garmin/Dynastream ones).
+
+```sh
+uvx antplus-recorder            # run without installing
+uv tool install antplus-recorder
+pipx install antplus-recorder
+```
+
+libusb comes along with the `libusb-package` dependency, so a Mac needs nothing from Homebrew. If libusb is installed on the system, that one is used.
+
+- **macOS:** Plug the stick in and allow the accessory to connect when macOS asks.
+- **Linux:** The stick needs read/write access for your user. Untested, but this udev rule in `/etc/udev/rules.d/42-ant-usb-sticks.rules` should do it, followed by `sudo udevadm control --reload-rules` and replugging the stick:
+
+  ```
+  SUBSYSTEM=="usb", ATTRS{idVendor}=="0fcf", ATTRS{idProduct}=="1008", MODE="0666"
+  SUBSYSTEM=="usb", ATTRS{idVendor}=="0fcf", ATTRS{idProduct}=="1009", MODE="0666"
+  ```
+
+## Usage
+
+```sh
+antplus-recorder                       # show and record everything in range
+antplus-recorder --no-record           # only show
+antplus-recorder -o ~/Rides            # record somewhere else
+antplus-recorder -d 57587 -d 19696     # only these device numbers
+antplus-recorder --fit-from 2026-10-09_18-57-53.csv
+```
+
+Recording starts right away, so it can't be forgotten. Files go to the folder you start the command in, named after the start time, and are never overwritten.
+
+| Option | Default | Effect |
+|---|---|---|
+| `-o`, `--output-dir DIR` | current folder | Where recordings go. |
+| `--no-record` | off | Only show, write no files. |
+| `-d`, `--device NUMBER` | all | Only show and record this ANT+ device number. Repeat for more. Useful when other people's sensors are in range. |
+| `--devices FILE` | `devices.toml` | The device list, see [Naming devices](#naming-devices). |
+| `--fit-from CSV` | | Build the FIT files for a recorded CSV, e.g. after a crash, then exit. |
+
+### Keys
+
+| Key | Effect |
+|---|---|
+| `1`–`5` or the buttons | Big power numbers, L/R balance and the difference show Live, 3 s, 10 s, 30 s or 60 s averages. |
+| click a power tile | Make it the reference for comparing, click again to clear. |
+| `c` | Start a new lap for the comparison. |
+| `q` | Quit. Writes the FIT files. |
+
+### What a tile shows
+
+- Power and cadence. Power is the average over the selected window, cadence is live.
+- 3 s, 10 s and 30 s averages, always.
+- The difference to the reference meter, see below.
+- L/R balance for dual-sided meters, power-weighted over the selected window, battery and how often a new power value arrives (Hz).
+- Smart trainers (FE-C): state (ready, in use, paused), resistance level, incline if sent, and warnings such as `spindown needed` or `ERG: speed too low`.
+- A trend line of the last two minutes, starting at 0 W.
+
+Heart rate straps get a tile with bpm. Every other ANT+ device in range (watches, footpods, radars …) is listed in a table below.
+
+## Comparing power meters
+
+Click the power meter you trust, for example the pedals or the crank. It gets an orange border and `REFERENCE`. Every other power tile then shows:
+
+```
+Δ vs Stages Cycling
+30s  -7 W  -6.5%
+lap  -6.8%  (4:12)
+```
+
+- The middle line compares the averages over the selected window. In Live mode it uses 30 s, because two meters never measure at the same instant and single readings make the difference jump.
+- **lap** compares the work of both meters since the last `c`. Seconds in which the reference is below 20 W (coasting) or one of the meters sends nothing don't count, and the time in brackets is only the counted seconds. Because it sums energy, a minute at 300 W weighs three times as much as a minute at 100 W. Press `c` at the start of every power level.
+- Changing the reference starts a new lap. The reference is saved in `devices.toml`.
+
+Use the lap, not the 30 s value, for corrections: over a few seconds, the reference's own noise shows up as a difference.
+
+**Example:** With the crank as reference, a smart trainer shows `-6.5%`, so it reads 6.5% low. To really ride 200 W in ERG mode, set it to 200 × (1 − 0.065) ≈ 187 W.
+
+For a clean number, warm up for 10 minutes, then do the trainer's spindown and the zero offset of the other meters, and ride a few minutes at each of several levels (100, 200, 300 W). That also shows whether the difference is a constant percentage or a fixed number of watts: 7 W are 7% at 100 W but only 2–3% at 300 W.
+
+## Files
+
+### CSV
+
+`2026-10-09_18-57-53.csv`, one row per sensor and second, appended and flushed every second, so a crash loses at most the last second.
+
+| Column | Content |
+|---|---|
+| `time` | Local time with UTC offset, ISO 8601. |
+| `kind` | `power`, `trainer` or `heart_rate`. |
+| `number` | ANT+ device number. |
+| `name` | Name from `devices.toml`, else the manufacturer. |
+| `value` | Watts or bpm, the mean of that second. |
+| `unit` | `W` or `bpm`. |
+| `cadence` | rpm. |
+| `right_balance` | Right leg's share in %, dual-sided meters only. |
+| `speed` | km/h, smart trainers only. |
+
+A device that joins mid-ride (pedals woken up later) simply starts appearing in the rows. With pandas: `df.pivot_table(index="time", columns=["kind", "number"], values="value")`.
+
+### FIT
+
+When you quit, there is one FIT file per power source, e.g. `2026-10-09_18-57-53_power-57587_stages-cycling.fit`, with power, cadence, L/R balance and the heart rate of the first strap, plus speed and distance for a smart trainer. Each file is a complete cycling activity (indoor cycling) with lap and session summary, so it can be uploaded anywhere and compared with tools like the [DC Rainmaker Analyzer](https://analyzer.dcrainmaker.com), which expect one file per power meter. A FIT file is only valid when complete, so it is built from the CSV at the end. After a crash, `--fit-from` builds it.
+
+### Naming devices
+
+`devices.toml` in the current folder lists every device ever seen, filled in automatically:
+
+```toml
+[power.57587]
+name = ""
+manufacturer = "Stages Cycling"
+model = 3
+serial = 40618248
+reference = true
+```
+
+Set `name` and the tile shows it right away, no restart needed. Names also go into the CSV and the FIT file names. A Kickr shows up twice, as `power` and as `trainer`: smart trainers send both profiles, so plain power meter displays can read them too.
+
+## How it works
+
+- **Scan mode:** The stick runs in ANT continuous scan mode. It listens 100% of the time on 2457 MHz and receives every sensor, with no pairing and no limit of 8 channels. The same sensor can still be paired with a bike computer or Zwift at the same time, because ANT+ sensors broadcast. The flip side: scan mode only receives, so the app can't control a trainer. Use the trainer's own app for ERG.
+- **Power between pages:** Torque-based meters send the page with the power value only every few messages. The app computes the average from the accumulated power and the event counter, so the power of every pedal stroke counts, not just the latest one.
+- **Coasting:** A meter keeps repeating its last value while the cranks stand still. If the event counter hasn't moved for 3 s, the app shows 0 W, like head units do.
+- **Recording:** If a second gets no new power value, the last one is held while the sensor is still sending, again like head units with 1 s recording.
+
+## Troubleshooting
+
+- **No ANT+ USB stick found:** Check that the system sees it (macOS: allow the accessory; Linux: udev rule above).
+- **Stick is used by another app:** Only one program can use the stick. Close Zwift, Garmin Express or another `antplus-recorder`.
+- **Stick didn't answer, resetting it:** After a crash or kill the stick can hang once. The app resets it on its own, which takes about 3 s.
+- **No sensors found:** Sensors sleep until they move. Pedal a few turns, put on the heart rate strap.
+- **Two scrollbars at the right edge in iTerm2:** iTerm2 extends the last column into the window margin. Settings → Advanced → "Extend background color into margins in alternate screen mode?" → No ([textual#6230](https://github.com/Textualize/textual/issues/6230)).
+
+## Limitations
+
+- Receives only, no trainer control (see scan mode above).
+- Tested on macOS with an ANT USB2 stick, a Wahoo Kickr, a Stages crank and a Garmin heart rate strap. Linux is untested.
+- A Kickr sends the power page on its trainer channel only rarely, sometimes more than 10 s apart, so its `trainer` tile reacts slowly. Its `power` tile updates about once per second and is the better one to compare.
+- Many sensors on one frequency collide more often. Untested beyond a handful of real sensors; the display itself was tested with 40 simulated ones.
+
+## Development
+
+```sh
+just run                  # run the dashboard from the repo
+just test                 # pytest
+just lint                 # ruff with all rules (config in pyproject.toml)
+just build                # sdist and wheel into dist/
+```
+
+Releases go out through GitHub Actions: `git tag v0.2.0 && git push --tags` runs ruff and the tests and publishes to PyPI with Trusted Publishing. The tag has to match the version in `pyproject.toml`.
+
+## License
+
+MIT

antplus_recorder-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "antplus-recorder"
+version = "0.1.0"
+description = "Record and display every ANT+ sensor in range: power meters, smart trainers and heart rate straps"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Martin Mahner", email = "martin@mahner.org" }
+]
+keywords = ["ant+", "antplus", "power meter", "smart trainer", "cycling", "fit", "tui"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "garmin-fit-sdk>=21.218.0",
+    "libusb-package>=1.0.30.0",
+    "openant>=1.3.4",
+    "textual>=8.2.8",
+    "tomlkit>=0.15.1",
+]
+
+[project.scripts]
+antplus-recorder = "antplus_recorder:main"
+
+[project.urls]
+Homepage = "https://github.com/bartTC/antplus-recorder"
+Issues = "https://github.com/bartTC/antplus-recorder/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.16",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py311"  # keep in sync with requires-python
+lint.select = ["ALL"]
+lint.ignore = [
+    # Valid exclusions.
+    "COM812", # Conflicts with ruff format
+    "E501", # Line too long (>88)
+    "D203", # incorrect-blank-line-before-class (conflicts with D211)
+    "D212", # Don't require summary on first line
+    "ERA001", # Found commented-out code
+    "FBT", # Flake Boolean Trap (don't use arg=True in functions)
+    "D", # docstrings are written where they help, not on every function
+    "CPY001", # the license is in LICENSE, no header in every file
+    "RUF001", "RUF002", "RUF003", # typographic characters (Δ · ●) in the interface are intended
+    "PLR2004", # ANT+ page numbers and byte offsets are the protocol, not magic numbers
+    "PLR0913", "PLR0917", # a tile's comparison takes many inputs — not a smell here
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15  # page decoding and the dashboard refresh branch a lot
+
+[tool.ruff.lint.pylint]
+max-branches = 15
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/test_*.py" = [
+    "S101", # Use of `assert` detected
+    "D", # Tests don't need docstrings on every class/method
+    "ANN", # Fake objects and inline helpers don't need full type annotations
+    "SLF001", # Tests routinely reach into implementation internals
+]
+"tests/conftest.py" = ["D", "ANN"]
+"src/antplus_recorder/__init__.py" = [
+    "T201", # the command prints the files it wrote
+]
+"tests/__init__.py" = ["D104"]

antplus_recorder-0.1.0/src/antplus_recorder/__init__.py

@@ -0,0 +1,93 @@
+"""Record and display every ANT+ sensor in range."""
+
+import argparse
+import logging
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+from textual.logging import TextualHandler
+
+from .app import RecorderApp
+from .receiver import Receiver
+from .recording import Recorder, write_fit_files
+from .registry import Registry
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="antplus-recorder", description=__doc__)
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        type=Path,
+        default=Path(),
+        help="where recordings go, named by start time (default: current directory)",
+    )
+    parser.add_argument(
+        "--no-record", action="store_true", help="only display, don't write any files"
+    )
+    parser.add_argument(
+        "-d",
+        "--device",
+        type=int,
+        action="append",
+        metavar="NUMBER",
+        help="only show and record this ANT+ device number; repeat for more (default: all)",
+    )
+    parser.add_argument(
+        "--devices",
+        type=Path,
+        default=Path("devices.toml"),
+        help="file listing seen devices and their names (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--fit-from",
+        type=Path,
+        metavar="CSV",
+        help="build the FIT files for a recorded CSV, e.g. after a crash, then exit",
+    )
+    args = parser.parse_args()
+
+    if args.fit_from:
+        write_fits(args.fit_from)
+        return
+
+    # openant logs USB hiccups as warnings, which would garble the terminal UI
+    logging.basicConfig(level=logging.WARNING, handlers=[TextualHandler()])
+
+    receiver = Receiver(set(args.device) if args.device else None)
+    recorder = None
+    if not args.no_record:
+        args.output_dir.mkdir(parents=True, exist_ok=True)
+        path = args.output_dir / f"{datetime.now().astimezone():%Y-%m-%d_%H-%M-%S}.csv"
+        recorder = Recorder(path, time.monotonic())
+
+    app = RecorderApp(receiver, Registry(args.devices), recorder)
+    try:
+        app.run()
+    finally:
+        receiver.stop()
+        if recorder:
+            recorder.close()
+
+    if recorder:
+        if recorder.rows:
+            print(f"Recorded {recorder.path}")
+            write_fits(recorder.path)
+        else:
+            recorder.path.unlink()
+            if not app.error:
+                print("Nothing recorded, no files written.")
+    if app.error:
+        sys.exit(app.error)
+
+
+def write_fits(csv_path: Path) -> None:
+    written, skipped = write_fit_files(csv_path)
+    for path in written:
+        print(f"Wrote {path}")
+    for path in skipped:
+        print(f"Skipped {path}, it already exists")
+    if not written and not skipped:
+        print(f"No power data in {csv_path}, no FIT files written.")