戻る | 前へ | 次へ

IPAd (euicc-profile-assistant) 使用手順¶

注釈

docomo business SIGNの提供機能ではありません。ご利用をご希望されるお客様向けにIoT Connect Mobile Type Sの付加機能として、個別にご提供いたします。

動作環境¶

IoT機器

アーキテクチャ
- Raspberry Pi 4 または 5 (arm64)
- PC (amd64(x86_64))
  
  VMware workstation 等の仮想環境上でも可
ディストリビューション
- Raspberry Pi の場合、 Raspberry Pi OS (Trixie)
- PC の場合、 Ubuntu 24.04

SIM

SGP.32 対応 eUICC

通信モジュール/組み込み製品

以下が、現時点で対応している通信モジュールです。

通信モジュール/組み込み製品	制御プロトコル	備考
Telit Cinterion LN920A6WW	MBIM (Mobile Broadband Interface Model)	アンテナ・SIMの取り付けに関しては該当マニュアルを参照してください。
Soracom Onyx (SC-QGLC4-C1)	QMI (Qualcomm MSM Interface)

注釈

MBIMプロトコル、QMIプロトコルの両方に対応しているモジュールをご使用の場合、どちらのモードに設定されているかご確認いただき、必要に応じて設定を変更してください。

(必要に応じて)セルフパワー仕様の USB ハブ

Raspberry Pi は、AC アダプタの供給電力が不足する場合、上記の通信モジュールを接続すると Raspberry Pi OS の動作が不安定になる場合があります。供給電力が高いACアダプタを使用するか、ACアダプタと通信モジュールを USB ハブに接続し、USB ハブ経由で電力を供給する構成にしてください。

インストール手順¶

リリースファイル (euicc-profile-assistant-x.x.x.zip) を展開します。
展開先フォルダで、ご自身の環境に適合したパッケージ一式をインストールしてください。
```
# Raspberry Pi の場合
sudo apt install ./rpi-os/*.deb

# PC の場合
sudo apt install ./ubuntu24/*.deb
```

通信モジュールの準備¶

通信モジュールに SGP.32 対応 eUICC を装着します。
通信モジュールを Raspberry Pi または PC に接続します。
通信モジュールが起動完了するまで 1 ～ 2 分程度待ちます。
コマンド mmcli -L を実行して通信モジュール名が表示されれば、モジュールは起動完了しています。
```
$ mmcli -L
    /org/freedesktop/ModemManager1/Modem/<num> [xxx] xxx
```
注釈
- 上記の <num> および xxx の部分は、通信モジュールまたは認識状況により変化します。
- <num> は、後ほどのコマンド実行で使用します。
注釈

mmcli -L でモジュール名が表示されない場合、モデムマネージャ起動状態を確認し、もし ModemManager が起動していない場合、起動操作を実施してください。
```
$ sudo systemctl status ModemManager # 起動状態の確認
$ sudo systemctl restart ModemManager # 再起動
```

SIM が認識されているか確認を行います。コマンド mmcli -i <num> を実行し、下記のような表示 (active: yes) となることを確認してください。

注釈

<num> は、 mmcli -L の実行結果に表示される値です。

$ mmcli -i 0
  -------------------------------
  General    |              path: /org/freedesktop/ModemManager1/SIM/0
  -------------------------------
  Properties |            active: yes
             |              imsi: 001010123456063
             | emergency numbers: 112, 545727
             |              gid1: FFFF
             |              gid2: FFFF

SIM が認識されない場合、 error: couldn't find SIM が表示されます。

SIM に対してコマンドが発行できるか確認を行います。下記のコマンドを実行し、 eUICC の EID 値が表示されることを確認してください。

指定するパラメータは、通信モジュールの制御プロトコルによって異なります。 MBIM プロトコルの場合 --mbim-device 、QMI プロトコルの場合 --qmi-device を指定してください。
```
# MBIM プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-eid --mbim-device /dev/cdc-wdm0
890410300xxxxxxxxxxxxxxxxxxxxxxx

# QMI プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-eid --qmi-device /dev/cdc-wdm0
890410300xxxxxxxxxxxxxxxxxxxxxxx
```

