【重要】TTN V2からTTN V3への移行手順

2021-05-07 (Fri)

マルチランゲージ版The Things Stack V3を搭載したThe Things Stack Community Editionがリリースされるまで、あと少し時間がかかかります。　現行のThe Things Network V2は、前にもこのブログで何度か触れましたが、今年いっぱいで停止となります。　そこで現在のゲートウェイや登録したLoRaWANデバイスをどうやって移行するか？　説明をいたします。

＊Migrating to The Things Stack Community Edition（オリジナルソース）
↓
https://www.thethingsnetwork.org/docs/the-things-stack/

The Things Stack Community Editionへの移行

クイックスタートで述べたように、The Things Network V2のソフトウェアは、The Things Stack Community Edition（通称V3）にアップグレードされました。既存のThe Things Network V2ユーザーは、The Things Network V2のクラスターが2021年末に停止するため、ゲートウェイやデバイスをThe Things Stack Community Editionに移行する必要があります。

*The Things Stack Community Edition
↓
https://console.cloud.thethings.network/

注記：
The Things Stack Community Editionは、The Things Networkコミュニティメンバーが無料で使用できるLoRaWANネットワークサーバーです。Community Editionは、LoRaWANプロジェクトのテストと評価のために設計されており、The Things Industriesが管理しています。コミュニティ版は保証がなく、コミュニティのサポートのみが含まれているため、商用利用には適していません。コミュニティサポートについては、The Things Network ForumまたはSlackにご参加ください。

商用のLoRaWANプロジェクトでは、専門的なサポートが含まれるSLA保証版のThe Things Stackを使用することが推奨されています。

なぜデバイスやゲートウェイをThe Things Network V2からThe Things Stack Community Editionに移行しなければならないのですか？

ここでは、The Things Network V2の使用経験があり、そこにゲートウェイやデバイスが接続されていることを前提としています。まだThe Things Network V2を使用されていない場合は、下記クイックスタートガイドに従ってください。

https://www.thethingsnetwork.org/docs/quick-start/

The Things Stackの特徴

The Things Stackは、The Things Network V2と比較して、より拡張性が高くより安全で、最新のLoRaWANバージョン1.1や1.0.4など、最新のLoRaWAN開発をすべてサポートしています。

The Things Stackのアーキテクチャはマイクロサービスをベースにしており、サービスの分散、スケーリング、他のLoRaWANネットワークとの相互運用性が向上しています。

The Things Stackは、すべてのLoRaWANクラス（A、B、C）とマルチキャストデバイスグループ、既存のすべてのLoRaWANバージョン（v1.0.4、v1.1を含む）、LoRa Allianceが定義するすべての地域パラメータをサポートしています。標準に準拠することで、The Things Stackはパッシブローミングをサポートし、将来的にはハンドオーバーローミングもサポートする予定です。

今回のアップグレードでは、無線によるファームウェアの更新、高度なクラスタリングとロードバランシング技術も提供されます。
高度なAPIは、gRPC、HTTP、MQTTの統合を提供します。デバッグのためには、APIベースのイベントストリームがあり、問題の追跡、デバイスの動作の監視、有用なアラートの取得に役立ちます。The Things Stackが使用するデータフォーマットは、異なるスキーマを持ちより豊富なメタデータをサポートしています。データを保存するためにStorage Integrationも用意されています。

The Things Stackのユーザーは、セキュリティキーの保存と発行にGlobal Join Serverを使用することができ、それによってセンサー展開のセキュリティを向上させることができます。このネットワークアーキテクチャは、標準規格に準拠しているため、開発者は信頼できるサードパーティが運営するジョインサーバーを使用することもできます。

The Things Stack Community EditionとプライベートLoRaWANネットワーク間のトラフィック交換を可能にすることで、LoRaWANネットワークのカバレッジ、パフォーマンス、キャパシティを向上させ、エンドデバイスのバッテリー寿命を延ばすことができ、最も重要な機能の一つです。

また、「The Things ID」機能により、「The Things Network V2」でのユーザー名とパスワードを再利用してログインすることができます。ユーザーは、改良されたユーザーインターフェースやCLIを備えたコンソールを使用して、ゲートウェイ、デバイス、アプリケーション、ユーザー、組織を管理したり、アップリンクやダウンリンクのイベントをリアルタイムでやり取りしたりすることができます。

「The Things Network V2」と「The Things Stack Community Edition」のより詳細な比較については、「The Things Stackの主な変更点」のページをご覧ください。

ゲートウェイとデバイスの移行

