The Things Network (V2)からThe Things Stack (V3)へ設定や環境を移行する


## How to migrate from The Things Network V2 to The Things Stack (V3)

この記事は2021年9月あたりに書いています。

今年4月に久しぶりにTTN（The Things Network）にアクセスしたところ、V3に移行する必要があり、2021年12月末にはV2にもアクセスできなくなる旨が警告されていたため、移行作業をしました。

そのため、今後のメモを兼ねて移行に必要な作業や、V2の情報との比較のために記事にしておきます。

## やること

* The Things Network (V2) からThe Things Stack Community Edition (V3)に移行します
    * TTNは無料で利用できましたが、TTSはCommunity Editionのみ無料で利用できます
    * 商用利用などは別のプランがあるのでそちらを調べてみてください

以下に大雑把なV2からV3（The Things Stack Community Edition）への移行方法が掲載されているので、一緒に参考にしてください。

**"Migrate from The Things Network V2 to The Things Stack"**

https://www.thethingsnetwork.org/docs/the-things-stack/migrate-to-v3/

CRI Japanさん以下の記事も必要に応じて確認してみてください。

http://joomlaweb.blog117.fc2.com/blog-entry-1915.html

## 移行の全体イメージ

V2とThe Things Stack Community Edition(V3)の移行はこんなイメージです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/aa8f07f9-15ac-a3e4-e1e8-4bcc48b5f59f.png)

以下、移行をする順番です
（TTN IDでThe Things Stack Community Edition(V3)へログイン済みとします）

1. 新規アプリケーションを作成
2. Integrationの設定を移行&Integration先の設定を変更
3. End Device（Application上に登録されているデバイス）を移行
4. Gatewayを移行
5. Gatewayの設定を変更
6. 動作テスト

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/450acdff-c209-0c3b-3df3-5bd86e7dbdef.png)

## 移行手順

### 1. 新規アプリケーションを作成

V2に登録済みのアプリケーション情報を参考に、The Things Stack Community Edition(V3)で新規でアプリケーションを作成します。

>
 To migrate your end device, you first need to add an application on the The Things Stack Community Edition. The Application ID does not neccessarily have to be the same as the one in The Things Network V2.
（訳：移行にあたってまずはThe Things Stack Community Edition(V3)で新たにアプリケーションを作成します。アプリケーションIDは必ずしもV2と同じである必要はありません）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/7750078f-5df2-75ee-3ab5-b1a16e006cf6.png)

### 2. Integrationの設定を移行&Integration先の設定を変更

Azureなど、他のサービスとの連携設定（インテグレーション）がある場合は、これも移行する必要があります。

The Things Stack Community Edition(V3)におけるアプリケーションの以下のメニューから好きなインテグレーションを追加します。こんなに豊富になっているなんて驚きました。今後Azure連携とAWS連携など色々試してみたいですね。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/a003e731-e335-cf9f-60b0-f89c019c18cc.png)

元々、私はHTTP WebhookでAzure Functionsにデータを投げていたので、とりあえずそのままシンプルなWebhookを作成しました。

新たにLoRaWANメッセージのアップリンクとダウンリンク、その他細かくパスを追加できるようになっていますが、一旦アップリンクメッセージだけ有効化しておきます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/173b86ed-7f70-4ad7-1885-5b09bdee203e.png)![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/1426b943-31bc-094c-086d-c8208563baff.png)


ちなみに、TTNからHTTPで渡されるJSONのフォーマットが大きく変わっているので、以下の仕様を確認して、後からテストをしつつデバッグしておきます。

https://www.thethingsindustries.com/docs/reference/data-formats/

私はAzure Functionsにデータを流していたのですが、そのままAPIの送信先を設定してもThe Things Stack Community Edition(V3)からのJSONフォーマットが大きく異るので動作しませんでした・・・。そのため、上記の仕様を確認して一部受け取ったデータをパースするプログラムをアップデートしました。

（詳細は省略していますが、仕様に合わせるのがけっこう大変でした。。）

### 3. End Device（Application上に登録されているデバイス）を移行

元々のV2ではアプリケーションにそれぞれのDeviceが追加されていましたが、先程作成したアプリケーションへこれらのDeviceを移行します。

以下を参考に移行＆登録作業を行います。
※今回はABPモードで動作するデバイスを移行します。OTAAが推奨されていますが・・・。

https://www.thethingsnetwork.org/docs/the-things-stack/migrate-to-v3/migrate-using-console/

