MicroPython Hex ファイル¶

MicroPythonをビルドすると、コンパイラは MicroPython ファームウェアを含む Intel Hex ファイルを生成します。このファイルにデータを追加して、MicroPython バージョン情報、または起動時に実行する Python コードを含められます。

一般的なメモリレイアウトは次のとおりです:

0x00000000: MicroPython ファームウェアの先頭 - 最大 248 KB
0x0003e000: 追加スクリプトの先頭(オプション) - 最大 8 KB
0x100010c0: UICR カスタマー[16]レジスター, MicroPython 情報の先頭 - 28バイト

注釈

Intel Hex ファイルにデータを追加したり変更したりする場合は、データのアドレスが増分順に格納されていることを確認してください。後方にアドレスジャンプがある場合、DAPLink はファイルをフラッシュできません。

UICR フォーマット(micro:bit V1)¶

ユーザー情報構成レジスター (UICR: User Information Configuration Registers)は、不揮発性メモリーの領域で、ユーザー固有の設定を保管できます。最初の128バイトは予約されていますが、残りの128バイトを使用して任意のデータを格納できます。

MicroPython は、UICR カスタマー[16]レジスターから開始して、リトルエンディアンで次の情報を格納します。

0x100010c0: 4バイト整数のマジック値 0x17eeb07c
0x100010c4: 4バイト整数値 0xffffffff
0x100010c8: 4バイト整数値 0x0000000a (フラッシュページサイズ 1024 の２進対数)
0x100010ca: 2バイト整数値 0x0000 (ファームウェアの開始ページ)
0x100010cc: ファームウェアのページ数の2バイト整数値
0x100010d0: 4バイト整数値 0xffffffff
0x100010d4: ファームウェア内のバージョン文字列のあるアドレスを示す4バイト整数値
0x100010d8: 4バイト整数値 0x00000000

レイアウトテーブル(micro:bit V2)¶

micro:bit V2用の MicroPython をビルドすると、転送レイアウトテーブルが hex ファイルに追加されます。

レイアウトテーブルは16バイトのエントリのシーケンスです。最後のエントリにはヘッダ(マジックナンバーを含む)が含まれており、レイアウトテーブルの最終バイトがそのページの最終バイトになるようにページの最後に配置されています。これは、素早く簡単に検索できるようにするためです。

レイアウトテーブルの形式は次のとおりです。整数値はすべて符号なしで、リトルエンディアンで格納します。

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

このレイアウトテーブルは、MicroPython のバージョンと現在のメモリレイアウトを Bluetooth クライアントに通信し、部分転送を有効にするために使われます(転送時に Python スクリプトの更新のみを行い、MicroPython 既存のバージョンのままにします)。

firmware.hex ファイルを作成する手順¶

micro:bit V1¶

ここでは micro:bit V1 の MicroPython について説明します。micro:bit V1 用のソースは次のところにあります: bbcmicrobit/micropython

MicroPython のビルドには yotta ツールを使います。ビルドの前には準備として Makefile で追加のファイルを生成しなければなりません。ビルドの後には付加データを hex ファイルに追加します。

make all コマンドを実行すると、以下の順序で処理されます:

tools/makeversionhdr.py スクリプトが microbitversion.h ファイルを作成します。このファイルはビルド情報をもったマクロを定義しています。
yotta がソースをビルドし、ファームウェアだけの生の hex ファイルを作成します
tools/adduicr.py スクリプトが生の hex ファイルに UICR を追加します
完成した hex ファイルを build/firmware.hex に置きます
ユーザーは、オプションで tools/makecombinedhex.py (または他のツール)を使ってスクリプトを追加できます

micro:bit V2¶

ここでは micro:bit V2 の MicroPython について説明します。micro:bit V2 用のソースは次のところにあります: microbit-foundation/micropython-microbit-v2

これは MicroPython を micro:bit に移植したもので、ターゲットプラットフォームとして CODAL を使っています。

make コマンドを実行すると、以下の順序で処理されます:

build 出力ディレクトリを作成し、cmake を実行し、codal ライブラリが存在することを(cmake で)確認します。
(src/codal_port/ にあるソースから) libmicropython.a 、(src/codal_app/ にあるソースから) CODAL アプリの両方をビルドします。
addlayouttable.py を実行して、レイアウトテーブルを .hex ファイルに追加します
src/ ディレクトリに microbit-micropython ファームウェアである MICROBIT.hex を作成します。これは micro:bit にコピーできます。

ユーザースクリプトのインクルード¶

ユーザースクリプトは MicroPython ファイルシステムに保存され、main.py スクリプトが存在すれば MicroPython の起動時に実行されます。追加の Python スクリプトを main.py ファイルや REPL からインクルードして実行することもできます。

Pythonエディタは microbit-fs を使ってファイルシステムを作成し、それをHEXファイルにインクルードします。Python エディタは MicroPython V1 と V2 の HEX ファイルにファイルシステムを追加し、両方のハードウェアの互換性を確保するために両方を Universal HEX ファイルに結合しなければなりません。

Appended script format (Deprecated) V1¶

スクリプトを MicroPython の最後に追加する方法は micro:bit V1 で使われていましたが、現在では使われていません。Python ファイルはファイルシステムに格納されるようになり、 main.py がプログラムの入り口になります。

MicroPython はアドレス 0x0003e000 の先頭2バイトをチェックします。これは、追加スクリプトがあるかを示すマジック文字列です。マジック文字列が見つかった場合、MicroPython ファイルシステムに main.py ファイルが格納されていない限り、追加されている Python コードを自動的に実行します。

0x0003e000: 2 バイト "MP"
0x0003e002: 2バイト、追加されたスクリプトの長さ(バイト単位)のリトルエンディアン整数(この長さにヘッダ4バイト分は含みません)
0x0003e004: バイト列として格納したスクリプト。MicroPython で使う際には utf-8 でデコードします。