From 1be9e872a27f4bada4e12d63b2d8f08e1bd6fcc5 Mon Sep 17 00:00:00 2001 From: Mark Date: Thu, 3 Dec 2020 14:05:31 +0000 Subject: [PATCH 01/21] 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 * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio * Update docs/i2c.rst Co-authored-by: Carlos Pereira Atencio * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio * changes based on initial feedback * update return pin * sound is in microbit module * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio * more feedback updates * spacing * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio * does this comment work? * Revert "does this comment work?" This reverts commit 48461132dae5dcd016c39acb1c6765a74f291471. * 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 * 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 * more updates * tidy up * move SoundEvent * Revert "move SoundEvent" This reverts commit 8f52c9728fe49c9219b1e54c7258b5bb4701d6c1. * 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 * Update docs/microphone.rst Co-authored-by: Carlos Pereira Atencio * Update docs/microbit_micropython_api.rst Co-authored-by: Carlos Pereira Atencio * Update docs/microphone.rst Co-authored-by: Carlos Pereira Atencio * Update docs/music.rst Co-authored-by: Carlos Pereira Atencio * Update docs/audio.rst Co-authored-by: Carlos Pereira Atencio * more updates Co-authored-by: Carlos Pereira Atencio --- docs/audio.rst | 63 +++++++++++---- docs/i2c.rst | 9 ++- docs/index.rst | 8 ++ docs/microbit.rst | 3 + docs/microbit_micropython_api.rst | 73 +++++++++++++++++- docs/microphone.png | Bin 0 -> 49534 bytes docs/microphone.rst | 124 ++++++++++++++++++++++++++++++ docs/music.rst | 22 ++++-- docs/pin.rst | 111 +++++++++++++++----------- docs/speech.rst | 18 ++++- examples/music.py | 3 +- 11 files changed, 361 insertions(+), 73 deletions(-) create mode 100644 docs/microphone.png create mode 100644 docs/microphone.rst diff --git a/docs/audio.rst b/docs/audio.rst index f62f02b07..17d5f47c5 100644 --- a/docs/audio.rst +++ b/docs/audio.rst @@ -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 ================= diff --git a/docs/i2c.rst b/docs/i2c.rst index 3224eb3f7..aa9266c16 100644 --- 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 + `_ + for the motion sensors and the edge connector. + .. py:function:: scan() diff --git a/docs/index.rst b/docs/index.rst index 43e2b2ee2..47035c8e2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,13 @@ 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 ` and use the `micro:bit Python Editor `_ to program the micro:bit. @@ -77,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 index 125e5e896..a13a7ed4d 100644 --- a/docs/microbit.rst +++ b/docs/microbit.rst @@ -90,6 +90,7 @@ Classes :maxdepth: 1 image.rst + Sound Modules @@ -99,8 +100,10 @@ Modules :maxdepth: 1 accelerometer.rst + Audio V2 compass.rst display.rst i2c.rst + microphone.rst spi.rst uart.rst diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst index 2063c3381..574215cf0 100644 --- a/docs/microbit_micropython_api.rst +++ b/docs/microbit_micropython_api.rst @@ -26,6 +26,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. @@ -74,11 +77,43 @@ 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 +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 @@ -92,6 +127,8 @@ keeps the API relatively flat, making it very easy to use: * *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:: @@ -113,6 +150,21 @@ Each of these pins are instances of the ``MicroBitPin`` class, which offers the # 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 ------ @@ -277,6 +329,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