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]>

Author: microbit-mark

docs/audio.rst

@@ -3,29 +3,48 @@ Audio
 
 .. py:module:: audio
 
-This module allows you play sounds from a speaker attached to the Microbit.
-In order to use the audio module you will need to provide a sound source.
+This module allows you to play your own sounds. If you are using a micro:bit
+**V2**, ``audio`` is also part of the ``microbit`` module.
 
-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.
+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.
 
 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.
 
-    ``source`` is an iterable, each element of which must be an ``AudioFrame``.
+    * **source**: ``Sound`` - The ``microbit`` module contains a list of
+      built-in sounds that your can pass to ``audio.play()``.
 
-    If ``wait`` is ``True``, this function will block until the source is exhausted.
+    * **source**: ``AudioFrame`` - The source agrument can also be an iterable
+      of ``AudioFrame`` elements as described below.
 
-    ``pin`` specifies which pin the speaker is connected to.
+    * **wait**: If ``wait`` is ``True``, this function will block until the
+      source is exhausted.
 
-    ``return_pin`` specifies a differential pin to connect to the speaker
-    instead of ground.
+    * **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.
+
+    * **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()
+
+    Return ``True`` if audio is playing, otherwise return ``False``.
+
+.. py:function:: stop()
+    
+    Stops all audio playback.
 
 Classes
 =======
@@ -41,9 +60,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
 =================
@@ -52,23 +87,24 @@ 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 samples at 7812.5 Hz, and uses linear interpolation to
-output a PWM signal at 32.5 kHz, which gives tolerable sound quality.
+The ``audio`` module consumes ``AudioFrame`` samples at 7812.5 Hz, and uses
+linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable
+sound quality.
 
 The function ``play`` fully copies all data from each ``AudioFrame`` before it
-calls ``next()`` for the next frame, so a sound source can use the same ``AudioFrame``
-repeatedly.
+calls ``next()`` for the next frame, so a sound source can use the same
+``AudioFrame`` repeatedly.
 
-The ``audio`` module has an internal 64 sample buffer from which it reads samples.
-When reading reaches the start or the mid-point of the buffer, it triggers a callback to
-fetch the next ``AudioFrame`` which is then copied into the buffer.
-This means that a sound source has under 4ms to compute the next ``AudioFrame``,
-and for reliable operation needs to take less 2ms (which is 32000 cycles, so should be plenty).
+The ``audio`` module has an internal 64 sample buffer from which it reads
+samples. When reading reaches the start or the mid-point of the buffer, it
+triggers a callback to fetch the next ``AudioFrame`` which is then copied into
+the buffer. This means that a sound source has under 4ms to compute the next
+``AudioFrame``, and for reliable operation needs to take less 2ms (which is
+32000 cycles, so should be plenty).
 
 
 Example
 =======
 
 .. include:: ../examples/waveforms.py
     :code: python
-

docs/conf.py

@@ -53,7 +53,7 @@
 
 # General information about the project.
 project = u'BBC micro:bit MicroPython'
-copyright = u'2015-2016, Multiple authors'
+copyright = u'2015-2020, Multiple authors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

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()

docs/index.rst

@@ -8,15 +8,24 @@ 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.
 
-If you're a new programmer, teacher or unsure where to start, begin with the tutorials.
+.. 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
+tutorials.
 
 .. image:: comic.png
 
@@ -28,8 +37,15 @@ If you're a new programmer, teacher or unsure where to start, begin with the tut
 
 Projects related to MicroPython on the BBC micro:bit include:
 
-* `Mu <https://github.com/ntoll/mu>`_ - a simple code editor for kids, teachers and beginner programmers. Probably the easiest way for people to program MicroPython on the BBC micro:bit.
-* `uFlash <https://uflash.readthedocs.io/en/latest/>`_ - a command line tool for flashing raw Python scripts onto a BBC micro:bit.
+* `micro:bit Python Editor <https://python.microbit.org>`_ A simple
+  browser-based code editor, designed to help teachers and learners get the
+  most out of text-based programming on the micro:bit.
+
+* `Mu <https://codewith.mu>`_ A simple offline code editor for kids, teachers
+  and beginner programmers.
+
+* `uFlash <https://uflash.readthedocs.io/en/latest/>`_ A command line tool
+  for flashing raw Python scripts onto a BBC micro:bit.
 
 .. toctree::
     :maxdepth: 2
@@ -67,6 +83,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

docs/microbit.rst

@@ -62,6 +62,7 @@ Classes
     :maxdepth: 1
 
     image.rst
+    Sound <audio.rst>
 
 
 Modules
@@ -70,9 +71,11 @@ Modules
 .. toctree::
     :maxdepth: 1
 
-    display.rst
-    uart.rst
-    spi.rst
-    i2c.rst
     accelerometer.rst
+    Audio V2 <audio.rst>
     compass.rst
+    display.rst
+    i2c.rst
+    microphone.rst
+    spi.rst
+    uart.rst