Skip to content

Commit 8a7a594

Browse files
microbit-sammicrobit-carlos
microbit-sam
and
microbit-carlos
committed
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 <carlos@microbit.org>
1 parent 88eb789 commit 8a7a594

3 files changed

Lines changed: 136 additions & 17 deletions

File tree

‎docs/ble.rst‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
Bluetooth
22
*********
33

4+
micro:bit V1
5+
============
6+
47
While the BBC micro:bit has hardware capable of allowing the device to work as
58
a Bluetooth Low Energy (BLE) device, it only has 16k of RAM. The BLE stack
69
alone takes up 12k RAM which means there's not enough memory for MicroPython
7-
to support Bluetooth.
10+
to support Bluetooth on a micro:bit V1.
811

912
.. note::
1013
MicroPython uses the radio hardware with the :mod:`radio` module. This
@@ -13,3 +16,15 @@ to support Bluetooth.
1316

1417
Furthermore, the protocol used in the :mod:`radio` module is a lot simpler
1518
than BLE, making it far easier to use in an educational context.
19+
20+
micro:bit V2
21+
============
22+
23+
The nRF52833 used by the micro:bit V2 has 128k of RAM, allowing Micropython to make
24+
use of the BLE stack. Currently the only implemented feature is BLE flashing, allowing
25+
a user to update the firmware on the micro:bit over Bluetooth.
26+
27+
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
28+
beta. The Nordic DFU service updates everything in flash and will take a (relatively) long
29+
time to complete, whereas the partial flashing service only updates the filesystem containing
30+
the user scripts.

‎docs/devguide/hexformat.rst‎

Lines changed: 118 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -21,20 +21,8 @@ The general memory layout used is:
2121
addresses of the data stored progress in incremental order.
2222
If there is an address jump backwards DAPLink will fail to flash the file.
2323

24-
Appended script format
25-
----------------------
26-
27-
MicroPython checks the first 2 bytes at address ``0x0003e000`` for a magic
28-
string to indicate if there is an appended script. If the magic string is
29-
found, it will automatically execute the Python code stored there, unless there
30-
is a main.py file stored in the MicroPython filesystem.
31-
32-
- ``0x0003e000``: 2 bytes "MP"
33-
- ``0x0003e002``: 2 bytes, little endian integer for the length (in bytes) of the appended script (not counting this 4 byte header)
34-
- ``0x0003e004``: Script stored as bytes, for MicroPython to decode using utf-8.
35-
36-
UICR format
37-
-----------
24+
UICR format (micro:bit V1)
25+
---------------------------
3826

3927
The User Information Configuration Registers (UICR) is a region of Non-Volatile
4028
Memory available to store user-specific settings.
@@ -53,17 +41,131 @@ the UICR customer[16] register:
5341
- ``0x100010d4``: 4-byte integer with the address in the firmware of the version string
5442
- ``0x100010d8``: 4-byte integer with value ``0x00000000``
5543

44+
Layout table (micro:bit V2)
45+
---------------------------
46+
47+
A flash layout table is appended to the the hex file when building MicroPython
48+
for a micro:bit V2.
49+
50+
The layout table is a sequence of 16-byte entries. The last entry contains the
51+
header (including magic numbers) and is aligned to the end of a page such that
52+
the final byte of the layout table is the final byte of the page it resides in.
53+
This is so it can be quickly and easily searched for.
54+
55+
The layout table has the following format. All integer values are unsigned and
56+
store little endian.
57+
58+
::
59+
60+
0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e
61+
62+
ID HT REG_PAGE REG_LEN HASH_DATA
63+
(additional regions)
64+
...
65+
MAGIC1 VERSION TABLE_LEN NUM_REG PSIZE_LOG2 MAGIC2
66+
67+
The values are:
68+
69+
ID - 1 byte - region id for this entry, defined by the region
70+
HT - 1 byte - hash type of the region hash data
71+
REG_PAGE - 2 bytes - starting page number of the region
72+
REG_LEN - 4 bytes - length in bytes of the region
73+
HASH_DATA - 8 bytes - data for the hash of this region
74+
HT=0: hash data is empty
75+
HT=1: hash data contains 8 bytes of verbatim data
76+
HT=2: hash data contains a 4-byte pointer to a string
77+
78+
MAGIC1 - 4 bytes - 0x597F30FE
79+
VERSION - 2 bytes - table version (currently 1)
80+
TABLE_LEN - 2 bytes - length in bytes of the table excluding this header row
81+
NUM_REG - 2 bytes - number of regions
82+
PSIZE_LOG2 - 2 bytes - native page size of the flash, log-2
83+
MAGIC2 - 4 bytes - 0xC1B1D79D
84+
85+
86+
This layout table is used to communicate the version of MicroPython and the
87+
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>`_
88+
(only updating the Python script, and keeping the existing version of
89+
MicroPython in flash).
90+
5691
Steps to create the firmware.hex file
5792
-------------------------------------
5893

94+
micro:bit V1
95+
============
96+
97+
This applies to MicroPython for the micro:bit V1, the source of which can be
98+
found here: `bbcmicrobit/micropython <https://github.com/bbcmicrobit/micropython>`_.
99+
59100
The yotta tool is used to build MicroPython, but before that takes place
60101
additional files have to be generated by the Makefile in preparation for the
61102
build, and additional data is added to the hex file after.
62103

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

