トラブルシューティング¶

うまく動かないときは、まず表示されたエラーメッセージ（[ERROR] の行と Next step: のヒント）を確認してください。以下は症状別の対処です。

usbipd-win を winget でインストールできない¶

winget install ... dorssel.usbipd-win の実行時に、以下のようなエラーで先に進めない場合。

Text Only

ソースの検索中に失敗しました: winget
0x8a15000f : ソースに必要なデータがありません
作業ソースの中にパッケージが見つかりませんでした

winget のパッケージソース（パッケージ一覧のインデックス）が未初期化、または現在のユーザープロファイルに登録されていない場合に発生します。次の順で対処します。

ソースをリセットして再取得します。
PowerShell
```
winget source reset --force
winget source update
```

利用規約を自動承諾してインストールを再実行します。

PowerShell

winget install --interactive --exact dorssel.usbipd-win --accept-source-agreements --accept-package-agreements

上記で解消しない場合は、winget を使わず手動でインストールします。usbipd-win の GitHub Releases から最新の usbipd-win_x.x.x.msi をダウンロードし、ダブルクリックしてインストールしてください。

ノート

winget を実行したユーザープロファイルに winget ソースが登録されていない場合にも、本エラーが発生します。この場合も、上記の手動インストール（.msi）が確実です。

usbipd attach に失敗する（WSL ディストリビューションがない）¶

usbipd attach failed や、次のメッセージが表示される場合。

Text Only

usbipd: error: There is no WSL 2 distribution running; ...

usbipd attach --wsl には、実体のある WSL2 ディストリビューション（本ガイドでは Ubuntu）が必要です。Docker Desktop の内部ディストリビューション（docker-desktop）はアタッチ先として認識されません。

Ubuntu をインストールする — 未導入の場合は、インストール（Windows）の手順に従って wsl --install -d Ubuntu を実行し、初回セットアップ（ユーザー名・パスワード）を完了します。
WSL2 で動作しているか確認する — 次のコマンドで Ubuntu が表示され、VERSION が 2 であることを確認します。
PowerShell
```
wsl -l -v
```

セキュリティ警告で実行できない¶

「開いているファイル - セキュリティの警告」 — 「実行」をクリックします。
「WindowsによってPCが保護されました」（SmartScreen） — 「詳細情報」をクリックすると「実行」が現れるので、これをクリックします。詳細は起動（Windows）をご参照ください。

管理者権限のエラー（usbipd bind failed）¶

usbipd bind failed や「管理者権限が必要」と表示される場合。

start.bat は実行時に管理者権限を求めます。「このアプリがデバイスに変更を加えることを許可しますか？」で「はい」を選んでください。誤って「いいえ」を選んだ場合は、もう一度 start.bat を実行してください。

受信機（COM ポート）が見つからない¶

No Septentrio COM port found や mosaic-G5 ... is not connected と表示される場合。

受信機が USB 接続されているか — ケーブルを挿し直し、受信機の PWR LED が赤色に点灯していることを確認します。
RxTools がインストールされているか — 受信機を USB シリアルとして認識させるドライバは RxTools が提供します。インストールしていない場合はインストール（Windows）を参照してください。
RxControl など、他のアプリケーションが COM ポートを掴んでいないか — RxControl を開いていると COM ポートを占有します。閉じてから再実行してください。
既に WSL へアタッチ済みでないか — 一度 WSL にアタッチすると Windows からは COM ポートが見えません。scripts\windows\detach.bat でデタッチしてから再実行します。

ヒント

デバイスマネージャーの「ポート (COM と LPT)」に Septentrio Virtual USB COM Port が2つ表示されていれば、Windows は受信機を認識できています。

デバイスマネージャーを使った COM ポートの確認

SBF ストリームが検出されない¶

No SBF stream detected on the receiver's ports、または検出時に両ポートが 0 bytes と表示される場合。

SBF の出力先が USB1 になっているか — COM1（物理シリアル）に出力していると USB 側には届きません。通常は start.bat が自動設定しますが、手動設定で上書きしている場合は付録：受信機の手動設定を確認してください。
QZSL6 の Tracking が有効か — 補正情報（QZSRawL6D/E）が出力されているか、同じく付録をご参照ください。
permission denied for user ... と表示される — WSL 内のシリアルデバイス（/dev/ttyACM*）は root または dialout グループのユーザーしか読めず、dialout に入っているかどうかは Ubuntu のバージョンやセットアップ方法によって異なります。start.bat は検出を root 権限（wsl -u root）で実行するためこのエラーにはなりませんが、検出スクリプトを手動で実行した場合に表示されることがあります。恒久的に解消するには、Ubuntu のシェルで次を実行します。
Bash
```
sudo usermod -aG dialout $USER
```
実行後、PowerShell で wsl --shutdown を実行してグループ変更を反映してから再試行してください。

