docs: Add SoundEvent.CLAP (V2).

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)

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)