まず先程作成したThe Things Stack Community Edition(V3)のアプリケーションを開いて、「エンドデバイス」を選択して、登録を開始します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/2acc0137-08e7-de64-8456-836a62b02fe6.png)

各項目について、以下を参考に設定します

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/d51bde39-727d-e48e-7327-7d0319ef85af.png)

- LoRaWANバージョン
    - MAC V1.0.2
- 地域パラメータのバージョン
    - PHY V1.0.2 REV B
- 周波数プラン
    - Asia 920-923 MHz
- アクティベーションモード
    - ABP/OTAAのいずれか（私はABPモードで動作させています）
- Addition LoRaWAN class capabilities
    - None (class A only)
- DevEUI
    - V2の設定を移行
- デバイスアドレス
    - V2の設定を移行
- AppSKey
    - V2の設定を移行
- NwkSKey
    - V2の設定を移行

一部の設定は、デバイス作成後しか変更ができないため、一旦保存し、デバイスを作成します。

作成したデバイスを開き、「一般設定」タブ＞「ネットワークレイヤー」＞「Advanced MAC Settings」を開きます。

※「Advanced MAC Settings」の文字が非常に小さいので注意してください。

さらに、以下の項目について変更または確認を行います

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/c2712267-f906-9a6d-40f0-f1e9a7bec321.png)


- フレームカウンター幅
    - 32bit
- RX1遅延
    - 1(※1)
- RXデータレートオフセット
    - 0
- フレームカウンターのリセット
    - 有効化にチェック(リプレイ攻撃の懸念が高まるため自己責任で)
- RX2データレートインデックス
    - 3 (ABPでは関係なさそうなのでEU868の設定値に揃えておきます)
- RX2周波数
    - 923200000(※2)
- 工場出荷時のプリセット周波数
    - 923200000(※2)

これで一旦デバイスの移行設定は完了です。デバイス本体の設定値を変える必要はありません。

**移行が完了し、設定値に間違いがないことを確認したら、V2のデバイスを削除することをおすすめします（V2に登録されている情報とコンフリクトが発生してバグってしまうため。。）**

#### ※1「RX1遅延」の設定について
「RX1遅延」には公式サイトの以下のNoteを参考に設定します。**移行にあたって非常に重要**でした。

この「RX遅延」には2パターンの設定値が考えられると記載があります。

>Note: 
The DevAddr and RX1 Delay values depend on your specific use case.

>Case 1: You want your ABP device’s traffic to be routed to The Things Stack Community Edition by Packet Broker, i.e. you do not want to migrate your gateway to The Things Stack Community Edition at this time.

>In this case, you need to auto-generate a new DevAddr and a new NwkSKey when adding the ABP device on The Things Stack Community Edition. After that, you will have to re-program your ABP device with new DevAddr and NwkSKey values, and an RX1 Delay of 5 seconds. This will make sure that your device’s DevAddr can be properly routed by Packet Broker, and that its traffic will reach The Things Stack Community Edition in time.

>Keep in mind that even if you are planning to migrate your gateway right after, it is recommended to re-program your device to use the newly generated DevAddr, and the RX1 Delay of 5 seconds which is a default for The Things Stack Community Edition.

ケース1：Packet Brokerを利用する場合は"5秒"に設定します。

Packet Brokerを経由するため少し時間がかかってしまうようです。

ちなみにPacket Brokerは、TTN V2にGatewayを残したまま、The Things Stack Community Edition(V3)へ一時的に接続して、Deviceから受信したパケットをThe Things Stack Community Edition(V3)へ流す事ができるものです。本来の用途は、複数のLoRaWANネットワークを仲介するための仕組みです（以下参照）。

https://www.thethingsindustries.com/docs/getting-started/packet-broker/

>Case 2: You want to migrate your gateway to The Things Stack Community Edition right after you migrate your device.

>If this is the case, you do not have to re-program your ABP device. You can add the ABP device in The Things Stack Community Edition using the same DevAddr and RX1 Delay of 1 second as it was on The Things Network V2.

>However, be aware that we recommend to re-program the device. Even if you migrate your gateway to The Things Stack Community Edition, you could be experiencing issues when using the RX1 Delay of 1 second if your gateway has a high-latency backhaul.

ケース2：ゲートウェイをV2からThe Things Stack Community Edition(V3)に移行する場合は"1秒"に設定します

#### ※2「RX2周波数」「工場出荷時のプリセット周波数」について
日本で、特に今回私はAS920（Asiaの920MHz - 923MHzを利用すること）を設定しているので、以下のページを参考に設定します

