v2.1 beta docs (#56)

Update corresponds to https://github.com/microbit-foundation/micropython-microbit-v2/releases/tag/v2.1.0-beta.3 so further minor changes are possible.

Co-authored-by: Robert Knight <robert@microbit.org>
Co-authored-by: Carlos Pereira Atencio <carlos@microbit.org>

Author: 3 people

examples/en-only/README.md

@@ -0,0 +1,2 @@
+Temporary home for files that cannot be processed by the translated versions
+yet. After the translation sync they should be found better homes.

examples/en-only/power_one.py

@@ -0,0 +1,31 @@
+from microbit import *
+import power
+
+
+@run_every(s=20)
+def silly_face():
+    display.show(Image.SILLY)
+    sleep(500)
+
+
+while True:
+    if button_a.is_pressed():
+        display.scroll("Off")
+        # In this mode the micro:bit can only wake up via the reset button
+        power.off()
+        # This line of code will never be executed, as waking up from this
+        # mode starts the programme from the beginning
+        display.show(Image.SURPRISED)
+    elif button_b.is_pressed():
+        display.scroll("Sleep")
+        # Go into Deep Sleep with multiple wake up sources
+        power.deep_sleep(
+            wake_on=(pin0, pin1, button_a),
+            ms=5 * 60 * 1000,  # In 5 minutes it wakes up anyway
+            run_every=False,  # Blocks run_every from waking up the board
+        )
+        # When the micro:bit wakes up will it continue running from here
+        display.show(Image.ASLEEP)
+        sleep(1000)
+    display.show(Image.HAPPY)
+    sleep(200)

examples/en-only/power_two.py

@@ -0,0 +1,17 @@
+from microbit import *
+import power
+import log
+
+# Log the temperature every 5 minutes
+@run_every(min=5)
+def log_temperature():
+    log.add(temp=temperature())
+
+
+while True:
+    # Display the temperature when button A is pressed
+    if button_a.is_pressed():
+        display.scroll(temperature())
+    # To go sleep, wake up when button A is pressed, and ensure the
+    # function scheduled with run_every still executes in the background
+    power.deep_sleep(wake_on=button_a, run_every=True)

examples/en-only/sound_effects.py

@@ -0,0 +1,59 @@
+from microbit import *
+
+# Play the default Sound Effect
+audio.play(audio.SoundEffect())
+
+# Create a new Sound Effect and immediately play it
+audio.play(
+    audio.SoundEffect(
+        freq_start=400,
+        freq_end=2000,
+        duration=500,
+        vol_start=100,
+        vol_end=255,
+        waveform=audio.SoundEffect.WAVEFORM_TRIANGLE,
+        fx=audio.SoundEffect.FX_VIBRATO,
+        shape=audio.SoundEffect.SHAPE_LOG,
+    )
+)
+
+# Play a Sound Effect instance, modify an attribute, and play it again
+my_effect = audio.SoundEffect(
+    freq_start=400,
+    freq_end=2000,
+)
+audio.play(my_effect)
+my_effect.duration = 1000
+audio.play(my_effect)
+
+# You can also create a new effect based on an existing one, and modify
+# any of its characteristics via arguments
+my_modified_effect = my_effect.copy()
+my_modified_effect.waveform = audio.SoundEffect.WAVEFORM_NOISE
+audio.play(my_modified_effect)
+
+# Use sensor data to modify and play an existing Sound Effect instance
+my_effect.duration = 600
+while True:
+    # int() might be temporarily needed: https://github.com/microbit-foundation/micropython-microbit-v2/issues/121
+    my_effect.freq_start = int(
+        scale(accelerometer.get_x(), from_=(-2000, 2000), to=(0, 9999))
+    )
+    my_effect.freq_end = int(
+        scale(accelerometer.get_y(), from_=(-2000, 2000), to=(0, 9999))
+    )
+    audio.play(my_effect)
+
+    if button_a.is_pressed():
+        # Button A silences the micro:bit
+        speaker.off()
+        display.show(Image("09090:00000:00900:09990:00900"))
+        sleep(500)
+    elif button_b.is_pressed():
+        # Button B re-enables the speaker & plays an effect while showing an image
+        speaker.on()
+        audio.play(audio.SoundEffect(), wait=False)
+        display.show(Image.MUSIC_QUAVER)
+        sleep(500)
+
+    sleep(150)

lang/en/typeshed/stdlib/audio.pyi

@@ -7,4 +7,5 @@ from .microbit.audio import (
     play as play,
     stop as stop,
     AudioFrame as AudioFrame,
+    SoundEffect as SoundEffect,
 )

lang/en/typeshed/stdlib/log.pyi

@@ -18,44 +18,46 @@ DAYS = 864000
 """Days timestamp format."""
 
 def set_labels(
-    *args: str, timestamp: Optional[Literal[1, 10, 36000, 864000]] = SECONDS
+    *labels: str, timestamp: Optional[Literal[1, 10, 36000, 864000]] = SECONDS
 ) -> None:
     """Set up the log file header.
 
-    Example: ``log.set_labels('x', 'y', 'z', timestamp=log.MINUTES)``
+    Example: ``log.set_labels('X', 'Y', 'Z', timestamp=log.MINUTES)``
 
-    Each call to this function with positional arguments will generate a new
-    header entry into the log file.
+    Ideally this function should be called a single time, before any data is
+    logged, to configure the data table header once.
 
-    If the program starts and a log file already exists it will compare the
-    labels set up by this function call to the last headers declared in the
-    file. If the headers are different it will add a new header entry at the
-    end of the file.
+    If a log file already exists when the program starts, or if this function
+    is called multiple times, it will check the labels already defined in the
+    log file. If this function call contains any new labels not already
+    present, it will generate a new header row with the additional columns.
 
-    :param *args: A positional argument for each log header.
-    :param timestamp: The timestamp unit that will be automatically added as the first column in every row.
-    Setting this argument to ``None`` disables the timestamp. Pass the ``log.MILLISECONDS``, ``log.SECONDS``, , ``log.MINUTES``, ``log.HOURS`` or ``log.DAYS`` values defined by this module. An invalid value will throw an exception.
+    By default the first column contains a timestamp for each row. The time
+    unit can be selected via the timestamp argument.
+
+    :param *labels: Any number of positional arguments, each corresponding to an entry in the log header.
+    :param timestamp: Select the timestamp unit that will be automatically added as the first column in every row. Timestamp values can be one of ``log.MILLISECONDS``, ``log.SECONDS``, ``log.MINUTES``, ``log.HOURS``, ``log.DAYS`` or ``None`` to disable the timestamp. The default value is ``log.SECONDS``.
     """
     ...
 
 @overload
 def add(
-    log_data: Optional[dict[str, Union[str, int, float]]],
+    data_dictionary: Optional[dict[str, Union[str, int, float]]],
 ) -> None:
     """Add a data row to the log by passing a dictionary of headers and values.
 
     Example: ``log.add({ 'temp': temperature() })``
 
     Each call to this function adds a row to the log.
 
-    Dictionary keys not already specified via the ``set_labels`` function,
-    or by a previous call to this function, will trigger a new header
-    entry to be added to the log with the extra label.
+    New labels not previously specified via the set_labels function, or by a
+    previous call to this function, will trigger a new header entry to be added
+    to the log with the extra labels.
 
-    Labels previously specified and not present in this function call will be
-    skipped with an empty value in the log row.
+    Labels previously specified and not present in a call to this function will
+    be skipped with an empty value in the log row.
 
-    :param log_data: The data to log as a dictionary with a key for each header.
+    :param data_dictionary: The data to log as a dictionary with a key for each header.
     """
     ...
 
@@ -67,12 +69,12 @@ def add(**kwargs: Union[str, int, float]) -> None:
 
     Each call to this function adds a row to the log.
 
-    Keyword arguments not already specified via the ``set_labels`` function,
-    or by a previous call to this function, will trigger a new header entry
-    to be added to the log with the extra label.
+    New labels not previously specified via the set_labels function, or by a
+    previous call to this function, will trigger a new header entry to be added
+    to the log with the extra labels.
 
-    Labels previously specified and not present in this function call will be
-    skipped with an empty value in the log row.
+    Labels previously specified and not present in a call to this function will
+    be skipped with an empty value in the log row.
     """
     ...
 
@@ -81,21 +83,22 @@ def delete(full=False):
 
     Example: ``log.delete()``
 
-    To add the log headers the ``set_labels`` function has to be called again
-    after this.
+    To add the log headers again the ``set_labels`` function should to be called after this function.
+
+    There are two erase modes; “full” completely removes the data from the physical storage,
+    and “fast” invalidates the data without removing it.
 
-    :param full: Selects a "full" erase format that removes the data from the flash storage.
-    If set to ``False`` it uses a "fast" method, which invalidates the data instead of performing a slower full erase.
+    :param full: ``True`` selects a “full” erase and ``False`` selects the “fast” erase method.
     """
     ...
 
 def set_mirroring(serial: bool):
-    """Mirrors the data logging activity to the serial output.
+    """Configure mirroring of the data logging activity to the serial output.
 
     Example: ``log.set_mirroring(True)``
 
-    Mirroring is disabled by default.
+    Serial mirroring is disabled by default. When enabled, it will print to serial each row logged into the log file.
 
-    :param serial: Pass ``True`` to mirror the data logging activity to the serial output, ``False`` to disable mirroring.
+    :param serial: ``True`` enables mirroring data to the serial output.
     """
     ...

lang/en/typeshed/stdlib/microbit/__init__.pyi

@@ -1,10 +1,13 @@
 """Pins, images, sounds, temperature and volume.
 """
 
+from typing import Any, Callable, List, Optional, Tuple, overload
+
 from _typeshed import ReadableBuffer
-from typing import Any, Callable, List, Optional, overload
 
+# V2 only
 from . import accelerometer as accelerometer
+from . import audio as audio
 from . import compass as compass
 from . import display as display
 from . import i2c as i2c
@@ -13,9 +16,6 @@ from . import speaker as speaker
 from . import spi as spi
 from . import uart as uart
 
-# V2 only
-from . import audio as audio
-
 def run_every(
     callback: Optional[Callable[[], None]] = None,
     days: int = 0,
@@ -24,28 +24,36 @@ def run_every(
     s: int = 0,
     ms: int = 0,
 ) -> Callable[[Callable[[], None]], Callable[[], None]]:
-    """Schedule a function to be called at a given interval **V2 only**.
+    """Schedule to run a function at the interval specified by the time arguments **V2 only**.
 
     Example: ``run_every(my_logging, min=5)``
 
-    This function can be passed a callback::
-
-        run_every(your_function, h=1, min=20, s=30, ms=50)
+    ``run_every`` can be used in two ways:
 
-    or used as a decorator::
+    As a Decorator - placed on top of the function to schedule. For example::
 
         @run_every(h=1, min=20, s=30, ms=50)
-        def your_function():
-            pass
+        def my_function():
+            # Do something here
+
+    As a Function - passing the callback as a positional argument. For example::
+
+        def my_function():
+            # Do something here
+        run_every(my_function, s=30)
 
-    Arguments with different time units are additive.
+    Each argument corresponds to a different time unit and they are additive.
+    So ``run_every(min=1, s=30)`` schedules the callback every minute and a half.
 
-    :param callback: The callback to invoke. Omit when using as a decorator.
-    :param days: The interval in days.
-    :param h: The interval in hours.
-    :param min: The interval in minutes.
-    :param s: The interval in seconds.
-    :param ms: The interval in milliseconds.
+    When an exception is thrown inside the callback function it deschedules the
+    function. To avoid this you can catch exceptions with ``try/except``.
+
+    :param callback: Function to call at the provided interval. Omit when using as a decorator.
+    :param days: Sets the day mark for the scheduling.
+    :param h: Sets the hour mark for the scheduling.
+    :param min: Sets the minute mark for the scheduling.
+    :param s: Sets the second mark for the scheduling.
+    :param ms: Sets the millisecond mark for the scheduling.
     """
 
 def panic(n: int) -> None:
@@ -61,6 +69,21 @@ def panic(n: int) -> None:
 def reset() -> None:
     """Restart the board."""
 
+def scale(value: float, from_: Tuple[float, float], to: Tuple[float, float]) -> float:
+    """Converts a value from a range to another range.
+
+    Example: ``temp_fahrenheit = scale(30, from_=(0, 100), to=(32, 212))``
+
+    This can be useful to convert values between inputs and outputs, for example an accelerometer X value to a speaker volume.
+
+    Negative scaling is also supported, for example ``scale(25, from_=(0, 100), to=(0, -200))`` will return ``-50``.
+
+    :param value: A number to convert.
+    :param from_: A tuple to define the range to convert from.
+    :param to: A tuple to define the range to convert to.
+    :return: The ``value`` converted to the ``to`` range.
+    """
+
 def sleep(n: float) -> None:
     """Wait for ``n`` milliseconds.
 
@@ -521,6 +544,9 @@ class Image:
     SNAKE: Image
     """Snake image."""
 
+    SCISSORS: Image
+    """Scissors image."""
+
     ALL_CLOCKS: List[Image]
     """A list containing all the CLOCK_ images in sequence."""
 

lang/en/typeshed/stdlib/microbit/accelerometer.pyi

@@ -39,6 +39,15 @@ def get_values() -> Tuple[int, int, int]:
     """
     ...
 
+def get_strength() -> int:
+    """Get the acceleration measurement of all axes combined, as a positive integer. This is the Pythagorean sum of the X, Y and Z axes.
+
+    Example: ``accelerometer.get_strength()``
+
+    :return: The combined acceleration strength of all the axes, in milli-g.
+    """
+    ...
+
 def current_gesture() -> str:
     """Get the name of the current gesture.
 
@@ -96,3 +105,11 @@ def get_gestures() -> Tuple[str, ...]:
     :return: The history as a tuple, most recent last.
     """
     ...
+
+def set_range(value: int) -> None:
+    """Set the accelerometer sensitivity range, in g (standard gravity), to the closest values supported by the hardware, so it rounds to either ``2``, ``4``, or ``8`` g.
+
+    Example: ``accelerometer.set_range(8)``
+
+    :param value: New range for the accelerometer, an integer in ``g``.
+    """