このガイドは、The Things Network V2からThe Things Stack Community Editionに移行する際の全体的な移行プロセスを、いくつかの分かりやすいステップで説明するために書かれたものです。

注記:
The Things Stack Community Editionは、The Things Networkコミュニティメンバーが無料で使用できるLoRaWANネットワークサーバーです。Community Editionは、LoRaWANプロジェクトのテストや評価のために設計されており、The Things Industriesが管理しています。コミュニティ版は保証がなく、コミュニティのサポートのみが含まれているため、商用利用には適していません。コミュニティサポートについては、The Things Network ForumまたはSlackにご参加ください。

このセクションでは、まずエンドデバイスの移行を検討し、次にゲートウェイの移行を検討します。また、アプリケーション、インテグレーション、ペイロードフォーマッターをThe Things Stack Community Editionに追加する必要があります。

*The Things Stack Community Edition
↓
https://console.cloud.thethings.network/

移行プロセスが成功し、期待通りの結果が得られることを確認するために、単一のエンドデバイスまたはエンドデバイスの小規模なバッチで移行をテストすることを強くお勧めします。

単一のエンドデバイスを移行するには、The Things Stack Community Edition コンソールから簡単に行うことができます。エンドデバイスを一括して移行するには、ttn-lw-migrateツールを使用します。

The Things Network V2からThe Things Stackへの移行動画解説

The Things Stack Community Editionへログイン

下記の手順を続けるためには、まずThe Things Stack Community Edition Consoleにログインして、地理的に最も近いクラスタを選択する必要があります。その後、The Things IDを介して、The Things Networkの認証情報でログインします。

The Things Stack Community Editionでアプリケーション追加

エンドデバイスを移行するには、まずThe Things Stack Community Edition上にアプリケーションを追加する必要があります。アプリケーションIDは、必ずしもThe Things Network V2のものと同じである必要はありません。

ペイロードフォーマッタや統合機能の追加

The Things Stack Community Editionでアプリケーションを追加した後、ペイロードフォーマッター（The Things Network V2ではコーダーとデコーダーと呼ばれています）やインテグレーションなどの関連要素も再度追加する必要があります。コンセプトは「The Things Network V2」と同じですが、若干の改良が加えられています。

The Things Network V2のペイロードコーダーとデコーダーのフォーマットは、The Things Stack Community Editionでもサポートされています。

The Things Stack Community Editionでのペイロードフォーマッタの書き方や統合機能の追加方法についてはこちらをご覧ください。

https://www.thethingsindustries.com/docs/integrations/payload-formatters/

次にエンドデバイスを移行する必要があります。1つのデバイスなのか、複数のデバイスなのかによって、適切な移行方法を選択します。

＊方法1: The Things Stack Community Edition コンソールを使ってエンドデバイスを移行する

The Things Stack Community Editionでエンドデバイスを追加

まず最初に、The Things Stack Community Edition でデバイスを追加します。ABPデバイス、OTAAデバイスともに手動で行うことができます。OTAAデバイスの場合は、デバイスリポジトリにデバイスの種類がある場合は、その種類を送信することでも行えます。

OTAA デバイスを手動で追加する場合は、以下の手順を正しく実行してください。
・ OTAA（Over The Air Actiovation）を選択します。
・ LoRaWANバージョンMAC V1.0.2を選択（長い間最も安定しており、最も一般的に使用されているバージョンであるため、おそらくこれがあなたのバージョンです。
・エンドデバイスIDの作成（The Things Network V2のDevice IDと一致する必要はありません。
・エンドデバイスのAppEUIとDevEUIを入力します（これらはThe Things Network V2のものと同じである必要があります）。
・周波数プランの選択
・ Regional Parameters version PHY V1.0.2 REV Bを選択（これはおそらくあなたのバージョンです
・サポートクラスB/Cにはチェックを入れないでください。
・高度な設定はおそらく必要ありません
・エンドデバイスのAppKeyを入力してください（The Things Network V2のものと一致する必要があります）

OTAAの使用を強くお勧めします! OTAAがABPよりも優れている理由をご覧ください。

どうしてもABPを使いたいという理由がある場合は、次の手順でABPデバイスをThe Things Stack Community Editionに追加することができます。

