update i2c

Author: microbit-mark

docs/audio.rst

@@ -21,12 +21,11 @@ Functions
 
     Play the source to completion.
 
-    ``source`` is an iterable, each element of which must be an ``AudioFrame``.
+    ``source`` is an iterable, each element of which must be an ``AudioFrame``
+    or built-in ``Sound``.
 
     If ``wait`` is ``True``, this function will block until the source is exhausted.
 
-    ``pin`` specifies which pin the speaker is connected to.
-
     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, you can use ``microbit.pin_speaker``
@@ -41,6 +40,15 @@ Functions
     ``return_pin`` specifies a differential edge connector pin to connect 
     to an exteernal speaker instead of ground.
 
+.. py:function:: is_playing()
+
+    Return ``True`` if audio is playing, otherwise
+    return ``False``.
+
+.. py:function:: stop()
+    
+    Stops all audio playback.
+
 Classes
 =======
 
@@ -55,9 +63,23 @@ 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** or generate your own, like in ``examples/waveforms.py``.
+
+Built-in sounds **V2**
+---------------
+
 
+    * ``Sound.GIGGLE``
+    * ``Sound.HAPPY``
+    * ``Sound.HELLO``
+    * ``Sound.MYSTERIOUS``
+    * ``Sound.SAD``
+    * ``Sound.SLIDE``
+    * ``Sound.SOARING``
+    * ``Sound.SPRING``
+    * ``Sound.TWINKLE``
+    * ``Sound.YAWN``
 
 Technical Details
 =================

docs/i2c.rst

@@ -28,8 +28,12 @@ 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 sensr and the edge connector.
+        
 
 
 .. py:function:: scan()

docs/microbit_micropython_api.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 heaphones 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.
 
@@ -76,20 +79,20 @@ Microphone **V2**
 This Microphone is accessed via the `microphone` object::
 
     # Value to represent loud sound events, like clapping or shouting.
-    LOUD = "loud"
+    SoundEvent.LOUD = "loud"
     # Value to represent quiet sound events, like speaking or background music.
-    QUIET = "quiet"
+    SoundEvent.QUIET = "quiet"
     # The name of the last recorded sound event, `loud` or `quiet`.
     current_sound()
-    # A sound event,  such as `microphone.LOUD` or `microphone.QUIET`. 
+    # 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_sound(event)
     # A tuple of the event history. The most recent is listed last.
     # Also clears the sound event history before returning.
     get_sounds()
     # The threshold level in the range 0-255. For example,
-    # `set_threshold(microphone.LOUD, 250)` will only trigger if the
+    # `set_threshold(SoundEvent.LOUD, 250)` will only trigger if the
     # sound is very loud (>= 250).
     set_threshold()
     # A representation of the sound pressure level in the range 0 to 255.
@@ -315,6 +318,26 @@ 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)
 
+Sounds **V2**
+------
+
+A set of expressive sounds are available to the micro:bit **V2** and can be
+accessed via the ``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
 ----
 
@@ -334,4 +357,4 @@ Use ``uart`` to communicate with a serial device connected to the device's I/O p
     # read bytes into the referenced buffer.
     uart.readinto(buffer)
     # write bytes from the buffer to the connected device.
-    uart.write(buffer)
+    uart.write(buffer)

docs/microphone.png

@@ -9,9 +9,9 @@ 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: 200px
+    :width: 300px
     :align: center
-    :height: 200px
+    :height: 240px
     :alt: micro:bit with microphone LED on
 
 Sound events
@@ -28,103 +28,56 @@ Classes
 .. py:class:: MicrobitMicrophone
 
     .. note::
-        The `MicrobitMicroPhone` class documented here can be accessed via the microbit module as
-        `microbit.microphone`. It cannot be initialised on it's own.
-
-    Represents the microphone
-
-    #: Value to represent loud sound events, like clapping or shouting
-    LOUD = "loud"
-    #: Value to represent quiet sound events, like speaking or background music
-    QUIET = "quiet"
-
-    def current_sound(self) -> string:
-        """
-        :return: The name of the last recorded sound event, `loud` or `quiet`.
-        """
-        pass
-
-    def was_sound(self, sound: string) -> bool:
-        """
-        :param sound: A sound event,  such as `microphone.LOUD` or
-            `microphone.QUIET`.
-        :return: `true` if sound was heard at least once since the last
-        call, otherwise `false`.
-        """
-        pass
-
-    def get_sounds(self):
-        """
-        :return: A tuple of the event history. The most recent is listed last.
-        Also clears the sound event history before returning
-        """
-        pass
-
-    def set_threshold(self, sound: string, level: int) -> None:
-        """
-        :param sound: A sound event, such as `microphone.LOUD` or
-        `microphone.QUIET`.
-        :param value: The threshold level in the range 0-255. For example,
-            `set_threshold(microphone.LOUD, 250)` will only trigger if the
-            sound is very loud (>= 250).
-        """
-        pass
-
-    def sound_level(self) -> int:
-        """
-        :return: A representation of the sound pressure level in the range 0 to
-        20000.
-        """
-        pass
+        The ``MicrobitMicroPhone`` class documented here can be accessed via 
+        the microbit module as ``microbit.microphone``. It cannot be
+        initialised on it's own.
+
+    Represents the microphone.
+
+.. py:class:: SoundEvent  
+
+    Value to represent loud sound events, like clapping or shouting
+    ``SoundEvent.LOUD`` = ``loud``.
+
+    Value to represent quiet sound events, like speaking or background music
+    ``SoundEvent.QUIET`` = ``quiet``.
+
+.. py:function:: current_event()
+
+    Returns the name of the last recorded sound event, ``loud`` or ``quiet``.
+
+.. py:function:: was_event(SoundEvent.LOUD)
+
+    Parameter: 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``.
+
+.. py:function:: get_events():
+
+    Returns a tuple of the event history. The most recent is listed last.
+
+    Also clears the sound event history before returning.
+
+.. py:function:: set_threshold()
+
+    Parameter: A sound event, such as ``SoundEvent.LOUD`` or ``SoundEvent.QUIET``.
+    
+    Parameter: 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()
+
+    Returns a representation of the sound pressure level in the range 0 to
+    255.
+
 
 Example
 =======
 