通信モジュールの初回設定 (MBIM プロトコル対応の通信モジュールのみ)¶

注釈

「MBIM プロトコル対応通信モジュール」および「IPAe 内蔵の eUICC」の両方を利用する場合のみ、初回設定を必ず実施してください。
IPAe が内蔵されていない eUICCの場合、この設定は必須ではありません (TERMINAL CAPABILITY の設定によらず動作します)。

QMI プロトコルの通信モジュールの場合、設定不要です。

通信モジュールの初回使用時、および通信モジュールを他の機器に接続した後、下記のコマンドを実行し、 TERMINAL CAPABILITY を設定してください。

$ sudo /usr/sbin/sgp32tools configure-terminal-capability --ipa-on-device enable --lpa-on-device enable --mbim-device /dev/cdc-wdm0

本設定は UE 上の不揮発メモリに保存されるため、毎回行う必要はありません (通信モジュールの初回使用時および、通信モジュールを他の機器に接続した後のみ設定してください)。 TERMINAL CAPABILITY を設定することにより、 eUICC 上の IPAe の起動・停止が切り替わります。 IPAe が動作していると IPAd は動作できないため、本設定を行う必要があります。

IPAe が動作する状態に戻したい場合、下記コマンドを実行してください。

$ sudo /usr/sbin/sgp32tools configure-terminal-capability --ipa-on-device disable --lpa-on-device disable --mbim-device /dev/cdc-wdm0

eCD (eIM Configuration Data) の初期設定¶

下記の操作により、 SGP.32 対応 eUICC に対して eCD (eIM Configuration Data) を設定してください。

注釈

既に設定済の場合、本手順の実施は不要です。

下記コマンドを実行し、設定済の eCD の値があればバックアップします。

# MBIM プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-ecd --mbim-device /dev/cdc-wdm0 --output ecd_backup.json

# QMI プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-ecd --qmi-device /dev/cdc-wdm0 --output ecd_backup.json

ecd_backup.json の内容が [] の場合、設定済の eCD はありません。

下記コマンドを実行し、設定済の eCD を消去します。

$ sudo /usr/sbin/sgp32tools euicc-memory-reset --mbim-device /dev/cdc-wdm0
reset_result: ok        # okNothingToDelete(1) となる場合もあります
reset_eim_result: ok    # 設定済 eCD がない場合、 okNothingToDelete(1) となります

Applet Console の「設定」メニュー＞「eIM」タブを開き、「eIM 設定データ (eCD)」の取得したJSONデータからファイル ecd.json を作成します。

注釈

Applet Consoleからコピーした jsonデータは、 [ ] で囲む必要があります。(JSON の配列形式にしてください)

[
  {
    "eim_id": "eim.xxx.sim-applet.com",
    "eim_id_type": "FQDN",
    "eim_publickey_data": {
      "public_key": "MFkwEwYHKoxxxxxxxxxxoZIzj0DAQcDQgAE/pSWwj4a2ZbxpSbOBvuxIzE2BiL+q3xDA8oyBDdGSVNcTNU9Tmdf76cekTUjUz6DEXH9KYAXaGA8HzdG4kexVw=="
    },
    "eim_supported_protocol": [
      "eimRetrieveHttps",
      "eimProprietary"
    ],
    "euicc_ci_pkid": "xxxxxxxxxxd0b1d408d4c3b232e6d25e795bebfb",
    "trusted_publickey_data_tls": {
      "public_key": "MFkwEwYHKoxxxxxxxxxxoZIzj0DAQcDQgAE/DoV49En3zulkmOqQK/ZQ+GBea60C2OklziHhDieILahvxU11V6kdB6zlHUDBSspEKlotoPQ=="
    }
  }
]

下記コマンドを実行し、 eCD を設定します。

# MBIM プロトコルの場合
$ sudo /usr/sbin/sgp32tools add-initial-eim --mbim-device /dev/cdc-wdm0 ecd.json