・アクティベーション・バイ・パーソナリゼーション（ABP）を選択します。
・ LoRaWANバージョンMAC V1.0.2を選択（これは長い間、最も安定していて最もよく使われているバージョンなので、おそらくあなたのバージョンです。
・エンドデバイスIDの作成（The Things Network V2のDevice IDと一致する必要はありません。
・ DevEUIフィールドはオプションです。
・周波数プランの選択
・ Regional Parameters version PHY V1.0.2 REV Bを選択してください（これはほとんどの場合、あなたのバージョンです）。
・サポートクラスB/Cにはチェックを入れないでください。
・デバイスのDevAddrとNwkSKeyを入力してください（これらはThe Things Network V2のものと同じでなければなりません）。
・高度な設定は、登録時に設定する必要があります（設定を変更すると、後で動作しない場合がありますのでご注意ください
o Frame counter widthを32ビットに設定（これはおそらくあなたの値です）
o RX1の遅延を1に設定（秒単位で設定）
o RX1データレートオフセットを0に設定
o お使いのデバイスはフレームカウンタをリセットしていると思いますので、Resets Frame Countersボックスをチェックしてください。
o 周波数プランが EU868 の場合、RX2 データレートインデックスを 3 に設定する。
o 周波数プランが EU868 の場合、RX2 周波数を 869525000 に設定する。
o EU868デバイスの工場出荷時のプリセット周波数を、すべてのデバイスの場合は868100000、868300000、868500000に、8チャンネルデバイスの場合は867100000、867300000、867500000、867700000、8679000、868100000、868300000、868500000に設定してください。

エンドデバイスがThe Things Network V2へのJoin実行を防ぐ

The Things Stack Community Editionにデバイスを登録したら、デバイスをThe Things Network V2に参加させないようにする必要があります。

OTAAデバイスの場合、The Things Network V2からデバイスを削除することで簡単に行うことができますが、データが失われる可能性がありますのでお勧めできません。

推奨される方法は、The Things Network V2でAppKeyを変更することです。この方法では、既存のセッションはまだ終了しませんが、エンドデバイスから送信された新しいJoinリクエストは、The Things Network V2クラスターでは受け付けられません。

移行プロセスが期待通りに進まない場合は、AppKeyの古い値を戻してThe Things Network V2に再接続することができます。

ABPデバイスの場合は、The Things Network V2から削除する必要があります。同じセッションを2つの場所で持つと、深刻なコンフリクトが発生します。

OTAAのエンドデバイスにThe Things Stack Community Editionのネットワークへの参加を強制する

OTAAエンドデバイスは、The Things Stack Community Editionへの新規参加(Join)を行う必要があります。
この方法は、デバイスのファームウェアに大きく依存します。

・エンドデバイスが不定期に（毎週、毎月など）新規参加を行う場合は、それが起こるのを待つしかありません。
・エンドデバイスが新規参加のトリガーとなるダウンリンクメッセージを送信できる場合は、The Things Network V2 Consoleからコマンドを送信してください。
・エンドデバイスが接続を失った時に新規参加を行った場合 - The Things Network V2 Consoleからそのデバイスを削除してください。
・エンドデバイスがパワーサイクルされたときにnew joinを行う場合 - パワーサイクルしてください。

まだThe Things Network V2からゲートウェイを移行していないので、エンドデバイスから送信された新しいJoinリクエストはThe Things Network V2クラスターで受信されます。このリクエストは、エンドデバイスのAppKeyを変更した場合（上記の推奨通り）や削除した場合には受け付けられません。

面白いのは、あなたのエンドデバイスの新しいJoinリクエストがThe Things Stack Community Editionクラスタでも受信されることです。これはPacket Brokerのおかげです（The Things Stack Community Editionコンソールでアップリンクのメタデータを見て確認できます）。

さて、Things Stack Community Editionのクラスターは、このJoinリクエストを受け入れるので、エンドデバイスは新しいDevAddrやチャンネル設定などのMACパラメータを取得します。新たに割り当てられたDevAddrを元に、Packet BrokerはThe Things Stack Community Editionのネットワークへのトラフィックをルーティングします。

ABPエンドデバイスをどうするか？

ABPデバイスを使用している場合、エンドデバイスは、まだThe Things Network V2 DevAddrに関連付けられているため、ゲートウェイをThe Things Stack Community Editionに接続していない場合、パケットブローカーは、トラフィックをThe Things Stack Community Editionクラスタにルーティングすることができないことになります。

このトラフィックを正しくルーティングするには、このページの最後のあなたのゲートウェイを移行パートをご参照ください。

＊方法2: マイグレーションツールを使ってエンドデバイスを移行

この方法で移行を完了するには、ttn-lw-migrateツールが必要です。