65-
- The ``tools/makeversionhdr.py`` script creates the ``microbitversion.h`` file with macros containing build information
106+
- The ``tools/makeversionhdr.py`` script creates the ``microbitversion.h`` file
107+
with macros containing build information
66108
- Yotta builds the source and creates a bare hex file with just the firmware
67109
- The ``tools/adduicr.py`` script adds the UICR to the bare hex
68110
- The final hex file is placed in ``build/firmware.hex``
69-
- The user can optionally append a script using ``tools/makecombinedhex.py`` (or other tools)
111+
- The user can optionally append a script using ``tools/makecombinedhex.py``
112+
(or other tools)
113+
114+
micro:bit V2
115+
============
116+
117+
This applies to MicroPython for the micro:bit V2, the source of which can be
118+
found here: `microbit-foundation/micropython-microbit-v2 <https://github.com/microbit-foundation/micropython-microbit-v2>`_.
119+
120+
This is a port of MicroPython to the micro:bit which uses CODAL as the
121+
underlying target platform.
122+
123+
After cloning this repository update the submodules::
124+
125+
$ git submodule update --init
126+
127+
Then build the MicroPython cross-compiler::
128+
129+
$ make -C lib/micropython/mpy-cross
130+
131+
After setting up, go to the src/ directory and build::
132+
133+
$ cd src
134+
135+
$ make
136+
137+
That will build both ``libmicropython.a`` (from source in ``src/codal_port/``) and the
138+
CODAL app (from source in ``src/codal_app/``). The resulting firmware will be
139+
``MICROBIT.hex`` in the ``src/`` directory which can be copied to the micro:bit.
140+
141+
Including a user script
142+
-----------------------
143+
144+
This section applies to both micro:bit V1 and V2.
145+
146+
User scripts are stored in the MicroPython filesystem and if a ``main.py`` script
147+
exists it is run when MicroPython starts. Additional Python scripts can also be
148+
included and executed from the ``main.py`` file, or the REPL.
149+
150+
The `Python Editor <https://python.microbit.org>`_ uses `microbit-fs <https://github.com/microbit-foundation/microbit-fs>`_
151+
to create the filesystem and include it in the HEX file. The Python Editor must
152+
add the filesystem to HEX files for MicroPython V1 & V2, and then combine both
153+
into a `Universal HEX <https://tech.microbit.org/software/hex-format/#universal-hex-files>`_
154+
file to ensure compatibility with both hardware variants.
155+
156+
Appended script format (Deprecated)
157+
-----------------------------------
158+
159+
This method of appending the script to the end of MicroPython was originally
160+
used for micro:bit V1, but is no longer used. Python files are now stored in the
161+
`filesystem <../filesystem.html>`_ and ``main.py`` is the program entry point.
162+
163+
MicroPython checks the first 2 bytes at address ``0x0003e000`` for a magic
164+
string to indicate if there is an appended script. If the magic string is
165+
found, it will automatically execute the Python code stored there, unless there
166+
is a ``main.py`` file stored in the MicroPython filesystem.
167+
168+
- ``0x0003e000``: 2 bytes "MP"
169+
- ``0x0003e002``: 2 bytes, little endian integer for the length (in bytes) of
170+
the appended script (not counting this 4 byte header)
171+
- ``0x0003e004``: Script stored as bytes, for MicroPython to decode using utf-8.

‎docs/filesystem.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _filesystem:
2+
13
Local Persistent File System
24
****************************
35

0 commit comments

Comments
 (0)