この記事は、Magic Leap Advent Calendar 2020 10日目の記事です！

はじめに

新品のMagicLeapがおうちに届いてさあ開発するぞとなった時、
第一の関門としてほぼ全ての開発者の前に立ちはだかるのが、OSアップデートの問題です。

出荷状態では、現行最新のSDK(v24.1/v24.2)を使ったアプリが証明書の仕様上動作せず、
OSアップデートが必須になるのですが、
アップデートができない！困った！という経験をされた方は非常に多いと思います。
自分の場合、業務で大量のMagicLeapを初期設定するタイミングがあり、この問題には相当悩まされました…

この記事では、MagicLeapのOSアップデートで困った時の対処法をお伝えできればと思います。
~~お察しの通り、非常にニッチな記事です。~~

何が問題なのか

MagicLeapのOSアップデートは、基本的にOSの設定画面の中から行います。
歯車アイコンで示される設定画面からSystem > Updateと進むと、
OSのバージョン確認およびアップデートを行う画面が現れます。
ここでCheck for Updateボタンを選択すると、MagicLeapが自動でサーバーに最新OSの問い合わせを行い、
指示に従って進むと最新OSがアップデートされます。

…というのが本来の挙動なのですが、
なぜかサーバーから最新OSの情報が正しく返ってこないことが多く、悩まされることとなります。
OSの情報が正しく返ってこないと、
MagicLeapが現状を最新OSとして認識してしまい、アップデートに進むことができません。

MagicLeap公式によれば、
MagicLeapをインターネットに接続した状態で数十分ほど放置すれば、
正しくOSの情報を取得できるはずとのこと。
数時間待ってもうまくいかない場合は、無理に粘らずに諦めた方がいいようです。

対処法その1 ： OSを手動インストール

LuminOSのソースやビルドは原則として公開されていませんが、
実は、手動で強制的にインストールする方法が用意されています。
基本的に、こちらのドキュメントに従う感じになります。
https://developer.magicleap.com/en-us/learn/guides/developer-flashing-guide-latest
ちなみに、最新でないOSイメージをダウンロードすれば、OSのダウングレードもこの方法でできるようです。

専用ページからOSイメージを落としてzipを解凍する
- アップデートしたいMagicLeap端末のシリアルナンバーが必要。
  シリアルナンバーを調べる方法は、主に以下の3通り
  - The LabのDevice Bridgeの端末情報を見る
  - mldb get-serialno コマンドで調べる
  - MagicLeap端末の後頭部部分のクッションを取り外して中の文字を読む
- OSバージョンがCEとCEでないものに分かれているが、ほとんどの場合非CE
  - CE=Creator Edition、梱包箱が大きかった初期のモデル (外見は全く同じ)
  - 製品の箱を開けた時、
    アクセサリ類がLightPackの左右に分かれて入っていたらCE、片側に固まって入っていたら非CE
1.の段階でリクエストが弾かれる場合は、何度か試したらサクッと諦めて、対処法その2に進みましょう
※↓リクエストが弾かれた時の様子。こうなったらこの方法では無理です
上げたいOSに対応するSDKバージョンを Device Flashing Guide で確認して、
そのSDKバージョンのmldbコマンドの実体と同じディレクトリに、解凍した中身をすべてコピペする
- 普通は MagicLeap > mlsdk > [sdk version] > tools > mldb にあります
- ターミナルでwhich mldbするか、LabのPackage Managerからも調べられます
ターミナルを開いて、さっきの階層にcdする
アップデートしたいMagicLeapをパソコンにUSB接続する

以下のコマンドを一行ずつ打っていく

mldb devices # 接続確認
mldb getprop | grep ml.build.version # バージョン確認
mldb reboot bootloader ## fastbootモードで再起動する

# fastbootモード中はMagicLeap側での画面描画が止まる
fastboot devices # 接続確認/fastbootモード中はmldbからは認識されない

# ここからOSの上書き作業になるので慎重に作業する
fastboot flash gpt flash_nvidia_ml.processed.xml.spi_ufs_64.bin.secure
fastboot flash bootloader bootloader.img.secure
fastboot reboot-bootloader
fastboot flash boot boot.img.secure
fastboot flash system system.img.secure # 処理に数分かかる
fastboot flash vendor vendor.img.secure
fastboot flash wearable wearable.img.secure
fastboot erase userdata # FactoryResetに相当/やらなくてもいいっぽい
fastboot reboot # fastbootモードを抜ける/処理に数分かかる

# そのあとMagicLeapから起動音＼ﾋﾟﾎﾟﾋﾟ／がしたら
mldb devices ## 接続確認/developerモードがオフに戻ってるとmldbが効かないので注意
mldb getprop | grep ml.build.version # バージョン確認

