bbcmicrobit · microbit-carlos · Dec 3, 2020 · Dec 18, 2020 · Dec 18, 2020 · Dec 21, 2020
diff --git a/docs/audio.rst b/docs/audio.rst
@@ -3,32 +3,43 @@ 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
+: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``.
 
-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 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: 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.
+
+.. py:function:: is_playing()
+
+    :returns: ``True`` if audio is playing, otherwise returns ``False``.
+
+.. py:function:: stop()
+
+    Stops all audio playback.
 
 Classes
 =======
@@ -52,9 +63,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 +90,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 +112,3 @@ Example
 
 .. include:: ../examples/waveforms.py
     :code: python
-
diff --git a/docs/ble.rst b/docs/ble.rst
@@ -1,10 +1,13 @@
 Bluetooth
 *********
 
+micro:bit V1
+============
+
 While the BBC micro:bit has hardware capable of allowing the device to work as
 a Bluetooth Low Energy (BLE) device, it only has 16k of RAM. The BLE stack
 alone takes up 12k RAM which means there's not enough memory for MicroPython
-to support Bluetooth.
+to support Bluetooth on a micro:bit V1.
 
 .. note::
     MicroPython uses the radio hardware with the :mod:`radio` module. This
@@ -13,3 +16,15 @@ to support Bluetooth.
 
     Furthermore, the protocol used in the :mod:`radio` module is a lot simpler
     than BLE, making it far easier to use in an educational context.
+
+micro:bit V2
+============
+
+The nRF52833 used by the micro:bit V2 has 128k of RAM, allowing Micropython to make
+use of the BLE stack. Currently the only implemented feature is BLE flashing, allowing 
+a user to update the firmware on the micro:bit over Bluetooth.
+
+At the time that this was written the `Nordic DFU service <https://infocenter.nordicsemi.com/topic/sdk_nrf5_v16.0.0/lib_bootloader_dfu_process.html>`_ is implemented, and partial flashing is currently working but in
+beta. The Nordic DFU service updates everything in flash and will take a (relatively) long
+time to complete, whereas the partial flashing service only updates the filesystem containing
+the user scripts.
diff --git a/docs/devguide/devfaq.rst b/docs/devguide/devfaq.rst
diff --git a/docs/devguide/flashfirmware.rst b/docs/devguide/flashfirmware.rst
@@ -1,65 +1,116 @@
 .. _flashfirmware:
 
-=================
-Flashing Firmware
-=================
+===========================
+Build and flash MicroPython
+===========================
 
-Building firmware
------------------
-Use yotta to build.
+micro:bit V1
+============
 
-Use target bbc-microbit-classic-gcc-nosd::
+This applies to MicroPython for the micro:bit V1, the source of which can be 
+found here: `bbcmicrobit/micropython <https://github.com/bbcmicrobit/micropython>`_.
 
-  yotta target bbc-microbit-classic-gcc-nosd
+Dependencies
+------------
+- `cMake <https://cmake.org/>`_
+- `Arm gcc <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads>`_
+- `git <https://git-scm.com/>`_
+- `ninja <https://ninja-build.org/>`_
+- `python <https://www.python.org/downloads/>`_
+- `srecord <http://srecord.sourceforge.net/>`_
+- `yotta <http://docs.yottabuild.org//>`_
 
-Run yotta update to fetch remote assets::
+The `yotta
+<http://docs.yottabuild.org//>`_ tool is used to build MicroPython, but before
+that takes place additional files have to be generated by the Makefile in
+preparation for the build, and additional data is added to the hex file after.
 
-  yotta up
+Clone the repository and change directory to it::
 
-Start the build with either yotta::
+  $ git clone https://github.com/bbcmicrobit/micropython
 
-  yotta build
+  $ cd micropython
 
-...or use the Makefile::
+Configure yotta to use the micro:bit target::
 
