audio module
Many of these functions are available in three variants: headphone volume,
speaker volume, and volume. If headphones_are_connected() returns 1
the "headphone" variant is chosen, else the "speaker" variant is chosen.
Headphone port policy
Under normal circumstances it is an important feature to have a reliable speaker mute when plugging in headphones. However, since the headphone port on the badge can also be used for badge link, there are legimate cases where it is desirable to have the speakers unmuted while a cable is plugged into the jack.
As a person who plugs in the headphones on the tram, doesn't put them on, turns on music to check if it's not accidentially playing on speakers and then finally puts on headphones (temporarily, of course, intermittent checks if the speakers didn't magically turn on are scheduled according to our general anxiety level) we wish to make it difficult to accidentially have sound coming from the speakers.
Our proposed logic is as follows (excluding boot conditions):
- Badge link TX cannot be enabled for any of the headphone jack pins without a cable detected in the jack. This is to protect users from plugging in headphones while badge link is active and receiving a short but potentially very loud burst of digital data before the software can react to the state change.
- If the software detects that the headphone jack has changed from unplugged to plugged it always turns off speakers, no exceptions.
- If a user wishes to TX on headphone badge link, they must confirm a warning that having headphones plugged in may potentially cause hearing damage every time.
- If a user wishes to RX or TX on headphone badge link while playing sound on the onboard speakers, they must confirm a warning every time.
We understand that these means seem extreme, but we find them to be a sensible default configuration to make sure people can safely operate the device without needing to refer to a manual.
(TX here means any state that is not constantly ~GND with whatever impedance. While there are current limiting resistors (value TBD at the time of writing, but presumably 100R-470R) in series with the GPIOs, they still can generate quite some volume with standard 40Ohm-ish headphones. Ideally the analog switch will never switch to the GPIOs without a cable plugged in.)