From d805b37daed59c78416e18f5e25c316b3a1023fb Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Fri, 5 Apr 2024 18:31:12 +0100 Subject: [PATCH 1/2] docs: Improve descriptions for microphone module. --- docs/microphone.rst | 59 +++++++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/docs/microphone.rst b/docs/microphone.rst index 3cc74c8e9..3748d7ad8 100644 --- a/docs/microphone.rst +++ b/docs/microphone.rst @@ -17,7 +17,7 @@ which is lit when the microphone is in use. Sound events ============ The microphone can respond to a pre-defined set of sound events that are -based on the amplitude and wavelength of the sound. +based on the amplitude and wavelength of the sound. These sound events are represented by instances of the ``SoundEvent`` class, accessible via variables in ``microbit.SoundEvent``: @@ -33,42 +33,55 @@ Functions .. py:function:: current_event() - * **return**: the name of the last recorded sound event, - ``SoundEvent('loud')`` or ``SoundEvent('quiet')``. + Get the last recorded sound event + + :return: The event, ``SoundEvent('loud')`` or ``SoundEvent('quiet')``. .. py:function:: was_event(event) - * **event**: a sound event, such as ``SoundEvent.LOUD`` or - ``SoundEvent.QUIET``. - * **return**: ``true`` if sound was heard at least once since the last - call, otherwise ``false``. ``was_event()`` also clears the sound - event history before returning. + Check if a sound was heard at least once since the last call. + + This call clears the sound history before returning. + + :param event: The event to check for, such as ``SoundEvent.LOUD`` or + ``SoundEvent.QUIET`` + :return: ``True`` if sound was heard at least once since the last call, + otherwise ``False``. .. py:function:: is_event(event) - * **event**: a sound event, such as ``SoundEvent.LOUD`` or - ``SoundEvent.QUIET``. - * **return**: ``true`` if sound event is the most recent since the last - call, otherwise ``false``. It does not clear the sound event history. + Check the most recent sound event detected. + + This call does not clear the sound event history. + + :param event: The event to check for, such as ``SoundEvent.LOUD`` or + ``SoundEvent.QUIET`` + :return: ``True`` if sound was the most recent heard, ``False`` otherwise. .. py:function:: get_events() - * **return**: a tuple of the event history. The most recent is listed last. - ``get_events()`` also clears the sound event history before returning. + Get the sound event history as a tuple. + + This call clears the sound history before returning. + + :return: A tuple of the event history with the most recent event last. .. py:function:: set_threshold(event, value) - * **event**: a sound event, such as ``SoundEvent.LOUD`` or - ``SoundEvent.QUIET``. - - * **value**: The threshold level in the range 0-255. For example, - ``set_threshold(SoundEvent.LOUD, 250)`` will only trigger if the sound is - very loud (>= 250). + Set the threshold for a sound event. + + A high threshold means the event will only trigger if the sound is + very loud (>= 250 in the example). + + :param event: A sound event, such as ``SoundEvent.LOUD`` or + ``SoundEvent.QUIET``. + :param value: The threshold level in the range 0-255. .. py:function:: sound_level() - * **return**: a representation of the sound pressure level in the range 0 to - 255. + Get the sound pressure level. + + :return: A representation of the sound pressure level in the range 0 to 255. Example @@ -80,7 +93,7 @@ An example that runs through some of the functions of the microphone API:: # Button A is pressed and a loud or quiet sound *is* heard, printing the # results. On Button B this test should update the display when a loud or # quiet sound *was* heard, printing the results. On shake this should print - # the last sounds heard, you should try this test whilst making a loud sound + # the last sounds heard, you should try this test whilst making a loud sound # and a quiet one before you shake. from microbit import * From ad7e00f5db67ef12c82f5a8bbc84e12d20487587 Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Fri, 5 Apr 2024 18:40:23 +0100 Subject: [PATCH 2/2] docs: Add more info to `microphone.set_threshold()`. --- docs/microphone.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/microphone.rst b/docs/microphone.rst index 3748d7ad8..88a847031 100644 --- a/docs/microphone.rst +++ b/docs/microphone.rst @@ -33,7 +33,7 @@ Functions .. py:function:: current_event() - Get the last recorded sound event + Get the last recorded sound event. :return: The event, ``SoundEvent('loud')`` or ``SoundEvent('quiet')``. @@ -44,7 +44,7 @@ Functions This call clears the sound history before returning. :param event: The event to check for, such as ``SoundEvent.LOUD`` or - ``SoundEvent.QUIET`` + ``SoundEvent.QUIET``. :return: ``True`` if sound was heard at least once since the last call, otherwise ``False``. @@ -70,12 +70,20 @@ Functions Set the threshold for a sound event. - A high threshold means the event will only trigger if the sound is - very loud (>= 250 in the example). + The ``SoundEvent.LOUD`` event will be triggered when the sound level + crosses this threshold upwards (from "quiet" to "loud"), + and ``SoundEvent.QUIET`` event is triggered when crossing the threshold + downwards (from "loud" to "quiet"). + + If the ``SoundEvent.LOUD`` value set is lower than ``SoundEvent.QUIET``, + then "quiet" threshold will be decreased to one unit below the "loud" + threshold. If the ``SoundEvent.QUIET`` value is set higher than + ``SoundEvent.LOUD``, then the "loud" threshold will be set one unit above. :param event: A sound event, such as ``SoundEvent.LOUD`` or ``SoundEvent.QUIET``. - :param value: The threshold level in the range 0-255. + :param value: The threshold level in the range 0-255. Values outside this + range will be clamped. .. py:function:: sound_level()