Merge branch 'v2-docs' of https://github.com/bbcmicrobit/micropython …

…into v2-docs

# Conflicts:
#	docs/audio.rst

docs/accelerometer.rst

@@ -7,7 +7,7 @@ This object gives you access to the on-board accelerometer.
 
 By default MicroPython sets the accelerometer range to +/- 2000 mg (``g`` being
 a unit of acceleration based on the standard gravity), which configures the
-maximum and minimum values returned by the acceleromter functions.
+maximum and minimum values returned by the accelerometer functions.
 The range can be changed via :func:`microbit.accelerometer.set_range`.
 
 The accelerometer also provides convenience functions for detecting gestures.
@@ -78,13 +78,13 @@ Functions
 .. py:function:: set_range(value)
 
     Set the accelerometer sensitivity range, in g (standard gravity), to the
-    closest values supported by the hardware, so it rounds to either ``1``,
+    closest values supported by the hardware, so it rounds to either
     ``2``, ``4``, or ``8`` g.
 
     :param value: New range for the accelerometer, an integer in ``g``.
 
 Examples
---------
+========
 
 A fortune telling magic 8-ball. Ask a question then shake the device for an
 answer.

docs/audio.rst

@@ -6,29 +6,57 @@ Audio
 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
-:doc:`built-in speaker <speaker>` **V2**. You can connect wired headphones or
+: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.
 
 The ``audio`` module can be imported as ``import audio`` or accessed via
 the ``microbit`` module as ``microbit.audio``.
 
+There are three different kinds of audio sources that can be played using the
+:py:meth:`audio.play` function:
+
+1. `Built in sounds <#built-in-sounds-v2>`_ (**V2**),
+   e.g. ``audio.play(Sound.HAPPY)``
+2. `Sound Effects <#sound-effects-v2>`_ (**V2**), a way to create custom sounds
+   by configuring its parameters::
+
+    my_effect = audio.SoundEffect(freq_start=400, freq_end=2500, duration=500)
+    audio.play(my_effect)
+
+3. `Audio Frames <#audioframe>`_, an iterable (like a list or a generator)
+   of Audio Frames, which are lists of 32 samples with values from 0 to 255::
+
+    square_wave = audio.AudioFrame()
+    for i in range(16):
+        square_wave[i] = 0
+        square_wave[i + 16] = 255
+    audio.play([square_wave] * 64)
+
+
 Functions
 =========
 
 .. py:function:: play(source, wait=True, pin=pin0, return_pin=None)
 
-    Play the source to completion.
+    Play the audio source to completion.
 
-    :param source: ``Sound``: The ``microbit`` module contains a list of
-      built-in sounds that your can pass to ``audio.play()``.
+    :param source: There are three types of data that can be used as a source:
+
+        - ``Sound``: The ``microbit`` module contains a list of
+          built-in sounds, e.g. ``audio.play(Sound.TWINKLE)``. A full list can
+          be found in the `Built in sounds <#built-in-sounds-v2>`_ section.
+        - ``SoundEffect``: A sound effect, or an iterable of sound effects,
+          created via the :py:meth:`audio.SoundEffect` class
+        - ``AudioFrame``: An iterable of ``AudioFrame`` instances as described
+          in the `AudioFrame Technical Details <#id2>`_ section
 
-      ``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: 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``.
+
     :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.
@@ -41,34 +69,9 @@ Functions
 
     Stops all audio playback.
 
-Classes
-=======
-
-.. py:class::
-    AudioFrame
-
-    An ``AudioFrame`` object is a list of 32 samples each of which is an unsigned byte
-    (whole number between 0 and 255).
-
-    It takes just over 4 ms to play a single frame.
-
-    .. py:function:: copyfrom(other)
-
-        Overwrite the data in this ``AudioFrame`` with the data from another
-        ``AudioFrame`` instance.
-
-        :param other: ``AudioFrame`` instance from which to copy the data.
-
-
-Using audio
-===========
-
-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)``.
 
@@ -83,8 +86,154 @@ The built-in sounds can be called using ``audio.play(Sound.NAME)``.
 * ``Sound.TWINKLE``
 * ``Sound.YAWN``
 