ノート

SBF の Support 群は測位できていなくても出力されます。両ポートが 0 bytes の場合は「衛星が見えない」ではなく「出力先ポートの設定」を疑ってください。

ヒント

受信機からデータが WSL まで届いているかは、次のコマンドで直接確認できます（両方の ttyACM ポートを順に読みます）。16進の 24 40 は SBF の同期バイト $@ です。SBF がどちらのポートに出るかは環境によって変わるため、片方だけ確認して判断しないでください。また、コンテナが起動中の場合はコンテナ側が同じポートを読んでいてデータを取り合うため、docker stop mrtklib-web-ui で停止してから確認してください。

PowerShell

wsl -u root bash -c 'for p in /dev/ttyACM*; do echo $p:; timeout 3 cat $p | head -c 64 | od -An -tx1; done'

Docker Desktop が WSL2 バックエンドで動作していない¶

docker run の実行時に、次のいずれかのエラーが表示される場合。

Text Only

docker: Error response from daemon: error gathering device information while adding custom device "/dev/ttyACM0": no such file or directory

Text Only

docker: Error response from daemon: ... workspace: Access is denied.

Docker Desktop が Hyper-V バックエンドで動作していると、コンテナは WSL2 とは別の仮想マシン上で実行されます。このため、WSL（Ubuntu）へアタッチした受信機のデバイスを参照できず（no such file or directory）、Windows のフォルダをマウントする際にもアクセスが拒否される（Access is denied）ことがあります。

まず、次のコマンドで docker-desktop が登録されているかを確認します。

PowerShell

wsl -l -v

docker-desktop が表示されない場合は Hyper-V バックエンドで動作しています。インストール（Windows）の手順に従って Use the WSL 2 based engine を有効化し、WSL Integration で Ubuntu をオンにしてから、start.bat を再実行してください。

ノート

usbipd によるアタッチ自体が成功しているかは、次のコマンドで確認できます。 /dev/ttyACM0 /dev/ttyACM1 が表示されていれば、WSL 側までは正常に届いています。

PowerShell

wsl ls /dev/ttyACM*

コンテナが起動しない¶

docker run failed や docker command not found、あるいは起動が進まない場合。

Docker Desktop が起動しているか — タスクバーの隠れているインジケーターで 🐳 にカーソルを重ね、Docker Desktop running を確認します。起動していなければ Docker Desktop を起動してから再実行してください。
- ログインユーザと管理者ユーザが異なる場合 → Docker Desktop を管理者権限で起動する
... workspace: Access is denied や ... no such file or directory と表示される — Docker Desktop が WSL2 バックエンドで動作していない場合に多く発生します。Docker Desktop が WSL2 バックエンドで動作していないを参照してください。
docker command not found — Docker Desktop 自体が未インストールです。インストール（Windows）をご参照ください。
ポート 8080 / 2101 が使用中 — 既存コンテナや他アプリがこれらのポートを使っていると起動に失敗します。詳しくはポートが使用中で起動できないを参照してください。
イメージの取得（pull）が遅い / 失敗する — 初回はイメージのダウンロードに数分かかります。ネットワークを確認し、時間をおいて再実行してください。
起動直後に落ちる — 次のコマンドでログを確認します。
PowerShell
```
docker logs mrtklib-web-ui
```

ポートが使用中で起動できない¶

コンテナは 2 つのポートを使用します。どちらか一方でも埋まっていると docker run が失敗し、コンテナは起動しません。

ポート	用途
`8080`	Web UI（MRTKLIB Console）
`2101`	測位結果の TCP/IP 出力（付録：測位結果の出力設定）

ノート

2101 は TCP/IP 出力を使わない場合でも起動時に確保されます。出力機能を使う予定がなくても、このポートが埋まっていると起動に失敗します。

次のようなエラーが表示されます。

Text Only