-An example that runs through all the functions of the microphone API
-
-.. code::
-
-    # 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 shoul try this test whilst
-    # making a loud sound and a quiet one before you shake.
-
-    from microbit import *
-
-    icons = {
-        microphone.LOUD: Image.SQUARE,
-        microphone.QUIET: Image.SQUARE_SMALL
-    }
-
-    display.clear()
-    sound = microphone.current_sound()
-
-    while True:
-        if button_a.is_pressed():
-            if microphone.current_sound() == microphone.LOUD:
-                display.show(Image.SQUARE)
-                uart.write('isLoud\n')
-            elif microphone.current_sound() == microphone.QUIET:
-                display.show(Image.SQUARE_SMALL)
-                uart.write('isQuiet\n')
-            sleep(500)
-        display.clear()
-        if button_b.is_pressed():
-            if microphone.was_sound(microphone.LOUD):
-                display.show(Image.SQUARE)
-                uart.write('wasLoud\n')
-            elif microphone.was_sound(microphone.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_sounds()
-            soundLevel = microphone.sound_level()
-            print(soundLevel)
-            for sound in sounds:
-                display.show(icons[sound])
-                print(sound)
-                sleep(500)
+An example that runs through some of the functions of the microphone API
+
+.. include:: ../examples/microphone.py
+    :code: python

docs/microphone.rst

@@ -95,7 +95,7 @@ Functions
 
     An optional argument to specify the output pin can be used to override the
     default of ``microbit.pin0``. If you have the latest micro:bit, you can
-    use ``microbit.pin_speaker``**V2**.
+    use ``microbit.pin_speaker`` **V2**.
 
     .. note::
         Using this argument will disable the default functionality on the

docs/music.rst

@@ -24,7 +24,7 @@ depending upon the digital reading on pin 0::
 Pin Functions
 =============
 
-`Edge connector and pinout <https://tech.microbit.org/hardware/edgeconnector/#edge-connector-pins)>`_
+`Edge connector and pinout <https://tech.microbit.org/hardware/edgeconnector/#edge-connector-pins>`_
 
 Those pins are available as attributes on the ``microbit``
 module:``microbit.pin0`` - ``microbit.pin20``.
@@ -80,6 +80,7 @@ in MicroPython, but that are not available via the edge connector:
 
 - ``pin_logo`` - A touch sensitive logo pin on the front of the micro:bit. which by 
 default is set to capacative touch mode.
+
 - ``pin_speaker`` - A pin to control the sound output of the micro:bit speaker.
 
 
@@ -209,7 +210,7 @@ its own to that.
 
         .. note::
             The default touch mode for the pins on the edge connector is 
-            `resistive`. The default for the logo pin **V2** is capacative.
+            `resistive`. The default for the logo pin **V2** is `capacative`.
 
         **Resitive touch**
         This test is done by measuring how much resistance there is between the
@@ -219,7 +220,7 @@ its own to that.
 
         **Capacative touch**
         This test is done by interacting with the electric field of a capacitor
-        using the a finger as a conductor.`Capacative touch 
+        using the a finger as a conductor.`Capacative touch
         <https://www.allaboutcircuits.com/technical-articles/introduction-to-capacitive-touch-sensing/>`_
         does not require you to make a ground connection as part of a circuit.
 

docs/pin.rst

@@ -0,0 +1,46 @@
+# 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 shoul try this test whilst making a loud sound 
+# and a quiet one before you shake.
+
+from microbit import *
+
+icons = {
+    SoundEvent.LOUD: Image.SQUARE,
+    SoundEvent.QUIET: Image.SQUARE_SMALL
+}
+
+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:
+            display.show(icons[sound])
+            print(sound)
+            sleep(500)