+Sounds Example
+--------------
+
+::
+
+    from microbit import *
+
+    while True:
+        if button_a.is_pressed() and button_b.is_pressed():
+            # When pressing both buttons only play via the edge connector
+            audio.play(Sound.HELLO, pin=pin0)
+        elif button_a.is_pressed():
+            # On button A play a sound and when it's done show an image
+            audio.play(Sound.HAPPY)
+            display.show(Image.HAPPY)
+        elif button_b.is_pressed():
+            # On button B play a sound and show an image at the same time
+            audio.play(Sound.TWINKLE, wait=False)
+            display.show(Image.BUTTERFLY)
+
+        sleep(500)
+        display.clear()
+
+
+Sound Effects **V2**
+====================
+
+.. py:class::
+    SoundEffect(freq_start=500, freq_end=2500, duration=500, vol_start=255, vol_end=0, wave=WAVE_SQUARE, fx=FX_NONE, shape=SHAPE_LOG)
+
+    An ``SoundEffect`` instance represents a sound effect, composed by a set of
+    parameters configured via the constructor or attributes.
+
+    All the parameters are optional, with default values as shown above, and
+    they can all be modified via attributes of the same name. For example, we
+    can first create an effect ``my_effect = SoundEffect(duration=1000)``,
+    and then change its attributes ``my_effect.duration = 500``.
+
+    :param freq_start: Start frequency in Hertz (Hz), default: ``500``
+    :param freq_end: End frequency in Hertz (Hz), default: ``2500``
+    :param duration: Duration of the sound (ms), default: ``500``
+    :param vol_start: Start volume value, range 0-255, default: ``255``
+    :param vol_end: End volume value, range 0-255, default: ``0``
+    :param wave: Type of wave shape, one of these values: ``WAVE_SINE``,
+        ``WAVE_SAWTOOTH``, ``WAVE_TRIANGLE``, ``WAVE_SQUARE``,
+        ``WAVE_NOISE`` (randomly generated noise). Default: ``WAVE_SQUARE``
+    :param fx: Effect to add on the sound, one of the following values:
+        ``FX_TREMOLO``, ``FX_VIBRATO``, ``FX_WARBLE``, or ``FX_NONE``.
+        Default: ``FX_NONE``
+    :param shape: The type of the interpolation curve between the start and end
+        frequencies, different wave shapes have different rates of change
+        in frequency. One of the following values: ``SHAPE_LINEAR``,
+        ``SHAPE_CURVE``, ``SHAPE_LOG``. Default: ``SHAPE_LOG``
+
+    .. py:function:: copy()
+
+        :returns: A copy of the SoundEffect.
+
+    .. py:attribute:: freq_start
+
+        Start frequency in Hertz (Hz), a number between ``0`` and ``9999``.
+
+    .. py:attribute:: freq_end
+
+        End frequency in Hertz (Hz), a number between ``0`` and ``9999```.
+
+    .. py:attribute:: duration
+
+        Duration of the sound in milliseconds, a number between ``0`` and
+        ``9999``.
+
+    .. py:attribute:: vol_start
+
+        Start volume value, a number between ``0`` and ``255``.
+
+    .. py:attribute:: vol_end
+
+        End volume value, a number between ``0`` and ``255``.
+
+    .. py:attribute:: wave
+
+        Type of wave shape, one of these values: ``WAVE_SINE``,
+        ``WAVE_SAWTOOTH``, ``WAVE_TRIANGLE``, ``WAVE_SQUARE``,
+        ``WAVE_NOISE`` (randomly generated noise).
+
+    .. py:attribute:: fx
+
+        Effect to add on the sound, one of the following values:
+        ``FX_TREMOLO``, ``FX_VIBRATO``, ``FX_WARBLE``, or ``None``.
+
+    .. py:attribute:: shape
+
+        The type of interpolation curve between the start and end
+        frequencies, different wave shapes have different rates of change
+        in frequency. One of the following values: ``SHAPE_LINEAR``,
+        ``SHAPE_CURVE``, ``SHAPE_LOG``.
+
+The arguments used to create any Sound Effect,
+can be inspected by looking at each of the SoundEffect instance attributes,
+or by converting the instance into a string (which can be done via ``str()``
+function, or by using a function that does the conversion automatically like
+``print()``).
+
+For example, with the :doc:`REPL </devguide/repl>` you can inspect the
+default SoundEffects::
+
+    >>> print(audio.SoundEffect())
+    SoundEffect(freq_start=500, freq_end=2500, duration=500, vol_start=255, vol_end=0, wave=WAVE_SQUARE, fx=FX_NONE, shape=SHAPE_LOG)
+
+This format is "human readable", which means it is easy for us to read,
+and it looks very similar to the code needed to create that SoundEffect,
+but it's not quite right. The ``repr()`` function can be used to create a
+string of Python code that can be stored or transferred
+(you could transmit sounds via micro:bit radio!) and be executed with the
+``eval()`` function::
+
+    >>> from audio import SoundEffect
+    >>> sound_code = repr(SoundEffect())
+    >>> print(sound_code)
+    SoundEffect(500, 2500, 500, 255, 0, 3, 0, 18)
+    >>> eval("audio.play({})".format(sound_code))
+
+Sound Effects Example
+---------------------
+
+.. include:: ../examples/soundeffects.py
+    :code: python
+
+AudioFrame
+==========
+
+.. py:class::
+    AudioFrame
+
+    An ``AudioFrame`` object is a list of 32 samples each of which is an unsigned byte
+    (whole number between 0 and 255).
+
+    It takes just over 4 ms to play a single frame.
+
+    .. py:function:: copyfrom(other)
+
+        Overwrite the data in this ``AudioFrame`` with the data from another
+        ``AudioFrame`` instance.
+
+        :param other: ``AudioFrame`` instance from which to copy the data.
+
 Technical Details
-=================
+-----------------
 
 .. note::
     You don't need to understand this section to use the ``audio`` module.
@@ -104,11 +253,11 @@ samples. When reading reaches the start or the mid-point of the buffer, it
 triggers a callback to fetch the next ``AudioFrame`` which is then copied into
 the buffer. This means that a sound source has under 4ms to compute the next
 ``AudioFrame``, and for reliable operation needs to take less 2ms (which is
-32000 cycles, so should be plenty).
+32000 cycles in micro:bit V1 or 128000 in V2, so should be plenty).
 
 
-Example
-=======
+AudioFrame Example
+------------------
 
 .. include:: ../examples/waveforms.py
     :code: python

docs/i2c.rst

@@ -56,7 +56,7 @@ Functions
 
 
 Connecting
-----------
+==========
 
 You should connect the device's ``SCL`` pin to micro:bit pin 19, and the
 device's ``SDA`` pin to micro:bit pin 20. You also must connect the device's

docs/index.rst

@@ -79,6 +79,7 @@ Projects related to MicroPython on the BBC micro:bit include:
    ble.rst
    button.rst
    compass.rst
+   log.rst
    display.rst
    filesystem.rst
    i2c.rst
@@ -90,6 +91,7 @@ Projects related to MicroPython on the BBC micro:bit include:
    neopixel.rst
    os.rst
    pin.rst
+   power.rst
    radio.rst
    random.rst
    speaker.rst

docs/locale/ja/LC_MESSAGES/accelerometer.po

@@ -1,16 +1,16 @@
 # SOME DESCRIPTIVE TITLE.
-# Copyright (C) 2015-2020, Multiple authors
+# Copyright (C) 2015-2022, Multiple authors
 # This file is distributed under the same license as the BBC micro:bit
 # MicroPython package.
 # FIRST AUTHOR <EMAIL@ADDRESS>, 2022.
 #
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: BBC micro:bit MicroPython 1.0.1\n"
+"Project-Id-Version: BBC micro:bit MicroPython 1.1.0-beta\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2022-04-22 23:33+0900\n"
-"PO-Revision-Date: 2022-04-23 01:16+0900\n"
+"POT-Creation-Date: 2022-09-16 09:08+0900\n"
+"PO-Revision-Date: 2022-09-16 09:22+0900\n"
 "Last-Translator: Minoru Inachi\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
@@ -29,7 +29,7 @@ msgstr "このオブジェクトはボード上の加速度センサーにアク
 msgid ""
 "By default MicroPython sets the accelerometer range to +/- 2000 mg (``g``"
 " being a unit of acceleration based on the standard gravity), which "
-"configures the maximum and minimum values returned by the acceleromter "
+"configures the maximum and minimum values returned by the accelerometer "
 "functions. The range can be changed via "
 ":func:`microbit.accelerometer.set_range`."
 msgstr ""
@@ -148,12 +148,12 @@ msgstr ""
 #: ../../accelerometer.rst:80
 msgid ""
 "Set the accelerometer sensitivity range, in g (standard gravity), to the "
-"closest values supported by the hardware, so it rounds to either ``1``, "
-"``2``, ``4``, or ``8`` g."
+"closest values supported by the hardware, so it rounds to either ``2``, "
+"``4``, or ``8`` g."
 msgstr ""
 "加速度センサーの感度範囲を g (標準重力)で設定します。"
 "設定値は、ハードウェアがサポートする最も近い値、すなわち "
-"``1``, ``2``, ``4``, ``8`` g のいずれかに丸められます。"
+"``2``, ``4``, ``8`` g のいずれかに丸められます。"
 
 #: ../../accelerometer.rst:87
 msgid "Examples"