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 <carlos@microbit.org> * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/i2c.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * changes based on initial feedback * update return pin * sound is in microbit module * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * more feedback updates * spacing * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * 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 <carlos@microbit.org> * 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 <carlos@microbit.org> * 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 <carlos@microbit.org> * Update docs/microphone.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/microphone.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/music.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org> * more updates Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org>
bbcmicrobit · Apr 21, 2022 · 38403c0 · 38403c0
1 parent f37681e
commit 38403c0
Show file tree

Hide file tree

Showing 13 changed files with 465 additions and 164 deletions.
diff --git a/docs/audio.rst b/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
-
diff --git a/docs/conf.py b/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

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