docker: Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:2101 -> 127.0.0.1:0: listen tcp 0.0.0.0:2101: bind: Only one usage of each socket address ... is normally permitted.

前回のコンテナが残っている場合¶

最も多い原因です。次のコマンドで削除してから start.bat を再実行します。

PowerShell

docker rm -f mrtklib-web-ui

他のアプリがポートを使用している場合¶

次のコマンドで、ポートを使用しているプロセスの PID を調べます。

PowerShell

netstat -ano | findstr :2101

表示された行の右端が PID です。プロセス名は次のコマンドで確認できます。

PowerShell

tasklist /FI "PID eq 1234"

そのアプリを終了できない場合は、使用するポートを変更するを参照してください。

Windows がポートを予約している場合¶

netstat に何も表示されないのに起動に失敗し、次のようなエラーが出る場合は、Windows（Hyper-V / WinNAT）がポート範囲を予約している可能性があります。

Text Only

bind: An attempt was made to access a socket in a way forbidden by its access permissions.

予約されている範囲は次のコマンドで確認できます。管理者権限の PowerShell で実行してください（PowerShell を管理者権限で起動）。

PowerShell

netsh int ipv4 show excludedportrange protocol=tcp

表示された範囲に 8080 または 2101 が含まれていた場合、WinNAT を再起動すると予約が解放されることがあります。

PowerShell

net stop winnat
net start winnat

解放されない場合は、使用するポートを変更するを参照してください。

使用するポートを変更する¶

scripts\windows\lib\common.ps1 の冒頭にある次の値を、空いているポート番号に書き換えます。

PowerShell

$HostPort      = 8080   # web UI (MRTKLIB Console)
$OutPort       = 2101   # TCP/IP output of the solution

ノート

この2つの値は common.ps1 の1箇所で定義され、前提条件の確認とコンテナ起動の両方から参照されます。他のファイルを書き換える必要はありません。

重要

$OutPort を変更した場合は、UI の Output & Log Streams で設定する TCP Server のポート番号も同じ値に合わせてください。数字が一致していないと外部から接続できません。

Docker Desktop を管理者権限で起動する¶

ログインユーザと管理者ユーザが異なる場合、Docker Desktop を管理者権限で起動する必要があります。 すでに Docker Desktop が起動している場合には、先に以下の手順で Docker Desktop を停止します。

Docker Desktop の停止¶

タスクバーの ^ から隠れているインジケーターを表示します。 🐳のアイコンにカーソルを重ね、右クリックで Quit Docker Desktop をクリックし、終了します。

Docker Desktop の起動¶

Windows のスタートメニューから Docker Desktop を検索し、右クリックして「管理者として実行」をクリックします。

管理者権限で起動し直した場合、Docker Desktop の設定はユーザごとに保存されるため、Docker Desktop のバックエンド設定 をあらためて確認してください。

ブラウザで UI が開かない¶

初回はイメージ取得に時間がかかる — 起動待ちがタイムアウトしても、コンテナは動いている場合があります。少し待ってから手動で http://localhost:8080 を開いてください。

コンテナが動いているか確認 — 次のコマンドで mrtklib-web-ui が Up かを確認します。無ければ start.bat を再実行します。

PowerShell

docker ps

動作している場合

PowerShell

CONTAINER ID   IMAGE                                    COMMAND                   CREATED          STATUS                    PORTS                                         NAMES
afa58c127340   hatognss/mrtklib-docker-ui:0.3.0-alpha   "uvicorn mrtklib_web…"   47 seconds ago   Up 46 seconds (healthy)   0.0.0.0:8080->8000/tcp, [::]:8080->8000/tcp   mrtklib-web-ui

動作していない場合

PowerShell

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

測位が始まらない / FIX しない¶

UI の Path が正しいか — ttyACM0 を設定します（先頭の /dev/ は不要）。起動スクリプトが SBF の出ているポートをコンテナ内で /dev/ttyACM0 に固定して渡すため、環境によらずこの値です（UI の使い方）。
アンテナが遮蔽されていないか — 屋内や上空が遮られる場所では衛星を捕捉できません。空の開けた場所にアンテナを設置してください。
初回は航法データの取得に時間がかかる — 測位が始まるまで数分待ちます。
QZSS L6 が受信できているか — MADOCA-PPP は QZSS L6 の補正情報が必要です。QZS の可視状況（仰角）を確認してください（GNSS View）。