docs: Update the docs to include the V2 API (#692)

* Add microphone API * include V2 on index * update music and V2 pins * update speech * update audio * update i2c * add description to built-in sounds * format sounds * format pins * format pins * spelling * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/i2c.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * changes based on initial feedback * update return pin * sound is in microbit module * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * more feedback updates * spacing * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * does this comment work? * Revert "does this comment work?" This reverts commit 4846113. * update audio * update audio * add Python Editor * add references to sound * update mic image * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * multiple fixes * use Param in docs * update SouneEvent * update microphone module * update param * update image list * update parameters * remove note * update param * add line break * add mic and make clases a-z * format parameters * Update docs/microbit_micropython_api.rst * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * more updates * tidy up * move SoundEvent * Revert "move SoundEvent" This reverts commit 8f52c97. * move soundEvent * update image list * remove param reference * more feedback updates * move audio to modules * Update docs/music.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microphone.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/microphone.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/music.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <[email protected]> * more updates Co-authored-by: Carlos Pereira Atencio <[email protected]>
bbcmicrobit · microbit-carlos · Dec 3, 2020 · Dec 18, 2020 · Dec 18, 2020 · Dec 21, 2020
commit 1be9e872a27f4bada4e12d63b2d8f08e1bd6fcc5
diff --git a/docs/audio.rst b/docs/audio.rst
@@ -3,32 +3,47 @@ Audio
 
 .. py:module:: audio
 
-This module allows you play sounds from a speaker attached to the micro:bit.
+This module allows you play sounds with the micro:bit.
+
+By default sound output will be via the edge connector on pin 0 and the
+built-in speaker **V2**. You can connect a wired headphones or a speaker to
+pin 0 and GND on the edge connector to hear the sounds.
 
 The ``audio`` module can be imported as ``import audio`` or accessed via
 the ``microbit`` module as ``microbit.audio``.
 
-In order to use the audio module you will need to provide a sound source.
-
-A sound source is an iterable (sequence, like list or tuple, or a generator) of
-frames, each of 32 samples.
-The ``audio`` modules plays samples at the rate of 7812.5 samples per second,
-which means that it can reproduce frequencies up to 3.9kHz.
-
 Functions
 =========
 
 .. py:function:: play(source, wait=True, pin=pin0, return_pin=None)
+                 play(source, wait=True, pin=(pin_speaker, pin0), return_pin=None)
 
     Play the source to completion.
 
-    :param source: An iterable sound source, each element of which must be
-        an ``AudioFrame``.
+    :param source: ``Sound``: The ``microbit`` module contains a list of
+      built-in sounds that your can pass to ``audio.play()``.
+
+      ``AudioFrame``: The source agrument can also be an iterable
+      of ``AudioFrame`` elements as described below.
     :param wait: If ``wait`` is ``True``, this function will block until the
         source is exhausted.
-    :param pin: Specifies which pin the speaker is connected to.
-    :param return_pin: Specifies a differential pin to connect to the speaker
-        instead of ground.
+    :param pin: As with the music module, you can use the optional ``pin``
+      argument to specify the output pin can be used to override the
+      default of ``microbit.pin0``. If you have the latest micro:bit **V2**,
+      you can use ``microbit.pin_speaker``. The pin argument can also take a
+      tuple of two pins, for example ``pin=(pin_speaker, pin0)`` which would
+      output sound on the built-in speaker and pin 0.
+    :param return_pin: specifies a differential edge connector pin to connect
+      to an external speaker instead of ground. This is ignored for the **V2**
+      revision.
+
+.. py:function:: is_playing()
+
+    :returns: ``True`` if audio is playing, otherwise returns ``False``.
+
+.. py:function:: stop()
+
+    Stops all audio playback.
 
 Classes
 =======
@@ -52,9 +67,25 @@ Classes
 Using audio
 ===========
 
-You will need a sound source, as input to the ``play`` function. You can generate your own, like in
-``examples/waveforms.py``.
-
+You will need a sound source, as input to the ``play`` function. You can use
+the built-in sounds **V2** from the ``microbit`` module, ``microbit.Sound``, or
+generate your own, like in ``examples/waveforms.py``.
+
+Built-in sounds **V2**
+----------------------
+
+The built-in sounds can be called using ``audio.play(Sound.NAME)``.
+
+* ``Sound.GIGGLE``
+* ``Sound.HAPPY``
+* ``Sound.HELLO``
+* ``Sound.MYSTERIOUS``
+* ``Sound.SAD``
+* ``Sound.SLIDE``
+* ``Sound.SOARING``
+* ``Sound.SPRING``
+* ``Sound.TWINKLE``
+* ``Sound.YAWN``
 
 Technical Details
 =================

diff --git a/docs/i2c.rst b/docs/i2c.rst
@@ -28,8 +28,13 @@ Functions
 
     .. warning::
 
-        Changing the I²C pins from defaults will make the accelerometer and
-        compass stop working, as they are connected internally to those pins.
+        On a micro:bit V1 board, changing the I²C pins from defaults will make
+        the accelerometer and compass stop working, as they are connected
+        internally to those pins. This warning does not apply to the **V2**
+        revision of the micro:bit as this has `separate I²C lines
+        <https://tech.microbit.org/hardware/i2c/>`_
+        for the motion sensors and the edge connector.
+
 
 
 .. py:function:: scan()

diff --git a/docs/index.rst b/docs/index.rst
@@ -17,6 +17,13 @@ This documentation includes lessons for teachers
 and API documentation for developers (check out the index on the left). We hope
 you enjoy developing for the BBC micro:bit using MicroPython.
 
+.. note::
+
+    The BBC micro:bit MicroPython documentation contains information for all 
+    versions of the micro:bit board. Where functionality is applicable only
+    to the latest device, you will see a note or comment marking this as 
+    **V2**.
+
 If you're a new programmer, teacher or unsure where to start, begin with the
 :ref:`Tutorials <Tutorials>` and use the `micro:bit Python Editor <https://python.microbit.org>`_
 to program the micro:bit. 
@@ -77,6 +84,7 @@ Projects related to MicroPython on the BBC micro:bit include:
    i2c.rst
    image.rst
    machine.rst
+   microphone.rst
    micropython.rst
    music.rst
    neopixel.rst

diff --git a/docs/microbit.rst b/docs/microbit.rst
@@ -90,6 +90,7 @@ Classes
     :maxdepth: 1
 
     image.rst
+    Sound <audio.rst>
 
 
 Modules
@@ -99,8 +100,10 @@ Modules
     :maxdepth: 1
 
     accelerometer.rst
+    Audio V2 <audio.rst>
     compass.rst
     display.rst
     i2c.rst
+    microphone.rst
     spi.rst
     uart.rst
diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst
@@ -26,6 +26,9 @@ There are a few functions available directly::
     panic(error_code)
     # resets the micro:bit.
     reset()
+    # sets the output volume (0-255) of the micro:bit speaker **V2** and
+    # external speaker or headphones connected to the edge connector pins.
+    set_volume(128)    # V2
 
 The rest of the functionality is provided by objects and classes in the microbit module, as described below.
 
@@ -74,11 +77,43 @@ The LED display is exposed via the `display` object::
     # written messages).
     display.scroll(string, delay=400)
 
+SoundEvent **V2**
+-----------------
+Sound events describe changes in the sound heard by the microphone::
+
+    # Value to represent the transition of sound events, from `quiet` to `loud`
+    # like clapping or shouting.
+    SoundEvent.LOUD = SoundEvent('loud')
+    # Value to represent the transition of sound events, from `loud` to `quiet`
+    # like speaking or background music.
+    SoundEvent.QUIET = SoundEvent('quiet')
+
+Microphone **V2**
+-----------------
+
+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`. 
+    # Returns`true` if sound was heard at least once since the last
+    # call, otherwise `false`.
+    was_event(event)
+    # Returns a tuple of the event history. The most recent is listed last.
+    # Also clears the sound event history before returning.
+    get_events()
+    # 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_threshold(128)
+    # Returns a representation of the sound pressure level in the range 0 to 255.
+    sound_level()
+
 Pins
 ----
 
 Provide digital and analog input and output functionality, for the pins in the
-connector. Some pins are connected
+connector, the **V2** logo and the **V2** speaker. Some pins are connected
 internally to the I/O that drives the LED matrix and the buttons.
 
 Each pin is provided as an object directly in the ``microbit`` module.  This
@@ -92,6 +127,8 @@ keeps the API relatively flat, making it very easy to use:
     * *Warning: P17-P18 (inclusive) are unavailable.*
     * pin19
     * pin20
+    * pin_logo **V2**
+    * pin_speaker **V2**
 
 Each of these pins are instances of the ``MicroBitPin`` class, which offers the following API::
 
@@ -113,6 +150,21 @@ Each of these pins are instances of the ``MicroBitPin`` class, which offers the
     # is touched
     pin.is_touched()
 
+Except in the case of the pins marked **V2**, which offers the following API:
+
+pin_logo::
+
+    # returns boolean for logo touch pin
+    pin_logo.is_touched()
+
+pin_speaker, as the above ``MicroBitPin`` class, but does not include
+``pin.is_touched()`` and includes::
+
+    # disable the built-in speaker
+    pin_speaker.disable()
+    # enable the built-in speaker
+    pin_speaker.enable()
+
 Images
 ------
 
@@ -277,6 +329,25 @@ There is an I2C bus on the micro:bit that is exposed via the `i2c` object.  It h
     # write buf to device with addr; repeat=True means a stop bit won't be sent.
     i2c.write(addr, buf, repeat=False)
 
+Sound **V2**
+------------
+
+A set of expressive sounds are available to the micro:bit **V2**. They can be
+accessed via the ``microbit`` module and played with the :doc:`audio <audio>` module.
+
+**Built-in sounds**
+
+``Sound.GIGGLE``
+``Sound.HAPPY``
+``Sound.HELLO``
+``Sound.MYSTERIOUS``
+``Sound.SAD``
+``Sound.SLIDE``
+``Sound.SOARING``
+``Sound.SPRING``
+``Sound.TWINKLE``
+``Sound.YAWN``
+
 UART
 ----
 

diff --git a/docs/microphone.png b/docs/microphone.png
diff --git a/docs/microphone.rst b/docs/microphone.rst
@@ -0,0 +1,124 @@
+Microphone **V2**
+*****************
+
+.. py:module:: microbit.microphone
+
+This object lets you access the built-in microphone available on the
+micro:bit **V2**. It can be used to respond to sound. The microphone input
+is located on the front of the board alongside a microphone activity LED,
+which is lit when the microphone is in use.
+
+.. image:: microphone.png
+    :width: 300px
+    :align: center
+    :height: 240px
+    :alt: micro:bit with microphone LED on
+
+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. 
+
+These sound events are represented by instances of the ``SoundEvent`` class,
+accessible via variables in ``microbit.SoundEvent``:
+
+- ``microbit.SoundEvent.QUIET``: Represents the transition of sound events,
+  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.
+
+Functions
+=========
+
+.. py:function:: current_event()
+
+    * **return**: the name of the last recorded sound 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.
+
+.. 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.
+
+.. 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.
+
+.. 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).
+
+.. py:function:: sound_level()
+
+    * **return**: a representation of the sound pressure level in the range 0 to
+      255.
+
+
+Example
+=======
+
+An example that runs through some of the functions of the microphone API::
+
+    # Basic test for microphone.  This test should update the display when
+    # 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 
+    # and a quiet one before you shake.
+
+    from microbit import *
+
+    display.clear()
+    sound = microphone.current_event()
+
+    while True:
+        if button_a.is_pressed():
+            if microphone.current_event() == SoundEvent.LOUD:
+                display.show(Image.SQUARE)
+                uart.write('isLoud\n')
+            elif microphone.current_event() == SoundEvent.QUIET:
+                display.show(Image.SQUARE_SMALL)
+                uart.write('isQuiet\n')
+            sleep(500)
+        display.clear()
+        if button_b.is_pressed():
+            if microphone.was_event(SoundEvent.LOUD):
+                display.show(Image.SQUARE)
+                uart.write('wasLoud\n')
+            elif microphone.was_event(SoundEvent.QUIET):
+                display.show(Image.SQUARE_SMALL)
+                uart.write('wasQuiet\n')
+            else:
+                display.clear()
+            sleep(500)
+        display.clear()
+        if accelerometer.was_gesture('shake'):
+            sounds = microphone.get_events()
+            soundLevel = microphone.sound_level()
+            print(soundLevel)
+            for sound in sounds:
+                if sound == SoundEvent.LOUD:
+                    display.show(Image.SQUARE)
+                elif sound == SoundEvent.QUIET:
+                    display.show(Image.SQUARE_SMALL)
+                else:
+                    display.clear()
+                print(sound)
+                sleep(500)