ttn-lw-migrate は、The Things Network V2 クラスタからエンドデバイスとアプリケーションを JSON ファイルにエクスポートするために使用します。このJSONファイルは、後でThe Things Stack Community EditionにConsoleまたはCLI経由でインポートできます。

デバイスはThe Things Stack Community Editionに再Joinしなければなりません

デバイスの移行を始める前に、アクティブセッションの移行についていくつか知っておくと良いでしょう。

The Things Stack version v3.12.0から、特定のデプロイメントではアクティブセッションの移行も可能になりました。アクティブなセッションを移行すると、OTAAデバイスはThe Things Stackネットワークに新たに参加する必要がなくなります。

警告：
The Things Network V2からThe Things Stack Community Editionにアクティブなセッションを移行することはできません。つまり、新しいセッションを開始するためには、デバイスがThe Things Stack Community Editionのネットワークに新たにジョインする必要があります。

これは、The Things Stack Community EditionがThe Things Network V2とは異なるDevAddrブロックを使用しているためです。アクティブなセッションの移行は、The Things Industries V2 (V2 SaaS)のお客様が、The Things Stack Cloudやその他のThe Things Stackの有料サービスに移行する場合のみ可能です。

環境設定

マイグレーションツールのインストール後、環境変数の設定を行う必要があります。

$ export TTNV2_APP_ID="ttn-v2-application-ID"
$ export TTNV2_APP_ACCESS_KEY="access-key-of-your-ttn-v2-application"
$ export FREQUENCY_PLAN_ID="EU_863_870_TTN"

サポートされている周波数プランの一覧を参照し、設定に応じFREQUENCY_PLAN_IDを調整してください。

プライベートのThe Things Industries V2クラスターを所有している場合は、移行ツールを使用することができますが、追加の変数が設定されます。

$ export TTNV2_DISCOVERY_SERVER_ADDRESS=".thethings.industries:1900"

プライベートな The Things Industries V2 クラスタの Discovery Server が TLS を使用しない場合は、ttn-lw-migrate ツールを実行する際、ttnv2.discovery-server-insecure フラグを使用する必要があります。

The Things Network V2からシングルエンドデバイスをエクスポート

The Things Network V2からエンドデバイスをエクスポートする前に、エクスポートのテストを行います。

$ ttn-lw-migrate devices --dry-run --verbose --source ttnv2 "v2-end-device-ID" > devices.json

問題がなければ、次のコマンドを使ってエンドデバイスを実際にエクスポートし、セキュリティキーをクリアします。

$ ttn-lw-migrate device --source ttnv2 "v2-end-device-ID" > devices.json

The Things Network V2から複数のエンドデバイスをエクスポート

複数のデバイスをエクスポートするには、device_ids.txtというファイルを作成し、1行に1つのデバイスIDを記述します。

dev1
dev2
dev3

そしてエクスポートのテストを行います。

$ ttn-lw-migrate devices --dry-run --verbose --source ttnv2 < device_ids.txt > devices.json

これで問題がなければ、エンドデバイスをエクスポートするために次のコマンドを使用します。

$ ttn-lw-migrate device --source ttnv2 < device_ids.txt > devices.json

The Things Network V2アプリケーションに関連するすべてのエンドデバイスをエクスポート

The Things Network V2アプリケーションが含むすべてのデバイスをall-devices.jsonというファイルにエクスポートするには、以下のコマンドを使用します。

$ ttn-lw-migrate application --verbose --dry-run --source ttnv2 "ttn-v2-application-ID" > all-devices.json # testing export - make sure it goes without errors
$ ttn-lw-migrate application --source ttnv2 "ttn-v2-application-ID" > all-devices.json

The Things Network V2アプリケーションに関連するすべてのエンドデバイスをエクスポート

エンドデバイスをJSONファイル(ここではdevices.jsonとします)にエクスポートしたら、The Things Stack Community EditionアプリケーションでコンソールまたはCLI経由でそれらのデバイスをインポートすることができます。

コンソールでインポートする場合は、The Things Stack Community Editionアプリケーションにアクセスして、「End devices」にある「Import end devices」ボタンをクリックします。The Things StackのJSONフォーマットを選択し、Fileにあるdevices.jsonをアップロードします。Create end devices」ボタンをクリックすると、できあがりです。

CLIを使ってエンドデバイスをインポートしたい場合は、以下のコマンドを実行します。

$ ttn-lw-cli end-devices create --application-id "v3-application-id" < devices.json

どの方法でエンドデバイスをインポートしても、エラーが発生した場合は、関連するエラーメッセージが表示されます。

