Blog:
Toradex TEZI使用マニュアル BSP5用
本マニュアルについて
本マニュアルはトラデックスのCPUモジュールにOSイメージを書き込むために使用するTEZI(Toradex Easy Installer)の使用方 法について記述しています。
本マニュアルに記載されていないTEZIに関する情報も多々あります。詳しくはToradexのWEBサイトをご参照ください。
参考:
- https://developer.toradex.com/easy-installer
- https://developer-archives.toradex.com/knowledge-base/load-toradex-easy-installer#Download_Toradex_Easy_Installer
本マニュアルのPDFダウンロード
1.実行環境
本マニュアルの実行環境は下記です。
OS: Windows 10 21H2
TEZI: 5.7.1+build.13
CPUモジュール:Verdin iMX8M Plus Quad 4GB Wi-Fi / Bluetooth IT V1.1A
キャリアボード:キャリアボード:Verdin開発ボードRev 1.1C + アクセサリーキット
BSP: Linux Reference Minimal 5 LTS Downstream SoC vendor based kernel Wayland/XWayland graphics back-end supported but not included 5.7.0+build.20
(LTSとついていますがVerdin-iMX8M Plusに対してはLTS版ではありません。)
本マニュアルとは異なるモジュールや評価ボード以外のキャリアボードを使われても大雑把には同じ操作となります。
2.注意点
TEZIはパスワードなしでシリアルコンソールを使用できますまたセキュリティ皆無のVNCが入っていてます。本番環境では安全 なネットワークに接続してください。
TEZIは多くのオープンソースで作成されています。TEZIファイルシステムの/usr/share/common-licenses/配下にあるライセンス規約をご参照ください。 /usr/share/common-licenses/license.manifestにライセンスの概要があります。
開発環境(パソコン)と実行環境(モジュール)の違いをわかりやすくするためにコマンドの表記の前に下記をつけています。
開発環境(パソコン)上で入力するコマンド:[Ubuntu]$
実行環境(モジュール)上で入力するコマンド(Linux) :[Module]#
実行環境(モジュール)上で入力するコマンド(U-Boot):[U-Boot]#
実行環境(モジュール)上で入力するコマンド(TEZI):[Tezi]#
TEZIについて
TEZI(Toradex Easy Installer)はToradexのSOMの内部ROMにOSイメージを書き込むためのツールです。TEZIはLinux + アプリケーションで出来ています。SOM上で動作するものですのでパソコンなどがなくてもモジュール単体で書き込むことが可能です。SDやUSBメモリなどに格納したOSイメージや任意のサーバーからダウンロードしたものを書き込むこともできます。
TEZIが起動するとGUIが立ち上がり数クリックするだけで書き込みできるため誰でも利用することができます。
設定次第では電源を入れるだけで書き込みを自動で行うことも可能です。
SOMは出荷時にTEZIが書き込まれます。そのため量産工程で出荷時にインストールされているTEZIを利用して最終製品用のOSイメージを書き込みを行うこともできます。
TEZIの起動
TEZIを起動するには3つの方法があります。
- TEZIがインストールされているモジュールを起動する
購入直後はTEZIがインストールされているため開発ボードに電源を入れるだけでTEZIが起動します。
ただしTEZIでOSイメージを書き込むと内部のTEZIは消えてしまいますのでそれ以降はTEZIは起動せず書き込んだものが起動します。主にモジュール購入直後の評価開始のタイミングや量産時の初期書き込みに利用します。 - リカバリーモードで起動
リカバリーモードは通常起動とは別に内部ROMを使用せずに直接外部からRAMへプログラムを展開して起動するモードです。
主にブートローダーが潰れるなどモジュールが復帰できなくなった時に利用します。 - 外部メディアなどからの起動
通常はモジュール内蔵のeMMCに格納されているLinuxを起動しますがSDカードやUSBメモリー、Ethernetなど別の領域に格納されたTEZIを起動させることも可能です。
開発時に何度も書き直す場合にはこの方法が一番使いやすいです。
Toradexから公式にサポートしていなくてフラッシュされたU-Bootに依存されています。
起動イメージ
3つの起動方法の起動イメージです。
リカバリーモードは内部ROMを使わずにパソコンから直接RAMへBootloaderやOSを展開します。
内部ROMの状態にかかわらず常に同じ状態で起動できます。
外部メディアから起動する場合は最初に内部ROMのBootloaderが起動して外部メディアのOS起動するためそれぞれ互換性がない場合うまく動作しません。
TEZIとOSイメージの入手
OSを書き込むにはTEZIとOSイメージ(TEZIフォーマットタイプ)が必要です。
- TEZIの入手
TEZIは下記からダウンロードできます。対象のモジュールのファイルをダウンロードしてください。
https://developer-archives.toradex.com/knowledge-base/load-toradex-easy-installer#Download_Toradex_Easy_Installer - OSイメージの入手
下記にデモ用のOSイメージがあります。書き込みたいOSイメージをSDカードなどに格納してください。
https://developer.toradex.com/knowledge-base/toradex-easy-installer-os-and-demo-images
OSイメージをToradexのサーバーから書き込む場合はダウンロード不要です。書き込み時に自動でダウンロードされます。
自作カスタムOSを書き込む場合は作成したOSイメージを使用してください。
リカバリーモードでTEZIを起動する方法
OSイメージ解凍後をFAT32(もしくはEXT4)フォーマットのSDカードやUSBメモリに格納してください。
ルートディレクトリに任意の名前でディレクトリを作成してその中に格納してください。ディレクトリを分けて複数のOSイメージを格納することもできます。例えばSDカードがFドライブであればF:¥v1、F:¥v2配下など。
ToradexのサーバーからOSイメージを書き込む場合はSDカードは準備不要です。
ハードウェアの準備
以下を行います。
- X1にモジュールを挿します。ヒートシンクも装着します。
- X37にHDMIケーブルを指してディスプレイと繋ぎます。TightVNC Viewerなどで代用できます。
- X53にUSBマウスを挿入します。
- X34にUSBケーブルを差し込みパソコンと接続します。
- SDカードでアップデートする場合はX55にSDカードを挿入します。
アップデートをインターネット越しで行う場合はX25にEthernetケーブルを挿入します。
インターネットに接続できる環境が必要です。モジュールはDHCPで接続を行いますのでDHCPサーバーが必要です。 - X58にACアダプタを接続します。
リカバリーモードで起動
Recovery Modeボタン(SW3)を押しながら電源ボタン(SW2)を押してください。
電源ボタンを離した後少しおいてRecovery Modeボタンを離してください。リカバリーモードで起動します。
Verdin-iMX8M Plus以外のモジュールのリカバリーモードへの遷移方法は下記をご参照ください。
https://developer.toradex.com/knowledge-base/imx-recovery-mode#Enter_Recovery_Mode
リカバリーモードで起動するとブートローダーが動作しないためteratermなどに起動ログが出力されません。
リカバリモードに入ったかどうかを確認する場合はWindows PCのデバイスマネージャを見ます。
下記のようなベンダーID,プロダクトIDのHID準拠デバイスが追加されています。
リカバリーモードで起動したらTEZIを起動します。ダウンロードしたTEZIの中にあるrecovery-windows.batを実行します。
下記のようなログが出るとTEZIの起動成功です。
ディスプレイに下記のような画面が表示されます。SDカードに入れたOSイメージがリストされています。
複数入れている場合は複数表示されます。
Ethernetでアップデートする場合は下記のようにいくつかの項目がリストされます。
この項目はサーバーへ接続する時期により内容が変わります。
リストされている項目をダブルクリックすると下記のような確認がでてきます。Yesをクリックするとインストールが始まります。
ライセンス規約が表示されます。同意できる場合は「I Accept」をクリックしてください。
ライセンス規約に同意できない場合はソフトウェアを使用することはできません。
インストールが終了すると下記のような選択が表示されます。Rebootをクリックして書き込んだOSが起動するかどうかを確認します。
リカバリーモードで起動
TEZIを解凍してFAT32(もしくはEXT4)フォーマットのSDカードやUSBメモリのルートディレクトリに格納してください。
OSイメージも同様に解凍してリカバーモード時同様に任意のディレクトリに格納してください。
ToradexのサーバーからOSイメージを書き込む場合はOSイメージの準備は不要です。
TEZIとOSイメージは各々を別のメディアに格納することもできます。
ルートディレクトリにあるboot-tezi.scrというファイルをboot.scrにリネームします。
boot.scrはU-Boot起動時に起動スクリプトが監視するファイルです。
インストールが終了すると下記のような選択が表示されます。Rebootをクリックして書き込んだOSが起動するかどうかを確認します。
BSP5系では起動処理が内部eMMCや外部メディアなど起動する場所によらずすべて同じ処理となっています。
U-Bootの起動スクリプトはSDカード、モジュール上のeMMC、USBメモリ、Ethernetという優先順位で各々のルートディレクトリのboot.scrを探しboot.scrを実行することで起動します。
この優先順位はU-Bootの設定のboot_targetsという設定で決まっています。
下記コマンドで確認できます。
[U-Boot]$ printenv boot_targets boot_targets=mmc1 mmc2 usb0 dhcp
この順序は設定を変更することにより変えることができます。(左から順番に実行)
通常eMMCにはLinuxを書き込みます。SDカードにはTEZIを入れておきます。
優先順位を変更することで何を起動するかを切り替えることができます。
U-Bootのfatlsコマンドで中身を確認できます。
[U-Boot]$ fatls mmc 1:1
[U-Boot]$ fatls mmc 2:1
mmc1には本マニュアル通りのTEZIとインストールするOSイメージが格納されています。
boot.scrも含まれているためmmc1が優先されてmmc1から起動が行われます。
USBを使う場合はUSBの優先するようにboot_targetsを修正してください。修正方法は後述。
ハードウェアの準備
- X1にモジュールを挿します。ヒートシンクも装着します。
- X37にHDMIケーブルを指してディスプレイと繋ぎます。TightVNC Viewerなどで代用できます。
- X53にUSBマウスを挿入します。
- X66にUSBケーブルを差し込みパソコンと接続します。
- SDカードでアップデートする場合はX55にSDカードを挿入します。
アップデートをインターネット越しで行う場合はX25にEthernetケーブルを挿入します。
インターネットに接続できる環境が必要です。モジュールはDHCPで接続を行いますのでDHCPサーバーが必要です。 - X58にACアダプタを接続します。
シリアル通信ソフトの準備
モジュールとシリアル通信を行います。本マニュアルではTeraTermを使います。
TeraTermを下記、設定でCOMポートを開きます。
Verdin評価ボードと接続すると2つのCOMポート番号が追加されます。
そのうち大きな番号のCOMポート番号に接続してください。
例えば10,11と追加された場合は11を指定します。
起動
SDカードから起動する場合は電源ボタン(SW2)を押し電源ONすると自動的にSDカードから起動します。
SDカード以外から起動する場合は電源ON後、下記のように「Hit any key to stop autoboot:」とTeratermに出力されます。
この時に何かしらのキーを入力するとブートローダー(U-Boot)で止まりますが入力しないとU-BootがLinuxを起動させます。(書き込まれている場合) ブートローダーで止めるためにスペースキーなどを入力します。
例えばUSBを使う場合はUSBの優先するようにboot_targetsを修正してからresetコマンドで再起動します。
mmc2より左にusb0があれば優先されます。
U-Boot]$ setenv boot_targets mmc1 usb0 mmc2 dhcp [U-Boot]$ saveenv [U-Boot]$ reset
設定にかかわらずブートメディアを指定して起動することもできます。
bootcmd_mmc1やbootcmd_usb0など起動メディアを指定する起動コマンドが定義されています。
runコマンドでこの定義を実行することで指定した場所から起動することができます。
[U-Boot]$ run bootcmd_usb0
どのような定義が存在するかはprintenvコマンドで確認できます。
TEZI起動後はリカバリーモード時と同様の操作でOSイメージの書き込みを行ってください。
自動インストール機能
OSイメージの中にimage.jsonというファイルがあります。このファイルはTEZIの動作を定義するものです。
この中にautoinstallという設定があります。この設定をtrueに変更すると自動でインストールするようになります。TEZIが起動した後リムーバルメディアをスキャンしてautoinstallがtrueがあればそのままインストールされます。この設定を使用すると量産工程などでGUIなどを操作することなく電源ONからインストールまでが自動で行われます。複数OSイメージがある場合はどれがインストールされるかは保証されていないためひとつだけtrueに設定してください。
TEZIの自動アップデート機能
TEZIの設定ファイルimage.jsonにはフォーマットのバージョンがありconfig_formatで指定されています。
TEZIは新しい機能が追加されていき、場合によっては新しい設定項目が追加されフォーマットのバージョンが上がっていきます。
古いバージョンのTEZIを使った場合、新しいフォーマットのimage.jsonを読み込むことができません。
例えば在庫として長く置かれていたモジュールにはインストールされているTEZIのバージョンが古く、製品製造時に書き込むOSイメージのconfig_formatで指定されているバージョンに対応していない場合書き込むことができません。このような問題を解決するためにTEZIの自動アップデート機能があります。OSイメージを書き込む前に一旦TEZIのバージョンアップをすることで問題に対処します。
TEZIのimage.json(OSイメージにもimage.jsonがあるため注意してください。)にはisinstallerという設定がありtrueになっています。isinstallerがtrueかつautoinstallがtrueの場合、OSイメージよりも優先してTEZIの書き込みが行われます。実行中のTEZIのバージョン(versionの設定)と比較してリムーバルメディアにあるTEZIのバージョンが新しければ最初にTEZIをインストールして再起動が行われます。再起動後は新しいTEZIが立ち上がりバージョンが同じになるため再度TEZIがインストールされることはありません。次にOSイメージのインストールが行われます。
スクリプト実行機能
image.jsonに定義されているprepare_script、wrapup_script、error_scriptにシェルファイルを設定することでそれぞれインストール前、インストール後、エラー発生時に自動でスクリプトを実行することが可能です。
例えばwrapup.shにrebootコマンドを記述することでOS書き込み後自動でrebootします。ただしrebootしてもそのままほっておくと再度SDからの起動が優先されてTEZIが起動してしまいます。自動的に書き込んだOSがeMMCから起動するようにするためにはSDカードにあるboot.scrをリネームすることで防止できます。
例えば下記のような記述をするとOSイメージインストール後boot.scrをリネームして再起動します。TEZIはリムーバルメディアを読み込み専用でマウントします。そのままではboot.scrをリネームできないため一度、書き込み可能でマウントし直して最後に読み込み専用に戻しています。
#!/bin/sh MOUNT_POINT=/run/media/src mount -o remount,rw $MOUNT_POINT mv $MOUNT_POINT/boot.scr $MOUNT_POINT/boot-tezi.scr sync mount -o remount,ro $MOUNT_POINT reboot -f exit 0
スクリプト実行機能
prepare_script、wrapup_script、error_scriptで実行されるシェルファイルにはパラメータが付与されて起動します。$1,$2,$3,$4にそれぞれプロダクトID、モジュールリビジョン、シリアルナンバー、イメージのディレクトリが入っています。
例えば下記のような記述をするとOSイメージインストール後SDカードにログを出力して再起動しますTEZIが内部でどのようなことをしているかは/var/volatile/tezi.logにログが出力されています。
下記シェルではtezi.logも保存しています。
#!/bin/sh MOUNT_POINT=/run/media/src mount -o remount,rw $MOUNT_POINT LOG_DIR=$MOUNT_POINT/log/$3 mkdir -p $LOG_DIR echo "PRODUCT_ID:$1" >> $LOG_DIR/log echo "MODULE_REV:$2" >> $LOG_DIR/log echo "SERIAL:$3" >> $LOG_DIR/log echo "IMAGE_DIR:$4" >> $LOG_DIR/log cp -prf /var/volatile/tezi.log $LOG_DIR sync mount -o remount,ro $MOUNT_POINT reboot -f exit 0
U-Boot環境変数設定ファイル
image.jsonのu_boot_envに設定されたファイル(デフォルトはu-boot-initial-env-sd)にU-Bootの環境変数の設定をします。U-Bootのヘッダーを参照して出力されるためU-Bootのソースコードを修正しても修正した箇所がこのファイルにも適用されています。U-Bootのソースコードに設定された値はenv defaultで初期化した時に設定される値です。個別で設定を追加したい場合はこのファイルに追加するだけで設定されますが基本的にはU-Bootのソースコードを修正することで対応する方をお勧めします。
フラッシュ上に有効なU-Boot環境変数がすでにある場合、新しい変数は追加され、既存の変数は上書きされ、空の変数は削除され、他の変数は削除されます。
書き込み時間の短縮
書き込み時間はOSイメージの大きさに依存します。できるだけOSイメージから不要な機能を削除することでOSイメージのサイズを小さくすることで書き込み時間を短くすることができます。
OSイメージを出力するとrootfsやbootfsはLZMA2アルゴリズム(xzファイル)で出力されます。SDカードやUSBメモリなど高速に読み込みできるところにある場合、読み込速度に対して解凍の方が時間がかかるため遅くなります。(インターネット越しでダウンロードする場合は解凍時間に比べてダウンロード速度のほうが遅いため圧縮は効果的です。)
tar.xzを解凍してtarにした状態でインストールすると大幅に早くなります。この場合image.jsonのファイル名をtar.xzからtarに修正してください。xzの解凍は下記のコマンドで行います。
sudo xz -d ./Reference-Minimal-Image-verdin-imx8mp.tar.xz
uncompressed_sizeは書き込み中のインジケータの分母に使われます。正確な値ではなく目安として使われます。
気になる場合は微調整してください。
インストール中の背景の変更
OSイメージのファイル一式の中にmarketing.tarがあります。このファイルはインストール中の背景画像が入っています。
この中のファイルを変更することでインストール中の背景画像を変更することができます。
tar xf marketing.tar
slides_vgaというディレクトリに下記が入っています。これらの画像が順番に表示されていきます。
Embedded-Linux-Splash-Screen_V3_01.png
Embedded-Linux-Splash-Screen_V3_02.png
Embedded-Linux-Splash-Screen_V3_03.png
Embedded-Linux-Splash-Screen_V3_04.png
Embedded-Linux-Splash-Screen_V3_05.png
使用したい画像をpng形式で格納してください。
tar cf ./marketing.tar ./slides_vga/
インストール中の背景が変わっていることが確認できます。
桐川篤史・岡本無線電機
ガルシアアルバロ・Toradex(トラデックス)