Docs: Speaker update and play() pin arguments (bbcmicrobit#695)

* speaker pin changes

* Docs: update speaker pin info

* Add speaker page

* grammar

* Link to speaker page

* add speaker to navigation

* add speaker example

* Update docs/speaker.rst

Co-authored-by: Carlos Pereira Atencio <[email protected]>

* Update docs/speaker.rst

Co-authored-by: Carlos Pereira Atencio <[email protected]>

* Update docs/music.rst

Co-authored-by: Carlos Pereira Atencio <[email protected]>

* Docs: Update speaker pin

* remove build

* gitignore _build directory

* update music

* Update docs/music.rst

* Update docs/speech.rst

* Update docs/speech.rst

* Update docs/speech.rst

* Update docs/music.rst

Co-authored-by: Carlos Pereira Atencio <[email protected]>

Author: microbit-mark

.gitignore

@@ -1,5 +1,6 @@
 .yotta.json
 build/*
+_build/*
 yotta_modules/*
 yotta_targets/*
 *.swp

docs/audio.rst

@@ -7,14 +7,13 @@ 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.
 
 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.
+:doc:`built-in speaker <speaker>` **V2**. You can connect 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.
 
@@ -27,12 +26,9 @@ Functions
     * **wait**: If ``wait`` is ``True``, this function will block until the
       source is exhausted.
 
-    * **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.
+    * **pin**: An optional argument to specify the output pin can be used to
+    override the default of ``pin0``. If we do not want any sound to play
+    we can use ``pin=None``.
 
     * **return_pin**: specifies a differential edge connector pin to connect
       to an external speaker instead of ground. This is ignored for the **V2**

docs/index.rst

@@ -94,6 +94,7 @@ Projects related to MicroPython on the BBC micro:bit include:
    pin.rst
    radio.rst
    random.rst
+   speaker.rst
    speech.rst
    spi.rst
    uart.rst

docs/microbit.rst

@@ -77,5 +77,6 @@ Modules
     display.rst
     i2c.rst
     microphone.rst
+    speaker.rst
     spi.rst
     uart.rst

docs/microbit_micropython_api.rst

@@ -154,13 +154,7 @@ pin_logo::
 
 pin_speaker:
 
-As 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()
+As above ``MicroBitPin`` class, but does not include ``pin.is_touched()``.
 
 Images
 ------
@@ -350,6 +344,20 @@ accessed via the ``microbit`` module and played with the :doc:`audio <audio>` mo
 ``Sound.TWINKLE``
 ``Sound.YAWN``
 
+Speaker **V2**
+--------------
+
+The speaker is enabled by default and can be accessed using the ``speaker`` object. It
+can be turned off or on::
+
+    # disable the built-in speaker
+    speaker.off()
+    # enable the built-in speaker
+    speaker.on()
+    # returns True or False to indicate if the speaker is on or off
+    speaker.is_on()
+
+
 UART
 ----
 

docs/music.rst

@@ -5,8 +5,8 @@ Music
 
 This is the ``music`` module and you can use it to create and play melodies.
 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 sound:
+:doc:`built-in speaker <speaker>` **V2**. You can connect wired headphones or
+a speaker to pin 0 and GND on the edge connector to hear the sound:
 
 .. image:: music-pins.png
 
@@ -80,7 +80,6 @@ Functions
     Gets the current tempo as a tuple of integers: ``(ticks, bpm)``.
 
 .. py:function:: play(music, pin=pin0, wait=True, loop=False)
-                 play(music, pin=(pin_speaker, pin0) wait=True,loop=False)
 
     Plays ``music`` containing the musical DSL defined above.
 
@@ -95,36 +94,37 @@ Functions
     their defaults before the music (whatever it may be) is played.
 
     An optional argument to specify the output pin can be used to override the
-    default of ``microbit.pin0``. With micro:bit **V2** you can use
-    ``microbit.pin_speaker`` or a tuple of two pins, for example
-    ``pin=(pin_speaker, pin0)`` which would output sound on the built-in
-    speaker and pin 0.
+    default of ``microbit.pin0``. If we do not want any sound to play we can
+    use ``pin=None``.
 
     If ``wait`` is set to ``True``, this function is blocking.
 
     If ``loop`` is set to ``True``, the tune repeats until ``stop`` is called
     (see below) or the blocking call is interrupted.
 
-.. py:function:: pitch(frequency, duration=-1, pin=microbit.pin0, wait=True)
-                 pitch(frequency, duration=-1, pin=(pin_speaker, pin0), wait=True)
+.. py:function:: pitch(frequency, duration=-1, pin=pin0, wait=True)
 
     Plays a pitch at the integer frequency given for the specified number of
     milliseconds. For example, if the frequency is set to 440 and the length to
     1000 then we hear a standard concert A for one second.
 
     Note that you can only play one pitch on one pin at any one time.
 
+    An optional argument to specify the output pin can be used to override the
+    default of ``microbit.pin0``. If we do not want any sound to play out of
+    the pins we can use ``pin=None``.
+
     If ``wait`` is set to ``True``, this function is blocking.
 
-    If ``duration`` is negative the pitch is played continuously until either the
-    blocking call is interrupted or, in the case of a background call, a new
-    frequency is set or ``stop`` is called (see below).
+    If ``duration`` is negative the pitch is played continuously until either
+    the blocking call is interrupted or, in the case of a background call, a
+    new frequency is set or ``stop`` is called (see below).
 
 .. py:function:: stop(pin=pin0)
-                 stop(pin=(pin_speaker, pin0))
     
-    Stops all music playback on a given pin, eg. ``music.stop(pin_speaker)``
-    **V2**. If no pin is given, eg. ``music.stop()`` pin0 is assumed.
+    Stops all music playback on the built-in speaker and any pin outputting
+    sound. An optional argument can be provided to specify a pin, eg.
+    ``music.stop(pin1)``.
 
 .. py:function:: reset()
 

docs/pin.rst

@@ -81,7 +81,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 capacitive touch mode.
 
-* ``pin_speaker`` - A pin to control the sound output of the micro:bit speaker.
+* ``pin_speaker`` - A pin to address the micro:bit speaker.
 
 
 Pulse-Width Modulation

docs/speaker.png

@@ -0,0 +1,56 @@
+Speaker **V2**
+**************
+
+.. py:module:: microbit.speaker
+
+The micro:bit **V2** has a built-in speaker located on the rear of the board.
+
+.. image:: speaker.png
+    :width: 300px
+    :align: center
+    :height: 240px
+    :alt: speaker on rear of micro:bit V2
+
+By default sound output will be via the edge connector on pin 0 and the
+built-in speaker **V2**. You can connect wired headphones or a speaker to
+pin 0 and GND on the edge connector to hear the sounds.
+
+The speaker can be turned off or on using the functions listed here.
+
+Functions
+=========
+
+.. py:function:: off()
+
+    Use off() to turn off the speaker. This does not disable sound output, so
+    you will still hear sound on Pin 0 if you have headphones or a speaker
+    connected to that pin.
+
+.. py:function:: on()
+
+    Use ``on()`` to turn on the speaker.
+
+.. py:function:: is_on()
+
+    Returns ``True`` if the speaker is on, otherwise returns ``False``.
+
+Example
+=======
+
+An example that runs through some of the functions of the speaker API. ::
+
+    from microbit import *
+    import audio
+
+    # Check that the speaker is on
+    print(speaker.is_on())
+    # Play a sound
+    audio.play(Sound.HELLO)
+    sleep(2000)
+    # Disable the speaker
+    speaker.off()
+    # Check that the speaker is off
+    print(speaker.is_on())
+    # Play a sound. This will not be heard on the speaker, but will be heard
+    # on Pin 0 if you have headphones or a speaker connected.
+    audio.play(Sound.HELLO)

docs/speaker.rst

@@ -5,8 +5,8 @@ Speech
 
 This module makes the micro:bit talk, sing and make other speech like sounds.
 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 sound:
+:doc:`built-in speaker <speaker>` **V2**. You can connect wired headphones or
+a speaker to pin 0 and GND on the edge connector to hear the sound:
 
 .. image:: speech.png
 
@@ -46,32 +46,27 @@ Functions
     emphasis.
 
 .. py:function:: pronounce(phonemes, \*, pitch=64, speed=72, mouth=128, throat=128)
-                 pronounce(phonemes, \*, pitch=64, speed=72, mouth=128, throat=128, pin=(pin_speaker, pin0))
+                 pronounce(phonemes, \*, pitch=64, speed=72, mouth=128, throat=128, pin=pin0)
 
     Pronounce the phonemes in the string ``phonemes``. See below for details of
     how to use phonemes to finely control the output of the speech synthesiser.
     Override the optional pitch, speed, mouth and throat settings to change the
     timbre (quality) of the voice.
 
-    As with the music module, you can use 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 **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.
+    For micro:bit **V2** an optional argument to specify the output pin can be
+    used to override the default of ``pin0``. If we do not want any sound to
+    play out of the pins can use ``pin=None``.
 
 .. py:function:: say(words, \*, pitch=64, speed=72, mouth=128, throat=128)
-                 say(words, \*, pitch=64, speed=72, mouth=128, throat=128, pin=(pin_speaker, pin0))
+                 say(words, \*, pitch=64, speed=72, mouth=128, throat=128, pin=pin0)
 
     Say the English words in the string ``words``. The result is semi-accurate
     for English. Override the optional pitch, speed, mouth and throat
     settings to change the timbre (quality) of the voice. This is a short-hand
     equivalent of: ``speech.pronounce(speech.translate(words))``
 
 .. py:function:: sing(phonemes, \*, pitch=64, speed=72, mouth=128, throat=128)
-                 sing(phonemes, \*, pitch=64, speed=72, mouth=128, throat=128, pin=(pin_speaker, pin0))
+                 sing(phonemes, \*, pitch=64, speed=72, mouth=128, throat=128, pin=pin0)
 
     Sing the phonemes contained in the string ``phonemes``. Changing the pitch
     and duration of the note is described below. Override the optional pitch,