すべてが終わったらMagicLeapをかぶり、
コントローラーをLightPackに有線接続してコントローラーのファームウェアをアップデートする。
あとは普通に初期設定を行う (ユーザー情報消さなければスキップできるかも)

余談① : fastbootモードってなに？

Androidなどに用意されている、OSより低いレイヤーをいじるためのモード。
(LuminOSはAndroidをベースに作られています)
WindowsPCなどでいうBIOS起動に近い、がまた違った概念らしい……

筆者は自力で説明できるほど理解していないので、下記などを参照してください↓
https://source.android.com/setup/build/running?hl=ja
https://freesoft.tvbok.com/tips/efi_installation/fast_boot.html

ちなみに、MagicLeapがfastbootモードになったことは、端末表面のLEDインジケーターからも確認できます。
誤訳で「高速起動」というキャプションがついているのが、fastbootモードの時の表示です。
https://www.magicleap.care/hc/ja/articles/360011316312-Lightpack%E3%81%AELED%E3%82%B9%E3%83%86%E3%83%BC%E3%82%BF%E3%82%B9%E3%82%A4%E3%83%B3%E3%82%B8%E3%82%B1%E3%83%BC%E3%82%BF

余談② : 手順を間違えるとたいへんなことに & その復旧手段

上記の手順では、複数コマンドに渡ってOSを直接書き換えていくため、
処理の途中で誤って接続や電源を切ると、何のOSも正常に起動しない30万円の文鎮ができあがってしまいます。
OS消去によってmldbサーバーが消去されていた場合は、mldb reboot bootloaderすらできない事態に……

このように、途中でfastbootモードから誤って出てしまって文鎮化した場合は、
以下の手順でfastbootモードに復帰しましょう。

電源を切る
音量マイナスボタンをホールドする(押し続ける)
さらに、電源ボタンを同時にホールドする
電源がついたら、すぐに電源ボタンとマイナスボタンを離す
(電源ボタンを押し続けているとすぐにまた電源が切れてしまう)
本体表面のLEDインジケータが、
青っぽいLEDサインが伸び縮みするような動きをしていたら、無事fastbootモードに入れている。
PCにつないで fastboot devices から接続を確認する
上述の要領で、LuminOSをクリーンインストールする。

対処法2 : サポートに泣きつく

どうしようもない場合は公式のサポート窓口に相談しましょう。

公式サポートに相談すると、
1. 手順1でダウンロードできなかったOSイメージをダウンロードできるようにする
2. OSのアップデート通知が来ていなかったMagicLeap端末にアップデート通知を送る
のいずれかの対応を行ってくれるようです。

電話&メール

今回のケースの場合は、電話かメールがおすすめです。

どちらも非常にレスポンスが速く、きちんとサポートチケットを切って対応してくれるので、
今回のような、各ユーザーで頻発する既知の問題については、高速かつ責任ある解決が期待できます。
また、ほぼ確実にシリアルナンバーを聞かれるので、事前にメモしておきましょう。
(シリアルナンバーの調べ方は上述)

自分の場合はアメリカ向けの番号に直接電話してしまうことが多いのですが、
日本のサポート時間内であれば、プロの同時通訳者をはさんだ3者通話もできるので、
英語が苦手な方でも安心といえそうです。
ちなみに、どの国の番号もフリーダイヤルなので、通話料金も安心です。

ちなみに、fastbootモードに入るためのボタンの押し方など、
この記事の一部の情報は、サポート担当者から電話で直接教えてもらいました。
どこの公式ドキュメントにも載っていない情報を教えてもらえることもあるので、個人的に推しです。

フォーラム、Discord、Slack

公式フォーラムも有力な手段ですが、レスの速さが数日から1ヶ月程度までまちまちなのが難点です。
内部実装や製品開発ロードマップをある程度把握している中の人が答えてくれるので、
技術的にコアな内容や、公式ドキュメントに不足している情報などを質問するのに向いています。
たとえば自分の経験では、ArUcoマーカーに関するドキュメントの不備を指摘して修正してもらったことがあります。

公式Discord、LEAPERS JAPAN公式FacebookやSlackに馴染みのある方も多いと思いますが、
こちらはあくまで技術者同士の情報交換コミュニティで、公式への窓口としてはあまり適していません。
(Discordに社員の方が入っていたり、日本Slackの徳山さんが本社にコネをお持ちだったりはしますが)

特に、アメリカ圏ではMagicLeap発売から2年が経過していることもあり、
後発のnreal等と比べると、コミュニティが静かめな印象を受けます。

おわりに

実装コードもほとんどないまま5000字も書いてしまった…。
19日にも枠をもらっておりまして、そちらも実装コードが全くない記事を予定してますw ぜひお楽しみに。
明日の担当は会社の大先輩 @makisin さんです！

LuminOSがアップデートできない時のトラブルシューティング大全