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 cd5a13e26f259f7ca5f21e19c27ced37f042fe2c
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
 =================
@@ -63,7 +94,8 @@ Technical Details
     You don't need to understand this section to use the ``audio`` module.
     It is just here in case you wanted to know how it works.
 
-The ``audio`` module consumes ``AudioFrame`` samples at 7812.5 Hz, and uses
+The ``audio`` module can consumes an iterable (sequence, like list or tuple, or
+generator) of ``AudioFrame`` instances, each 32 samples at 7812.5 Hz, and uses
 linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable
 sound quality.
 
@@ -84,4 +116,3 @@ Example
 
 .. include:: ../examples/waveforms.py
     :code: python
-
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
@@ -8,14 +8,22 @@ BBC micro:bit MicroPython documentation
 
 Welcome!
 
-The BBC micro:bit is a small computing device for children. One of the
-languages it understands is the popular Python programming language. The
-version of Python that runs on the BBC micro:bit is called MicroPython.
+The `BBC micro:bit <https://microbit.org>`_ is a small computing device for
+children. One of the languages it understands is the popular Python programming
+language. The version of Python that runs on the BBC micro:bit is called
+MicroPython.
 
 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. 
@@ -76,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
@@ -64,6 +64,7 @@ Classes
     :maxdepth: 1
 
     image.rst
+    Sound <audio.rst>
 
 
 Modules
@@ -73,8 +74,10 @@ Modules
     :maxdepth: 1
 
     accelerometer.rst
+    Audio V2 <audio.rst>
     compass.rst
     display.rst
     i2c.rst
+    microphone.rst
     spi.rst
     uart.rst