Skip to content

Commit

Permalink
docs: Update Memory layout, Partial Flashing, Building for V2, BLE (b…
Browse files Browse the repository at this point in the history
…bcmicrobit#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 <[email protected]>
  • Loading branch information
microbit-sam and microbit-carlos committed Apr 12, 2022
1 parent ef98951 commit e445fa2
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 17 deletions.
17 changes: 16 additions & 1 deletion docs/ble.rst
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
134 changes: 118 additions & 16 deletions docs/devguide/hexformat.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,20 +21,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.

Appended script format
----------------------

MicroPython checks the first 2 bytes at address ``0x0003e000`` for a magic
string to indicate if there is an appended script. If the magic string is
found, it will automatically execute the Python code stored there, unless there
is a main.py file stored in the MicroPython filesystem.

- ``0x0003e000``: 2 bytes "MP"
- ``0x0003e002``: 2 bytes, little endian integer for the length (in bytes) of the appended script (not counting this 4 byte header)
- ``0x0003e004``: Script stored as bytes, for MicroPython to decode using utf-8.

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.
Expand All @@ -53,17 +41,131 @@ 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 <https://github.com/microbit-sam/codal-microbit-v2/blob/initial-docs-pf-and-memory-map/docs/bluetooth/MicroBitPartialFlashing.md>`_
(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 <https://github.com/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.

Running the ``make all`` command executes the following steps:

- The ``tools/makeversionhdr.py`` script creates the ``microbitversion.h`` file with macros containing build information
- The ``tools/makeversionhdr.py`` script creates the ``microbitversion.h`` file
with macros containing build information
- Yotta builds the source and creates a bare hex file with just the firmware
- The ``tools/adduicr.py`` script adds the UICR to the bare hex
- The final hex file is placed in ``build/firmware.hex``
- The user can optionally append a script using ``tools/makecombinedhex.py`` (or other tools)
- 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 <https://github.com/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
-----------------------

This section applies to both micro:bit V1 and V2.

User scripts are stored in the MicroPython filesystem and if a ``main.py`` script
exists it is run when MicroPython starts. Additional Python scripts can also be
included and executed from the ``main.py`` file, or the REPL.

The `Python Editor <https://python.microbit.org>`_ uses `microbit-fs <https://github.com/microbit-foundation/microbit-fs>`_
to create the filesystem and include it in the HEX file. The Python Editor must
add the filesystem to HEX files for MicroPython V1 & V2, and then combine both
into a `Universal HEX <https://tech.microbit.org/software/hex-format/#universal-hex-files>`_
file to ensure compatibility with both hardware variants.

Appended script format (Deprecated)
-----------------------------------

This method of appending the script to the end of MicroPython was originally
used for micro:bit V1, but is no longer used. Python files are now stored in the
`filesystem <../filesystem.html>`_ and ``main.py`` is the program entry point.

MicroPython checks the first 2 bytes at address ``0x0003e000`` for a magic
string to indicate if there is an appended script. If the magic string is
found, it will automatically execute the Python code stored there, unless there
is a ``main.py`` file stored in the MicroPython filesystem.

- ``0x0003e000``: 2 bytes "MP"
- ``0x0003e002``: 2 bytes, little endian integer for the length (in bytes) of
the appended script (not counting this 4 byte header)
- ``0x0003e004``: Script stored as bytes, for MicroPython to decode using utf-8.
2 changes: 2 additions & 0 deletions docs/filesystem.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _filesystem:

Local Persistent File System
****************************

Expand Down

0 comments on commit e445fa2

Please sign in to comment.