bbcmicrobit
diff --git a/‎docs/audio.rst‎
Lines changed: 47 additions & 16 deletions b/‎docs/audio.rst‎
Lines changed: 47 additions & 16 deletions
diff --git a/‎docs/i2c.rst‎
Lines changed: 7 additions & 2 deletions b/‎docs/i2c.rst‎
Lines changed: 7 additions & 2 deletions
diff --git a/‎docs/index.rst‎
Lines changed: 12 additions & 3 deletions b/‎docs/index.rst‎
Lines changed: 12 additions & 3 deletions
diff --git a/‎docs/microbit.rst‎
Lines changed: 3 additions & 0 deletions b/‎docs/microbit.rst‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎docs/microbit_micropython_api.rst‎
Lines changed: 76 additions & 2 deletions b/‎docs/microbit_micropython_api.rst‎
Lines changed: 76 additions & 2 deletions
diff --git a/‎docs/microphone.png‎
48.4 KB b/‎docs/microphone.png‎
48.4 KB
@@ -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
 =================
 
@@ -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()
 
@@ -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
 
@@ -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
@@ -22,6 +22,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.
 
@@ -70,10 +73,44 @@ 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 internally to the I/O that drives the LED matrix and the buttons.
+Provide digital and analog input and output functionality, for the pins in the
+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 keeps the API relatively flat, making it very easy to use:
 
@@ -85,6 +122,8 @@ Each pin is provided as an object directly in the ``microbit`` module.  This kee
     * *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::
 
@@ -102,9 +141,25 @@ Each of these pins are instances of the ``MicroBitPin`` class, which offers the
     # sets the period of the PWM output of the pin in microseconds
     # (see https://en.wikipedia.org/wiki/Pulse-width_modulation)
     pin.set_analog_period_microseconds(int)
-    # returns boolean
+    # Only available for touch pins 0, 1, and 2. Returns boolean if the pin
+    # 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
 ------
 
@@ -275,6 +330,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
 ----