https://www.thethingsnetwork.org/docs/lorawan/frequency-plans/

上記サイトより、「RX2周波数」は以下を設定します。

```
Downlink:
Uplink channels 1-10 (RX1)
923.2 - SF10BW125 (RX2)
```

923.2MHz = 923200000 Hz ですね

「工場出荷時のプリセット周波数」は、AS920の場合は920MHz - 932MHzの以下から適当に選択すればいいと思います。

```
923.2 - SF7BW125 to SF12BW125
923.4 - SF7BW125 to SF12BW125
922.2 - SF7BW125 to SF12BW125
922.4 - SF7BW125 to SF12BW125
922.6 - SF7BW125 to SF12BW125
922.8 - SF7BW125 to SF12BW125
923.0 - SF7BW125 to SF12BW125
922.0 - SF7BW125 to SF12BW125
922.1 - SF7BW250
921.8 - FSK
```


### 4. Gatewayを移行

以下を参考に、V2に登録されているGatewayをThe Things Stack Community Edition(V3)へ移行します。

https://www.thethingsnetwork.org/docs/the-things-stack/migrate-to-v3/migrate-gateways/

まずは、**V2に登録されているGatewayと同じEUIを持ったゲートウェイ**をThe Things Stack Community Edition(V3)で作成します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/5d08b53a-947d-0d5f-1ce7-cc719cc31275.png)


ここで、新しく作成したゲートウェイサーバのアドレスをメモしておきます。

> ゲートウェイサーバのアドレス　eu1.cloud.thethings.network

一旦これでGatewayの移行準備はできました。こっちは簡単ですね。

### 5. Gatewayの設定を変更

次に、実機のGatewayを起動してglobal.jsonを編集します。
（TTN v2を利用していたのであればglobal.jsonの説明は不要だと思います）

global.jsonの一番下に"gateway_conf"の欄があるので、先程のゲートウェイサーバのアドレスに書き換えます。一応global.jsonを以下に貼っておきます。

https://gist.github.com/himitu23/8d70c5a8c0838c3bde608cb5219a1de1

これで、V2にはパケットが流れなくなり、GatewayはThe Things Stack Community Edition(V3)に接続されるようになったはずです。

Gatewayのプログラムを再起動したらThe Things Stack Community Edition(V3)のライブデータに接続された旨が表示されました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/d948ec00-5a9a-c542-6089-3ed026b77199.png)

上記の表示が出ない場合は、アドレスが間違っている可能性があるので確認してみてください。

### 6. 動作テスト

今回、テストは以下の方法と順番で行います。

- ①Azure FunctionsからSlackへの通知テスト
    - TTN V3のデータフォーマットに対応できているか
- ②Uplink SimulatorからSlackへの通知テスト
    - TTN V3 Integrationが動作しているか（API先にデータを送信できているか）
    - TTN V3のデータフォーマットに対応できているか
- ③実デバイスからSlackへの通知テスト
    - End Deviceの認証情報（NwkSKey, AppSKeyなど）が正しく設定されているか、移行されているか
    - GatewayをV3に移行できているか

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/327b362c-61a8-1171-14de-492a4a825e50.png)

#### ①Azure FunctionsからSlackへの通知テスト

これは私の環境だけなので関係ない人は飛ばしてください。

私は元々TTN IntegrationでAzureFunctionsを使ってSlackへ通知を行っていたため、新しいData Formatに対応するように設定を変更します。

（参考記事）

https://qiita.com/_tokina23/items/7e5d3d0ed907912ab303

新しいJSONのデータフォーマットに合わせて動作させてみたところ、問題なく動作していることが確認できました。

Azure Functionsへ流したテストデータは、公式ページに書いてある例を参考に作成しました。一応以下に貼っておきます。

https://gist.github.com/himitu23/71fd06faf9d5789cce69ed86eea0d434

Azure Functionsへ新しいデータフォーマットを流して、Slackへ通知させた様子です。新しくAirtimeなどが取れるようになってていい感じです。ついでに、Gatewayの位置情報と、GoogleMapのリンクも作成するようにしました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/19f780ba-bfab-6824-e079-43f992e5276a.png)

#### ②Uplink SimulatorからSlackへの通知テスト

TTNにはV2のときから、実際にインテグレーションの動作確認のためにLoRaWANのアップリンクとダウンリンクそれぞれのシミュレーション機能が存在します。