# QMI プロトコルの場合
$ sudo /usr/sbin/sgp32tools add-initial-eim --qmi-device /dev/cdc-wdm0 ecd.json

下記コマンドを実行し, 設定した eCD が読み出せるか確認します。

# MBIM プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-ecd --mbim-device /dev/cdc-wdm0 | jq

# QMI プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-ecd --qmi-device /dev/cdc-wdm0 | jq

eCD を読み込ませるため、 IPAd を再起動します。

# MBIM プロトコルの場合
$ systemctl status euicc-profile-assistant-mbim@cdc-wdm0.service

# QMI プロトコルの場合
$ systemctl status euicc-profile-assistant-qmi@cdc-wdm0.service

IPAdの起動・停止手順、eIM への疎通確認手順¶

IPAdの起動状況確認

初期設定後、IPAd は、通信モジュールが起動完了すると自動的に起動します。起動状態は、下記コマンドで確認できます。

# MBIM プロトコルの場合
$ systemctl status euicc-profile-assistant-mbim@cdc-wdm0.service

# QMI プロトコルの場合
$ systemctl status euicc-profile-assistant-qmi@cdc-wdm0.service

下記のように Active: active (running) が表示されれば、起動成功です。

$ systemctl status euicc-profile-assistant-mbim@cdc-wdm0.service
● euicc-profile-assistant-mbim@cdc-wdm0.service - SGP.32 IPAd (IoT Profile Assistant in the IoT Device)
     Loaded: loaded (/lib/systemd/system/euicc-profile-assistant-mbim@.service; disabled; preset: enabled)
     Active: active (running) since Thu 2025-09-25 11:00:04 JST; 21min ago

IPAdの起動

IPAd の起動は、下記いずれかの手順で行えます。

# MBIM プロトコルの場合
$ sudo systemctl start euicc-profile-assistant-mbim@cdc-wdm0.service

# QMI プロトコルの場合
$ sudo systemctl start euicc-profile-assistant-qmi@cdc-wdm0.service

IPAdの停止

IPAd の停止は、下記いずれかの手順で行えます。

通信モジュールの USB ケーブルを抜く。 USB デバイスのリセット等により、 IPAd は自動的に停止します。

下記のコマンドで手動で停止させる。

# MBIM プロトコルの場合
$ sudo systemctl stop euicc-profile-assistant-mbim@cdc-wdm0.service

# QMI プロトコルの場合
$ sudo systemctl stop euicc-profile-assistant-qmi@cdc-wdm0.service

IPAdのログ表示

ログ表示は、下記いずれかの手順で行えます。ログ表示により、IPAdの動作状況、IPAd-eIM 間の疎通状況などが確認できます。

# MBIM プロトコルの場合
$ journalctl -u euicc-profile-assistant-mbim@cdc-wdm0

# QMI プロトコルの場合
$ journalctl -u euicc-profile-assistant-qmi@cdc-wdm0

注釈

加えて -f オプションを指定することで、リアルタイムでログを確認できます。

IPAd の起動直後のログから、下記の事項を確認してください。

eim_id の値 (eIM のホスト名) が表示されること。eUICC に設定した eCD の内容と合致すること。
eUICC から読み出した EID 値がログ表示されること。
IPAd の起動後数秒～数十秒以内に periodic polling completed とログ表示されること。

ログ内でこの表示が確認できれば、 eIM との疎通成功です。

Sep 25 11:00:04 raspberrypi systemd[1]: Started euicc-profile-assistant-pcsc.service - SGP.32 IPAd (IoT Profile Assistant in the IoT Device).
Sep 25 11:00:07 raspberrypi euicc-profile-assistant[890187]: [2025-09-25T02:00:07.205Z euicc_profile_assistant::esipa_http] eim_id: "eim-xxx.xxx.com", eim_id_type: Some(EimIdType(Integer(Primitive(2))))
Sep 25 11:00:07 raspberrypi euicc-profile-assistant[890187]: [2025-09-25T02:00:07.353Z euicc_profile_assistant::esipa_http] eim_id: "eim.xxx.sim-applet.com", eim_id_type: Some(EimIdType(Integer(Primitive(2))))
Sep 25 11:00:07 raspberrypi euicc-profile-assistant[890187]: [2025-09-25T02:00:07.578Z euicc_profile_assistant::esipa_http] EID: 12345678906727494900000009141036
Sep 25 11:00:08 raspberrypi euicc-profile-assistant[890187]: [2025-09-25T02:00:08.496Z euicc_profile_assistant::esipa_http] periodic polling completed (noEimPackageAvailable)

