From c182652ef1082a2046447591bc87adbc0d9c2bb1 Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Tue, 22 Aug 2023 18:55:02 +0100 Subject: [PATCH] docs: Add `SoundEvent.CLAP` (V2). --- docs/microbit_micropython_api.rst | 4 ++- docs/microphone.rst | 48 ++++++++++++++++++------------- 2 files changed, 31 insertions(+), 21 deletions(-) diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst index 19362fdac..b3c8e5fe1 100644 --- a/docs/microbit_micropython_api.rst +++ b/docs/microbit_micropython_api.rst @@ -87,6 +87,8 @@ Sound events describe changes in the sound heard by the microphone:: # Value to represent the transition of sound events, from `loud` to `quiet` # like speaking or background music. SoundEvent.QUIET = SoundEvent('quiet') + # Value to represent a loud event similar to a clap. + SoundEvent.CLAP = SoundEvent('clap') Microphone **V2** ----------------- @@ -95,7 +97,7 @@ The Microphone is accessed via the `microphone` object:: # Returns the name of the last recorded sound event. current_event() - # A sound event, such as `SoundEvent.LOUD` or `SoundEvent.QUIET`. + # A sound event, such as `SoundEvent.LOUD`, `SoundEvent.QUIET`, or `SoundEvent.CLAP`. # Returns`true` if sound was heard at least once since the last # call, otherwise `false`. was_event(event) diff --git a/docs/microphone.rst b/docs/microphone.rst index 3cc74c8e9..3136d835c 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``: @@ -26,48 +26,48 @@ accessible via variables in ``microbit.SoundEvent``: from ``loud`` to ``quiet`` like speaking or background music. - ``microbit.SoundEvent.LOUD``: Represents the transition of sound events, - from ``quiet`` to ``loud`` like clapping or shouting. + from ``quiet`` to ``loud`` like shouting. + +- ``microbit.SoundEvent.CLAP``: Detects a loud event similar to a clap. Functions ========= .. py:function:: current_event() - * **return**: the name of the last recorded sound event, - ``SoundEvent('loud')`` or ``SoundEvent('quiet')``. + :returns: The name of the last recorded sound event, + ``SoundEvent('loud')``, ``SoundEvent('quiet')``, ``SoundEvent('clap')``. .. 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 + :param event: A sound event, such as ``SoundEvent.LOUD``, + ``SoundEvent.QUIET``, or ``SoundEvent.CLAP``. + :returns: ``true`` if sound was heard at least once since the last call, otherwise ``false``. ``was_event()`` also clears the sound event history before returning. .. 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 + :param event: A sound event, such as ``SoundEvent.LOUD`` or + ``SoundEvent.QUIET``, or ``SoundEvent.CLAP``. + :returns: ``true`` if sound event is the most recent since the last call, otherwise ``false``. It does not clear the sound event history. .. py:function:: get_events() - * **return**: a tuple of the event history. The most recent is listed last. + :returns: A tuple of the event history. The most recent is listed last. ``get_events()`` also clears the sound event history before returning. .. 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, + :param event: A ``SoundEvent.LOUD`` or ``SoundEvent.QUIET`` sound event. + :param 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). .. py:function:: sound_level() - * **return**: a representation of the sound pressure level in the range 0 to + :returns: A representation of the sound pressure level in the range 0 to 255. @@ -80,7 +80,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 * @@ -90,7 +90,10 @@ An example that runs through some of the functions of the microphone API:: while True: if button_a.is_pressed(): - if microphone.current_event() == SoundEvent.LOUD: + if microphone.current_event() == SoundEvent.CLAP: + display.show(Image.DIAMOND) + uart.write('isClap\n') + elif microphone.current_event() == SoundEvent.LOUD: display.show(Image.SQUARE) uart.write('isLoud\n') elif microphone.current_event() == SoundEvent.QUIET: @@ -99,7 +102,10 @@ An example that runs through some of the functions of the microphone API:: sleep(500) display.clear() if button_b.is_pressed(): - if microphone.was_event(SoundEvent.LOUD): + if microphone.was_event(SoundEvent.CLAP): + display.show(Image.DIAMOND) + uart.write('wasClap\n') + elif microphone.was_event(SoundEvent.LOUD): display.show(Image.SQUARE) uart.write('wasLoud\n') elif microphone.was_event(SoundEvent.QUIET): @@ -114,7 +120,9 @@ An example that runs through some of the functions of the microphone API:: soundLevel = microphone.sound_level() print(soundLevel) for sound in sounds: - if sound == SoundEvent.LOUD: + if sound == SoundEvent.CLAP: + display.show(Image.DIAMOND) + elif sound == SoundEvent.LOUD: display.show(Image.SQUARE) elif sound == SoundEvent.QUIET: display.show(Image.SQUARE_SMALL)