①の動作確認済みの状態で、以下のアプリケーション>デバイス>メッセージングの画面で「アップリンクのシミュレーション」を行ってみます。
※実際にここで送信されるJSONのデータフォーマットは、先程テストしたデータのデータフォーマットの一部がかけている状態なのでエラーが出る場合があるので注意してください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/02774fbf-d5fe-e630-4e15-80b04d4c3b49.png)

Slackへの通知は以下のようになりました。アップリンクシミュレーションにはチャネル情報や周波数情報が入ってないので少しシンプルです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/553d4ca1-0817-09c6-b9ef-61adecf7f00e.png)

#### ③実デバイスからSlackへの通知テスト

:::note warn
念のため実機の動作確認は、V2に登録済みのデバイスを「削除」してから行いましょう
:::

OTAAを移行する際に削除せずに試したところ、V2のデバイスの画面で表示ができなくなってしまいました。結局デバイス側の設定を書き換えてABPに一度変更するなどの作業が必要になってしまいました。。

ABPでもV2登録済みの場合、V2側がおかしくなったのでABP/OTAAどちらの場合もV3で動作を確認するまえに各種情報を控えた後、一旦削除したほうが良さそうです。

V2の設定はReadOnlyになっているので、V2の設定の一部だけを書き換えるといった事はできないので慎重に。

ゲートウェイやアプリケーションの「ライブデータ」で通信ログができるので、適宜確認してデバッグしましょう。上手くいくと以下のような感じで確認できるはずです（ゲートウェイにはもしかしたら自身以外のデバイスから受信したログも出力されるかもしれません）。

![スクリーンショット 2021-08-18 043322.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/ee8b9612-d27d-5926-4877-afd947d4c5a4.png)

* ゲートウェイのライブデータにデバイスから送信されたデータを受信できていない場合
    * ゲートウェイのglobal_config.jsonのMQTTデータ送信先が間違っている
    * たまたま送信した際の周波数と受信の周波数が噛み合っていない、復号できない（チャネルホッピングの仕様）
* ゲートウェイのライブデータにデバイスから送信されたデータを受信しているが、アプリケーションのライブデータに表示されない場合
    * アプリケーションのEnd Deviceの設定（NwkSKeyや周波数、Regionなど）が間違っている
    * V2に設定が残ったままになっている
    * End Deviceのカウンターチェックが有効になっており、カウントが初期化されている
   
実行に成功するとSlackへ通知が来ました。

![スクリーンショット 2021-08-18 043345.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/54e1a91f-5ea5-a364-0d4a-b056af71a796.png)

## 最後に

今回、久しぶりにTTNを利用しようとしたところ、以下のメッセージが...

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/211407/2c1bc0ec-3107-45e3-9815-c5c3913cec1b.png)

The Things Stackが発表されて2年程度経過しましたが、急にV2に移行する必要があるとのことで焦りました。一旦移行は問題なくできたのですが、まちなかに設置されているデバイスの多くはまだV2だと思いますので、まだ移行していない人は急いで移行しましょう。じゃないと、LoRaWANのメリットである「パブリックネットワーク」が享受できないので。。

もし、本記事が参考になったのであればコメントいただければ幸いです。

また何かLoRaWANに関してネタやアップデートがあれば記事にします。

個人的にやはりClass B, Class Cを試してみたいですけどね、どうなんでしょうか。調べてないですが対応製品は今結構あるらしいですね。

ちなみにABPよりOTAAのほうが推奨されているのは重々承知なので、ご容赦ください。。

## （おまけ）The Things Stackで出てくる用語

* The Things Stack とは
    * Open Source LoRaWAN Networkで、Class A, B, Cに対応しています
    * もともとThe Things Networkという無償で利用できるプラットフォームはThe Things StackのCommunity Editionとなりました
* Class A
    * 「いつでも好きなときに」LoRaWANデバイスからデータを送信する仕様です
    * ダウンリンクなしの送るだけ：ABP
    * ダウンリンクありの双方向：OTAA
* Class B
    * 「サーバからのビーコンを受信したときに」LoRaWANデバイスからデータを送信できる仕様です
    * サーバから定期的にビーコンを受信する必要があるため消費電力は大きくなります
* Class C
    * 「いつでもメッセージを受信できる」仕様です
    * 送信するタイミングは自由です
    * もちとん消費電力は一番大きいです
* Packet Broker　とは
    * 複数のLoRaWANネットワークを仲介するためのThe Things Stackの仕組みです
    * V2のゲートウェイの設定をどうしても変更できない場合や、その他のサービスとの連携に利用できそうです