Skip to content

docs(radar): add AN-029 sports app note and a vendor doc index - #257

Merged
jewbetcha merged 3 commits into
open-flight:mainfrom
HuggeK:docs/ops243-sports-an029
Aug 30, 2026
Merged

docs(radar): add AN-029 sports app note and a vendor doc index#257
jewbetcha merged 3 commits into
open-flight:mainfrom
HuggeK:docs/ops243-sports-an029

Conversation

@HuggeK

@HuggeK HuggeK commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Adds OmniPreSense AN-029 "OPS24x for Sports Applications" rev A (21 Jun 2026) to docs/radar/, and adds a docs/radar/README.md index for the vendored radar PDFs.

AN-029 supersedes the July 2025 Sports_Ball_Detect slide deck we already had vendored — that one was an internal presentation stamped Confidential on every page; AN-029 is a formal public application note with a revision history and roughly 3x the content.

What AN-029 adds that we care about:

  • OPS243 field of view: 20° horizontal x 24° vertical, with a coverage-vs-distance table. The old deck gave no FOV numbers at all. At the recommended 2-3 m standoff that is a 0.7-1.1 m capture window, which bounds how far off the tee line a ball can sit.
  • An explicit golf settings table (Table 6) matching the documented golf configuration in ops243.py.
  • Rolling Buffer called out as an OPS243-A-only feature, pointing at AN-27.
  • Tennis added to the ball reflectivity table.

The 2025 deck is kept, not replaced. Three things live only there: the A! persistent-memory save that test_rolling_buffer_persist.py --setup depends on, the 10° up-angle recommendation for golf, and the R+ inbound-only filter.

docs/radar/README.md records that split, the source URL and revision of every vendored PDF, two errors in AN-029 rev A (it prints S>32 for the FFT command where its own Table 6 says X=32; and its report rate of ~200 Hz contradicts the older deck's 56 Hz for identical settings), and how Table 6 compares to what we actually send.

AN-029 page 8 cites this project by name as reference code for an OPS243-A launch monitor.

Why was this required?

The vendored sports note was the only OPS243 document we had covering ball detection and sensor placement, and it was a year out of date. Two concrete gaps it left:

  1. No field-of-view numbers anywhere in the repo. Mounting and aiming guidance for the OPS243 has been folklore — the 20°/24° cone and the coverage table are what actually bound tee placement tolerance, and until now they existed in no document we shipped.
  2. A stale report-rate figure baked into the code. ops243.py docstrings (lines 25 and 959) quote 56 Hz for 30 ksps / 128 / 4096. AN-029 gives ~200 Hz for identical settings. Nothing depends on this in rolling-buffer mode, but the contradiction was invisible until both documents sat side by side, and now it is written down.

There was also no index of docs/radar/. Five vendor PDFs sat there with no record of which revision each was, where it came from, or which superseded which — so "is our copy current?" required re-searching the vendor site each time, which is exactly what prompted this PR.

Automated tests

None. This PR adds a vendor PDF and a Markdown index; it changes no code, no configuration, and no behaviour. There is no executable surface to test.

The claims the README makes about the code were verified by reading it rather than by new tests — see manual testing below. If a reviewer would rather those claims be pinned by a test, the honest way to do it is a test asserting configure_for_rolling_buffer sends no R> command, which would be new coverage of existing behaviour and belongs in its own PR.

Manual (human) testing

Verified by hand, no hardware involved:

  • Provenance. Downloaded the PDF from the vendor URL now recorded in the README, confirmed it opens, is 11 pages, and its revision history page reads "A / June 21, 2026 / Initial release".
  • Content diff. Extracted the text of both the new AN-029 and the 2025 deck and read them side by side, page by page, to establish what is genuinely new versus reformatted. That is where the FOV table, the Tennis row, and the three deck-only items came from.
  • Code cross-check. Grepped src/openflight/ops243.py for every API command in AN-029 Table 6 and read the three configuration methods. This caught an error in my own first draft: I had written that AN-029 "adds an R>10 filter that OpenFlight does not set", which is only true of configure_for_rolling_buffer. configure_for_speed_trigger sets R>20 and R-, and configure_for_swing_speed_training defaults to R>20. Corrected in df4ab8e, which is the second commit here.
  • Errata. Confirmed AN-029 page 7's S>32 contradicts its own Table 6's X=32, and recomputed the report rate (128 / 30000 = 4.27 ms, so ~234 Hz theoretical) to judge which of the two conflicting vendor figures is the frame rate and which includes overhead.
  • Links. Checked every relative link in the new README resolves against the files actually in docs/radar/, including AN-027-A_Rolling Buffer.pdf, whose filename contains a space and therefore needs angle-bracket link syntax.

Not verified: nothing in this PR reaches the radar, so no mock-mode or hardware run applies.

Checklist

  • Single feature/fix — one thing: refresh the vendored OPS243 sports documentation and index docs/radar/
  • Automated tests included — n/a, justified above (docs-only, no executable surface)
  • Manual testing described — above
  • Python tests pass (uv run pytest tests/ -v) — unaffected; no code changed
  • Pylint passes (uv run pylint src/openflight/ --fail-under=9) — unaffected; no code changed
  • Ruff passes (uv run ruff check src/openflight/) — unaffected; no code changed
  • UI builds (cd ui && npm run build) — unaffected; no UI changed
  • UI lint passes (cd ui && npm run lint) — unaffected; no UI changed
  • Updated docs or CHANGELOG if needed — this PR is the docs update
  • No unrelated changes mixed in

OmniPreSense published AN-029 "OPS24x for Sports Applications" rev A in
June 2026. It supersedes the July 2025 Sports_Ball_Detect slide deck we
had vendored, which was an internal deck marked Confidential on every
page.

What AN-029 adds that we care about:

- OPS243 field of view, 20 deg horizontal by 24 deg vertical, with a
  coverage-vs-distance table. The old deck gave no FOV numbers at all.
  At the recommended 2-3 m standoff that is a 0.7-1.1 m capture window,
  which bounds how far off the tee line a ball can sit.
- An explicit golf settings table that matches the configuration in
  ops243.py, plus an R>10 speed filter we do not set.
- Rolling Buffer called out as an OPS243-A only feature.
- Tennis added to the ball reflectivity table.

The 2025 deck is kept, not replaced. Three things live only there: the
A! persistent-memory save that test_rolling_buffer_persist.py --setup
depends on, the 10 degree up-angle recommendation for golf, and the R+
inbound-only filter. docs/radar/README.md now records that split, the
source URL and revision of each vendored PDF, and two errors in AN-029
rev A (it prints S>32 for the FFT command where its own table says X=32,
and its report rate contradicts the older deck).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014udmxe5eNQxrsBRkPG7RZz
@HuggeK
HuggeK requested a review from jewbetcha as a code owner August 29, 2026 23:03
HuggeK and others added 2 commits August 30, 2026 01:05
The first draft said AN-029 "adds a R>10 speed filter that OpenFlight
does not set". That is only true of the production rolling-buffer path.
configure_for_speed_trigger sets R>20 and R-, and
configure_for_swing_speed_training defaults to R>20, both stricter than
AN-029's recommendation. configure_for_speed_trigger also uses a 256
point FFT rather than Table 6's 4096, trading resolution for report rate.

Spell all three out under a dedicated heading, and note that the
ops243.py docstrings still quote the older 56 Hz report rate that AN-029
contradicts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014udmxe5eNQxrsBRkPG7RZz
@jewbetcha
jewbetcha merged commit 8668dfc into open-flight:main Aug 30, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants