docs: document sound cues and the Volume setting (WP2) - #576
Merged
Conversation
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
marked this pull request as ready for review
August 7, 2026 21:57
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.rstnormenu_map.rst. A rev4 owner who heard a beep had nowhere to look, and no way to find theoff switch. This closes that gap.
What changed
docs/source/user_guide.rst— newSoundssub-section at the end of Settings Menu:level so you can set it by ear;
in loudness by design, not as a fault;
.. note::scoping v3/v2.5 (no buzzer), per D1's rev4-as-default rule.docs/source/menu_map.rstVolumeadded to the User Pref definition list, next to Key Bright, matching theon-device order in
menu_structure.py.GPS Baud Ratenow says which receiver each speed belongs to: rev4's 10th-generationUBlox at 115200, the older v3/v2.5 receiver at 9600 (added mid-task at Rich's request).
Screenshots — new
volume_setting_docs.pngat 176 px, plus the three existingSettings Menu shots re-taken at 176 px per D3 rule 3.
settings_03.pngwas 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-fbso 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:
Earcon.ERRORandSOLVE_LOCKhave catalog entries butpython/PiFinder/sound.pymarks them "defined-but-unwired in v1", and the onlyproducers in
main.pyareSTARTUP,SHUTDOWN,KEYPRESSandLOW_BATTERY(plusVOLUME_SAMPLEon a volume change). Documenting an error tone would have sent ownerslistening for a sound that never plays.
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 ispresent 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):Zero warnings, zero errors. Baseline was already clean, and
menu_map.rst's mermaiddiagrams all build.
Scope
docs/source/*.rstonly. Nodocs/*.mdstubs, nodocs/ax/*, no ADRs, nobuild_guide.rst/BOM.rst(D4). Deliberately kept small to merge cleanly alongside thesibling WP1/WP3/WP4 branches.
🤖 Generated with Claude Code