eIMとの疎通確認後、eIM 側で操作 (プロファイルの enable など) を行い、動作を確認してください。

プロトコルの切り替え手順 (eIM Package Injection の利用手順)¶

eCD (eIM Configuration Data) に "eim_supported_protocol": [ "eimProprietary" ] が設定されているか確認します。
```
# MBIM プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-ecd --mbim-device /dev/cdc-wdm0 | jq

# QMI プロトコルの場合
$ sudo /usr/sbin/sgp32tools read-ecd --qmi-device /dev/cdc-wdm0 | jq
```
もし出力結果に "eim_supported_protocol": [ "eimProprietary" ] が含まれていない場合、 eIM Configuration Data の初期設定を再度実施してください。
設定ファイル /etc/default/euicc-profile-assistant を作成し、下記内容を記載してください。
```
EIM_PROTOCOL=MQTTS
EIM_POLL_INTERVAL=disable
```

下記いずれかのコマンドにより、サービスを再起動してください。

# MBIM プロトコルの場合
$ sudo systemctl restart euicc-profile-assistant-mbim@cdc-wdm0.service

# QMI プロトコルの場合
$ sudo systemctl restart euicc-profile-assistant-qmi@cdc-wdm0.service

ログにより、 MQTT broker に接続したことを確認してください。

注釈

以下の例は、MBIM プロトコル対応の通信モジュールの場合です。

$ journalctl -u euicc-profile-assistant-mbim@cdc-wdm0.service
...
Mar 14 21:36:55 pn42 systemd[1]: Started euicc-profile-assistant-mbim@cdc-wdm0.service - SGP.32 IPAd (IoT Profile Assistant in the IoT Device).
Mar 14 21:36:55 pn42 sh[78322]: [2026-03-14T12:36:55.265Z euicc_profile_assistant] periodic polling is disabled
Mar 14 21:36:55 pn42 sh[78322]: [2026-03-14T12:36:55.913Z euicc_profile_assistant::esipa_mqtt] EID: 12345678906727494900000062022817
Mar 14 21:36:56 pn42 sh[78322]: [2026-03-14T12:36:56.104Z euicc_profile_assistant::esipa_mqtt] MQTT broker: eim.xxx.sim-applet.com:8883
Mar 14 21:36:56 pn42 sh[78322]: [2026-03-14T12:36:56.566Z euicc_profile_assistant::esipa_mqtt] MQTT Connected

eIM Package Retrieval (従来版の polling 動作) に戻す場合、下記の操作を行ってください。

設定ファイル /etc/default/euicc-profile-assistant を削除する。

下記いずれかのコマンドを実行し、サービスを再起動する。

# MBIM プロトコルの場合
$ sudo systemctl restart euicc-profile-assistant-mbim@cdc-wdm0.service

# QMI プロトコルの場合
$ sudo systemctl restart euicc-profile-assistant-qmi@cdc-wdm0.service

(参考) QMI プロトコル対応の通信モジュールにおける制限事項¶

下記の理由により、動作実績のない通信モジュールを QMI プロトコルで使用する場合、個別の検証が必要です。

通信モジュールの機種によっては、 QMI プロトコルの APDU コマンド送信機能が使用できない。
通信モジュールの機種により、 TERMINAL CAPABILITY APDU コマンドが自律的に送信されるタイミングや送信有無が異なる。
通信モジュールの仕様として eSIM 対応ではない製品 (規格 GSMA SGP.22 もしくは SGP.32 に対応していない製品) においては、プロファイル切替・プロファイルダウンロードなどの処理を行う際に予期せぬ不具合が発生する可能性がある。