Skip to content

docs: document sound cues and the Volume setting (WP2) - #576

Merged
brickbots merged 1 commit into
mainfrom
docs/rev4-sound-volume-wp2
Aug 7, 2026
Merged

docs: document sound cues and the Volume setting (WP2)#576
brickbots merged 1 commit into
mainfrom
docs/rev4-sound-volume-wp2

Conversation

@brickbots

Copy link
Copy Markdown
Owner

WP2 of the rev4 documentation pass (rev4-docs-update-plan.md §4).

Why

rev4 has a passive piezo buzzer, and Settings → User Pref → Volume (Off, 1–5) shipped
in v2.6.1 with zero documentation — it appears in neither user_guide.rst nor
menu_map.rst. A rev4 owner who heard a beep had nowhere to look, and no way to find the
off switch. This closes that gap.

What changed

docs/source/user_guide.rst — new Sounds sub-section at the end of Settings Menu:

  • what the tones mark: each key press, startup, shutdown, and every low-battery warning;
  • where Volume lives, its range, and that choosing a level plays a sample tone at that
    level so you can set it by ear;
  • the honest caveat — the buzzer is far louder at some pitches than others, so cues differ
    in loudness by design, not as a fault;
  • how to turn it off;
  • a .. note:: scoping v3/v2.5 (no buzzer), per D1's rev4-as-default rule.

docs/source/menu_map.rst

  • Volume added to the User Pref definition list, next to Key Bright, matching the
    on-device order in menu_structure.py.
  • GPS Baud Rate now says which receiver each speed belongs to: rev4's 10th-generation
    UBlox at 115200, the older v3/v2.5 receiver at 9600 (added mid-task at Rich's request).

Screenshots — new volume_setting_docs.png at 176 px, plus the three existing
Settings Menu shots re-taken at 176 px per D3 rule 3. settings_03.png was also stale:
it showed PiFinder Type / Camera Type at the top level, from before they moved under
Advanced. All four are 352×352 after screenshot_to_doc.py --scale 2, captured with -fb
so the title bar carries the rev4 battery icon.

Vocabulary

The Sound glossary's term is earcon; that stays a domain term. User-facing prose says
"sounds" and "tones", and "earcon" appears nowhere in the manual.

One deviation from the plan, flagged for review

The plan (§4 WP2 task 2) lists errors among the cues and says the setting "only
appears on hardware that has the buzzer."
Neither matches the code, so I documented what
ships:

  • No error tone is wired. Earcon.ERROR and SOLVE_LOCK have catalog entries but
    python/PiFinder/sound.py marks them "defined-but-unwired in v1", and the only
    producers in main.py are STARTUP, SHUTDOWN, KEYPRESS and LOW_BATTERY (plus
    VOLUME_SAMPLE on a volume change). Documenting an error tone would have sent owners
    listening for a sound that never plays.
  • The Volume menu item is not hardware-gated. It is unconditional in
    menu_structure.py; what is gated (main.py:555) is the sound process
    (capabilities.has_buzzer and hardware_platform == "Pi"). So on a v3 the setting is
    present and simply does nothing — which is what the note now says.

Verification

Full clean rebuild against an empty build dir, nitpicky mode, with the docs venv
(Sphinx 7.2.6 + sphinxcontrib-mermaid):

sphinx-build -b html -n docs/source /tmp/pifinder_docs_build_wp2

Zero warnings, zero errors. Baseline was already clean, and menu_map.rst's mermaid
diagrams all build.

Scope

docs/source/*.rst only. No docs/*.md stubs, no docs/ax/*, no ADRs, no
build_guide.rst / BOM.rst (D4). Deliberately kept small to merge cleanly alongside the
sibling WP1/WP3/WP4 branches.

🤖 Generated with Claude Code

The rev4 buzzer and its Settings -> User Pref -> Volume setting shipped in
v2.6.1 with no documentation in either the user guide or the menu map.  An
owner who heard a beep had nowhere to look, and no way to find the off switch.

- user_guide.rst: new "Sounds" sub-section under Settings Menu covering what
  the tones mark (key press, startup, shutdown, low-battery warnings), where
  Volume lives and its range, the sample tone played on selection, and the
  fact that cues differ in loudness because the piezo is far louder near its
  resonant peak.  v3/v2.5 (no buzzer) is scoped to a note, per D1.
- menu_map.rst: Volume added to the User Pref block next to Key Bright,
  matching the on-device order.
- menu_map.rst: GPS Baud Rate now says which receiver each speed belongs to —
  rev4's 10th-generation UBlox at 115200, the older v3/v2.5 receiver at 9600.
- Screenshots: new Volume shot at 176 px, and the three existing Settings Menu
  shots re-taken at 176 px per D3 rule 3.  settings_03 was also stale — it
  showed PiFinder Type / Camera Type at the top level, before they moved under
  Advanced.

Prose says "sounds"/"tones" throughout; "earcon" stays a domain term and is
kept out of the manual.

Docs build clean: zero warnings in nitpicky mode against an empty build dir.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@brickbots
brickbots marked this pull request as ready for review August 7, 2026 21:57
@brickbots
brickbots merged commit 016e028 into main Aug 7, 2026
4 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.

1 participant