docs: dev guide updates (bbcmicrobit#711)

Completes and merges build and flash pages.
Adds V2 info.
Removes outdated FAQ page.
Adds WebUSB info to REPL page.

Rebase update: Keeps and updates the flashing paragraph in
flashfirmware page.

Author: microbit-mark

docs/devguide/devfaq.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.

docs/devguide/flashfirmware.rst

@@ -121,23 +121,15 @@ found here: `microbit-foundation/micropython-microbit-v2 <https://github.com/mic
 This is a port of MicroPython to the micro:bit which uses CODAL as the 
 underlying target platform.
 
-After cloning this repository 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
-
-That will build both ``libmicropython.a`` (from source in ``src/codal_port/``) and the 
-CODAL app (from source in ``src/codal_app/``). The resulting firmware will be 
-``MICROBIT.hex`` in the ``src/`` directory which can be copied to the micro:bit.
+Running the ``make`` command executes the following steps:
+
+- Create build output directory, run cmake, and make sure codal libraries
+  exist (via cmake).
+- Build both ``libmicropython.a`` (from source in ``src/codal_port/``) and the 
+  CODAL app (from source in ``src/codal_app/``).
+- Run ``addlayouttable.py`` to add the layout table to the .hex file
+- Create the microbit-micropython firmware as ``MICROBIT.hex`` in the ``src/``
+  directory, which can be copied to the micro:bit.
 
 Including a user script
 -----------------------