From dc722f3930f708d483eb700655d695558d4865a5 Mon Sep 17 00:00:00 2001 From: Sam Kent <32453267+microbit-sam@users.noreply.github.com> Date: Wed, 3 Feb 2021 11:59:25 +0000 Subject: [PATCH] docs: Update Memory layout, Partial Flashing, Building for V2, BLE (#705) * Add layout table and partial flashing * deprecated appending script * add build info for v2 * Add section on BLE DFU for V2 * Carlos' feedback * fix filesystem link * fixup! fix filesystem link * fixup! fixup! fix filesystem link * formatting * formatting * fix filesystem link * Update docs/devguide/hexformat.rst Co-authored-by: Carlos Pereira Atencio --- docs/ble.rst | 17 ++++++- docs/devguide/hexformat.rst | 90 ++++++++++++++++++++++++++++++++++--- 2 files changed, 101 insertions(+), 6 deletions(-) diff --git a/docs/ble.rst b/docs/ble.rst index 739e087c4..5847dd492 100644 --- 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 `_ 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/hexformat.rst b/docs/devguide/hexformat.rst index f04b25da9..02b078627 100644 --- a/docs/devguide/hexformat.rst +++ b/docs/devguide/hexformat.rst @@ -22,8 +22,8 @@ The general memory layout used is: addresses of the data stored progress in incremental order. If there is an address jump backwards DAPLink will fail to flash the file. -UICR format ------------ +UICR format (micro:bit V1) +--------------------------- The User Information Configuration Registers (UICR) is a region of Non-Volatile Memory available to store user-specific settings. @@ -42,9 +42,62 @@ the UICR customer[16] register: - ``0x100010d4``: 4-byte integer with the address in the firmware of the version string - ``0x100010d8``: 4-byte integer with value ``0x00000000`` +Layout table (micro:bit V2) +--------------------------- + +A flash layout table is appended to the the hex file when building MicroPython +for a micro:bit V2. + +The layout table is a sequence of 16-byte entries. The last entry contains the +header (including magic numbers) and is aligned to the end of a page such that +the final byte of the layout table is the final byte of the page it resides in. +This is so it can be quickly and easily searched for. + +The layout table has the following format. All integer values are unsigned and +store little endian. + +:: + + 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e + + ID HT REG_PAGE REG_LEN HASH_DATA + (additional regions) + ... + MAGIC1 VERSION TABLE_LEN NUM_REG PSIZE_LOG2 MAGIC2 + + The values are: + + ID - 1 byte - region id for this entry, defined by the region + HT - 1 byte - hash type of the region hash data + REG_PAGE - 2 bytes - starting page number of the region + REG_LEN - 4 bytes - length in bytes of the region + HASH_DATA - 8 bytes - data for the hash of this region + HT=0: hash data is empty + HT=1: hash data contains 8 bytes of verbatim data + HT=2: hash data contains a 4-byte pointer to a string + + MAGIC1 - 4 bytes - 0x597F30FE + VERSION - 2 bytes - table version (currently 1) + TABLE_LEN - 2 bytes - length in bytes of the table excluding this header row + NUM_REG - 2 bytes - number of regions + PSIZE_LOG2 - 2 bytes - native page size of the flash, log-2 + MAGIC2 - 4 bytes - 0xC1B1D79D + + +This layout table is used to communicate the version of MicroPython and the +current memory layout to a Bluetooth client and enable `partial flashing `_ +(only updating the Python script, and keeping the existing version of +MicroPython in flash). + Steps to create the firmware.hex file ------------------------------------- +micro:bit V1 +============ + +This applies to MicroPython for the micro:bit V1, the source of which can be +found here: `bbcmicrobit/micropython `_. + The yotta 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. @@ -59,6 +112,33 @@ Running the ``make all`` command executes the following steps: - The user can optionally append a script using ``tools/makecombinedhex.py`` (or other tools) +micro:bit V2 +============ + +This applies to MicroPython for the micro:bit V2, the source of which can be +found here: `microbit-foundation/micropython-microbit-v2 `_. + +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. + Including a user script ----------------------- @@ -73,10 +153,10 @@ add the filesystem to HEX files for MicroPython V1 & V2, and then combine both into a `Universal HEX `_ file to ensure compatibility with both hardware variants. -Appended script format (Deprecated) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Appended script format (Deprecated) V1 +====================================== -This method of appending the script to the end of MicroPython +This method of appending the script to the end of MicroPython for micro:bit V1 is no longer used. Python files are now stored in the `filesystem <../filesystem.html>`_ and ``main.py`` is the program entry point.