The Things Stack Community EditionでインポートしたデバイスのMAC設定を調整

OTAAエンドデバイスを移行し、そのデバイスがThe Things Stack Community Editionに新規参加した場合、MAC設定はネットワークサーバによって自動的に正しく設定されます。

しかし、ABP デバイスを移行した場合は、MAC 設定を手動で設定する必要があります。これは、The Things Network V2とThe Things Stack Community EditionのNetwork Serverが使用する推奨設定が異なるためです。

例えば、The Things Network V2で使用されているRxDelayパラメータは、デフォルトでは1秒ですが、The Things Stack Community Editionの推奨値は5秒です。The Things Stack Community Edition Network Serverでは自動的に変更しようとしますが、MACコマンドがエンドデバイスに届くまで時間がかかる場合があります。

MAC設定の方法については、The Things Stack公式ドキュメントをご覧ください。

https://www.thethingsindustries.com/docs/devices/mac-settings/

あなたのゲートウェイを移行

ゲートウェイをThe Things Network V2からThe Things Stack Community Editionのクラスタに移行するのは、とても簡単な作業です。

まず最初に、The Things Stack Community Editionにゲートウェイを追加する必要があります。

https://www.thethingsindustries.com/docs/gateways/adding-gateways/

次に、使用しているThe Things Stack Community Editionのクラスタのアドレスを変更する必要があります。これは、使用しているゲートウェイの種類（Semtech UDP Packet ForwarderまたはLoRa Basics Station）によって異なります。ここでは、eu1.cloud.thethings.networkを使用していると仮定します。

・ Semtech UDP Packet Forwarderを使用している場合は、global_conf.jsonのserver_addressをeu1.cloud.thethings.networkに変更してください。
・ LoRa Basics StationをLNSサブプロトコルで使用している場合は、LNSサーバーアドレスをwss://eu1.cloud.thethings.network:8887に変更してください。
・ LoRa Basics Station を CUPS サブプロトコルで使用する場合は、CUPS サーバーのアドレスを https://eu1.cloud.thethings.network:443 に変更します。

クラスタアドレスを更新すると、ゲートウェイに届いたデータはThe Things Stack V3クラスタにルーティングされるようになります。

以上

■The Things Network - LoRaWANをみんなでシェアして使う　新刊本好評発売中！

Johan Stokking (左 The Things Network TECH LEAD=CTO）とWienke Geizeman （右 The Things Network CEO)

＊工学社新刊本リンク先
↓↓↓↓↓↓↓↓↓↓
https://www.kohgakusha.co.jp/books/detail/978-4-7775-2043-5

◆The Things Network PR Movie【日本語字幕入り】

◆詳細はこちらから....
↓↓↓↓↓↓↓
https://www.thethingsnetwork.org/country/japan/

＊The Things Network販促カタログ
↓↓↓↓↓↓↓↓↓↓
http://www.crijapan.jp/TTN_catalog.pdf

◆※例：Dragino製のゲートウェイの設定方法ですが、他社ゲートウェイもほぼ同じやり方でV2からＶ3に移行できます。
↓
https://wiki.dragino.com/index.php?title=Notes_for_TTN#TTN_v3

TTN V3対応最新版LoRaWANゲートウェイLPS8-JP日本語マニュアル from CRI Japan, Inc.

◆※Dragino LPS8, LG308, DLOS8ともに同じやり方でV3にゲートウェイ登録できます。注記：Draginoゲートウェイ用ファームウェアを更新する場合、現在お使いのファームウェアを必ずFactory Defaultに設定を戻してから更新してください。そのまま新しいファームウェアを更新すると正しく機能しなくなりますのでご注意ください。
↓

◆※万が一、上記のやり方で登録できない場合は、下記のやり方でGateway EUIを登録してみてください。
↓
https://www.thethingsindustries.com/docs/gateways/dragino-lps8/

The Thing Stack V3の機能と説明RevB.pdf from CRI Japan, Inc.

◆What is the Packet Broker? 【日本語字幕入り】

◆Migrating devices to The Things Stack【日本語字幕入り】

TTN V2からTTN V3への移行ハンズオン by TTN高崎イニシエーター/エルスピーナヴェインズ株式会社代表取締役青谷浩二様　 from CRI Japan, Inc.

◆TagoIO Webhook Integration with The Things Stack 【日本語字幕入り】

◆New Device Emulator from TagoIO【日本語字幕入り】

◆Distributing Dashboards with the TagoIO【日本語字幕入り】