-  make all
+  yotta target bbc-microbit-classic-gcc-nosd@https://github.com/lancaster-university/yotta-target-bbc-microbit-classic-gcc-nosd
 
-The result is a microbit-micropython hex file (i.e. ``microbit-micropython.hex``)
-found in the build/bbc-microbit-classic-gcc-nosd/source from the root of the
-repository.
+Run yotta update to fetch remote assets::
 
-The Makefile does some extra preprocessing of the source, which is needed only
-if you add new interned strings to ``qstrdefsport.h``. The Makefile also puts
-the resulting firmware at build/firmware.hex, and includes some convenience
-targets.
+  yotta up
+
+Start the build using the makefile::
+
+  make all
+
+The resulting ``firmware.hex`` can be found in the ``build/`` 
+directory which can then be copied to the micro:bit.
 
 Preparing firmware and a Python program
 ---------------------------------------
 
-A script in the following location, called using the following syntax, should
-help::
+Using ``tools/makecombinedhex.py`` you can combine the MicroPython firmware
+with a Python script and produce a hex file ready for uploading to the
+micro:bit.::
 
-  tools/makecombinedhex.py <firmware.hex> <script.py> [-o <combined.hex>]
+  ./makecombinedhex.py <firmware.hex> <script.py> [-o <combined.hex>]
 
 The script will output to ``stdout`` if no output option (``-o``) is provided.
 
-Flashing to the micro:bit
--------------------------
+Using ``tools/hexlify.py`` you can turn a Python script into Intel HEX format
+to be concatenated at the end of the MicroPython firmware.hex.  A simple header
+is added to the script.::
+
+  ./hexlifyscript.py <script.py>
+
+It also accepts data on standard input.
+
+
+micro:bit V2
+============
 
-The Microbit mounts itself as a mass storage device over USB.  When it detects
-that a .hex file has been uploaded to the internal mass storage device, it will
-flash itself with the bytecode representation, and start running the program.
+This applies to MicroPython for the micro:bit V2, the source of which can be 
+found here: `microbit-foundation/micropython-microbit-v2 <https://github.com/microbit-foundation/micropython-microbit-v2>`_.
 
-This means that uploading a .hex file should result in the Microbit running your
-code.
+The repository also contains a history of 
+`MicroPython firmware builds <https://github.com/microbit-foundation/micropython-microbit-v2/actions>`_.
 
+Dependencies
+------------
 
+- `Arm gcc <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads>`_
+- `gcc <http://gcc.gnu.org/install/>`_
+- `cMake <https://cmake.org/>`_
+- `git <https://git-scm.com/>`_ 
+- `ninja <https://ninja-build.org/>`_
+- `python <https://www.python.org/downloads/>`_
 
-**Installation Scenarios**
+Clone the repository and change directory to it::
+
+    $ git clone https://github.com/microbit-foundation/micropython-microbit-v2
+    $ cd micropython-microbit-v2
+
+Update the submodules::
+
+    $ git submodule update --init
+
+Then build the MicroPython cross-compiler::
+
+    $ make -C lib/micropython/mpy-cross
+
+After setting up, go to the src/ directory and build::
+
+    $ cd src
+
+    $ make
+
+The resulting firmware will be ``MICROBIT.hex`` in the ``src/`` 
+directory which can be copied to the micro:bit.
+
+
+Flashing to the micro:bit
+=========================
 
-* :ref:`Windows <microbit-windows>`
-* :ref:`OS X <microbit-osx>`
-* :ref:`Linux <microbit-linux>`
-* :ref:`Debian and Ubuntu <microbit-debian-ubuntu>`
-* :ref:`Red Hat Fedora/CentOS <microbit-redhat>`
-* :ref:`Raspberry Pi <microbit-rpi>`
+The micro:bit mounts itself as a USB mass storage device named ``MICROBIT``.
+When it detects that a .hex file has been copied to the USB drive, it will
+flash itself, and start running the program.