From cd5a13e26f259f7ca5f21e19c27ced37f042fe2c Mon Sep 17 00:00:00 2001 From: Mark Date: Thu, 3 Dec 2020 14:05:31 +0000 Subject: [PATCH 01/11] 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 | 65 +++++++--- docs/i2c.rst | 9 +- docs/index.rst | 15 ++- docs/microbit.rst | 3 + docs/microbit_micropython_api.rst | 196 +++++++++++++++++++++--------- docs/microphone.png | Bin 0 -> 49534 bytes docs/microphone.rst | 124 +++++++++++++++++++ docs/music.rst | 26 ++-- docs/pin.rst | 108 +++++++++------- docs/speech.rst | 18 ++- examples/music.py | 3 +- 11 files changed, 433 insertions(+), 134 deletions(-) create mode 100644 docs/microphone.png create mode 100644 docs/microphone.rst diff --git a/docs/audio.rst b/docs/audio.rst index c824d3b46..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 ================= @@ -63,7 +94,8 @@ 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 ``AudioFrame`` samples at 7812.5 Hz, and uses +The ``audio`` module can consumes an iterable (sequence, like list or tuple, or +generator) of ``AudioFrame`` instances, each 32 samples at 7812.5 Hz, and uses linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable sound quality. @@ -84,4 +116,3 @@ Example .. include:: ../examples/waveforms.py :code: python - diff --git a/docs/i2c.rst b/docs/i2c.rst index 06296bbfa..ec62cb059 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 da3e83cfe..f27da2fcd 100644 --- 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 `_ 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 ` and use the `micro:bit Python Editor `_ 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 index 97bb697e4..4312ac0a3 100644 --- a/docs/microbit.rst +++ b/docs/microbit.rst @@ -64,6 +64,7 @@ Classes :maxdepth: 1 image.rst + Sound Modules @@ -73,8 +74,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 a36ae16f0..e3ee2c838 100644 --- a/docs/microbit_micropython_api.rst +++ b/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 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,27 @@ 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 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 ------ @@ -157,60 +214,68 @@ Images API:: # returns a new image created by multiplying the brightness of each pixel by n image * n - # built-in images. - Image.HEART - Image.HEART_SMALL - Image.HAPPY - Image.SMILE - Image.SAD - Image.CONFUSED - Image.ANGRY - Image.ASLEEP - Image.SURPRISED - Image.SILLY - Image.FABULOUS - Image.MEH - Image.YES - Image.NO - Image.CLOCK12 # clock at 12 o' clock - Image.CLOCK11 - ... # many clocks (Image.CLOCKn) - Image.CLOCK1 # clock at 1 o'clock - Image.ARROW_N - ... # arrows pointing N, NE, E, SE, S, SW, W, NW (microbit.Image.ARROW_direction) - Image.ARROW_NW - Image.TRIANGLE - Image.TRIANGLE_LEFT - Image.CHESSBOARD - Image.DIAMOND - Image.DIAMOND_SMALL - Image.SQUARE - Image.SQUARE_SMALL - Image.RABBIT - Image.COW - Image.MUSIC_CROTCHET - Image.MUSIC_QUAVER - Image.MUSIC_QUAVERS - Image.PITCHFORK - Image.XMAS - Image.PACMAN - Image.TARGET - Image.TSHIRT - Image.ROLLERSKATE - Image.DUCK - Image.HOUSE - Image.TORTOISE - Image.BUTTERFLY - Image.STICKFIGURE - Image.GHOST - Image.SWORD - Image.GIRAFFE - Image.SKULL - Image.UMBRELLA - Image.SNAKE - # built-in lists - useful for animations, e.g. display.show(Image.ALL_CLOCKS) - Image.ALL_CLOCKS - Image.ALL_ARROWS +**Built-in images** + +``Image.HEART`` +``Image.HEART_SMALL`` +``Image.HAPPY`` +``Image.SMILE`` +``Image.SAD`` +``Image.CONFUSED`` +``Image.ANGRY`` +``Image.ASLEEP`` +``Image.SURPRISED`` +``Image.SILLY`` +``Image.FABULOUS`` +``Image.MEH`` +``Image.YES`` +``Image.NO`` +``Image.TRIANGLE`` +``Image.TRIANGLE_LEFT`` +``Image.CHESSBOARD`` +``Image.DIAMOND`` +``Image.DIAMOND_SMALL`` +``Image.SQUARE`` +``Image.SQUARE_SMALL`` +``Image.RABBIT`` +``Image.COW`` +``Image.MUSIC_CROTCHET`` +``Image.MUSIC_QUAVER`` +``Image.MUSIC_QUAVERS`` +``Image.PITCHFORK`` +``Image.XMAS`` +``Image.PACMAN`` +``Image.TARGET`` +``Image.TSHIRT`` +``Image.ROLLERSKATE`` +``Image.DUCK`` +``Image.HOUSE`` +``Image.TORTOISE`` +``Image.BUTTERFLY`` +``Image.STICKFIGURE`` +``Image.GHOST`` +``Image.SWORD`` +``Image.GIRAFFE`` +``Image.SKULL`` +``Image.UMBRELLA`` +``Image.SNAKE`` + +Clock: + +``Image.CLOCK1`` ``Image.CLOCK2`` ``Image.CLOCK3`` ``Image.CLOCK4`` +``Image.CLOCK5`` ``Image.CLOCK6`` ``Image.CLOCK7`` ``Image.CLOCK8`` +``Image.CLOCK9`` ``Image.CLOCK10`` ``Image.CLOCK11`` ``Image.CLOCK12`` + +Arrows: + +``Image.ARROW_N`` ``Image.ARROW_NE`` ``Image.ARROW_E`` ``Image.ARROW_SE`` +``Image.ARROW_S`` ``Image.ARROW_SW`` ``Image.ARROW_W`` ``Image.ARROW_NW`` + +The following are Python lists of images, useful for automatically displaying an +animation or manually iterating through them. + +``Image.ALL_CLOCKS`` +``Image.ALL_ARROWS`` Accelerometer ------------- @@ -266,6 +331,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