Skip to content

Commit fb73239

Browse files
nejraselimovicnejraselimovic
committed
doc: Fix migration docs
1 parent f844865 commit fb73239

3 files changed

Lines changed: 60 additions & 8 deletions

File tree

‎doc/content/getting-started/migrating/migrating-from-v2/migrate-using-console.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ Some OTAA devices ocasionally perform new joins - with these end devices, you ca
105105

106106
{{< tabs/tab "ABP" >}}
107107

108-
For ABP device, you need to completely delete it from {{% ttnv2 %}}, especially if you have not re-programmed it for a new **DevAddr**. Having the same session in {{% ttnv2 %}} and {{% tts %}} would introduce some serious conflicts.
108+
{{< warning >}} For ABP device, you need to completely delete it from {{% ttnv2 %}}, especially if you have not re-programmed it for a new **DevAddr**. Having the device registered in both {{% ttnv2 %}} and {{% tts %}} would introduce some serious conflicts. {{</ warning >}}
109109

110110
{{< /tabs/tab >}}
111111

‎doc/content/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session.md‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,34 @@ This section explains how to export one or more of your end devices from {{% ttn
88

99
<!--more-->
1010

11-
{{< note >}} Migrating end devices without their active session with `ttn-lw-migrate` tool is not applicable to ABP devices. To achieve this, see [how to migrate ABP device to {{% tts %}} using Console]({{< ref "/getting-started/migrating/migrating-from-v2/migrate-using-console" >}}).
11+
{{< info >}} We strongly recommend migrating end devices without persisting active sessions. {{</ info >}}
1212

13-
This section only applies to OTAA devices.{{</ note >}}
13+
{{< tabs/container "OTAA" "ABP" >}}
1414

15-
{{< info >}} We strongly recommend migrating end devices without persisting active sessions {{</ info >}}
15+
{{< tabs/tab "OTAA" >}}
1616

1717
When migrating OTAA devices without persisting active sessions, a new join needs to be performed on {{% tts %}} to establish a new session.
1818

1919
By establishing the new session with {{% tts %}}, an OTAA device gets assigned a new **DevAddr** and default values of some other parameters (like 5 seconds **RX1 Delay**). This ensures that the traffic sent by these end devices can be properly routed by the Packet Broker to and from {{% tts %}}.
2020

21+
{{< /tabs/tab >}}
22+
23+
{{< tabs/tab "ABP" >}}
24+
25+
The **DevAddr** and some other parameters (like **RX1 Delay**) are hardcoded for ABP devices. If you do not re-program the device to change these values, you can migrate it to {{% tts %}} without its security keys, network parameters, etc. which basically means you are migrating it without its active session.
26+
27+
{{< note >}} If you want your end device traffic to be routed via Packet Broker to {{% tts %}}, the **DevAddr** must be routable by the Packet Broker and the **RX1 Delay** value must be 5 seconds. Note that the **DevAddr** is routable only if you are using **The Things Industries V2 (SaaS)** and migrating to **{{% tts %}} Cloud**, and even that is being achieved only on customer request by contacting [The Things Industries support](mailto:[email protected]).
28+
29+
If you are not migrating from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud**, Packet Broker will not be able to route your ABP device's traffic properly, so you will have to [migrate your gateway]({{< ref "/getting-started/migrating/gateway-migration" >}}) to {{% tts %}} too. Be aware that in this case, even if you do migrate your gateway, you could still be experiencing latency issues if your gateway has a high latency backhaul. {{</ note >}}
30+
31+
{{< warning >}} Note that this is **not a recommended practice**. We advise re-programming the ABP device to change the **DevAddr** to the one issued by The Things Stack and **RX1 Delay** to 5 seconds, even if you do not want your traffic to be routed by Packet Broker.
32+
33+
If you re-program the device, you will have to follow the [Migrate using the Console]({{< ref "/getting-started/migrating/migrating-from-v2/migrate-using-console" >}}) guide. The reason for this is that when you re-program your ABP device, its **DevAddr** and other parameters will no longer match the device description stored in {{% ttnv2 %}}, so you will not be able to export the current device description using the `ttn-lw-migrate` tool. {{</ warning >}}
34+
35+
{{< /tabs/tab >}}
36+
37+
{{< /tabs/container >}}
38+
2139
{{< note >}} Before exporting end devices, you can first test the execution by appending the `--dry-run` and `--verbose` flags to the commands presented in the sections below. {{</ note >}}
2240

2341
### Export a Single End Device
@@ -58,14 +76,32 @@ $ ttn-lw-migrate application --source ttnv2 "ttn-v2-application-ID" --ttnv2.with
5876

5977
Exporting end devices without their active sessions does not clear root and session keys on {{% ttnv2 %}}. Hence, you need to prevent your devices from re-joining the {{% ttnv2 %}} network.
6078

79+
{{< tabs/container "OTAA" "ABP" >}}
80+
81+
{{< tabs/tab "OTAA" >}}
82+
6183
To prevent OTAA device from re-joining the {{% ttnv2 %}} network, the recommended practice is to change the **AppKey** in the {{% ttnv2 %}}. By changing the **AppKey**, the existing session on {{% ttnv2 %}} will not be terminated yet, but the end device will not be able to re-join because the {{% ttnv2 %}} cluster will reject its new Join Requests.
6284

85+
{{< /tabs/tab >}}
86+
87+
{{< tabs/tab "ABP" >}}
88+
89+
{{< warning >}} For ABP device, you need to completely delete it from V2, especially because this section assumes that you have not re-programmed it for a new **DevAddr**. Having this device registered in V2 and The Things Stack would introduce some serious conflicts. {{</ warning >}}
90+
91+
{{< /tabs/tab >}}
92+
93+
{{< /tabs/container >}}
94+
6395
## Import End Devices in {{% tts %}} Application
6496

6597
Now that you have exported one or more of your devices to a `devices.json` file, you can continue by importing this file in {{% tts %}} via Console or via CLI.
6698

6799
> See [Import End Devices in The Things Stack]({{< ref "/getting-started/migrating/import-devices" >}}) for detailed instructions on how to do this.
68100
101+
{{< tabs/container "OTAA" "ABP" >}}
102+
103+
{{< tabs/tab "OTAA" >}}
104+
69105
## Let the OTAA End Device Join {{% tts %}} Network
70106

71107
Next, your OTAA end device needs to join {{% tts %}} network. Since you have not migrated your device with its active session, it will need to perform a new join.
@@ -83,3 +119,15 @@ Since we assume that you have not migrated your gateway from {{% ttnv2 %}} yet,
83119
Instead, these Join Requests are going to be routed to {{% tts %}} via Packet Broker and {{% tts %}} will accept them. Your OTAA device will negotiate with {{% tts %}} Network Server to obtain a new **DevAddr**, channel settings and other MAC parameters. The traffic from your end device can from now on be routed to {{% tts %}} thanks to the newly assigned **DevAddr** and **RX1 Delay** of 5 seconds, which fulfills the Packet Broker requirements.
84120

85121
{{< note >}} Even if you manage to get your end device traffic routed to {{% tts %}} via Packet Broker, we still recommend you get in touch with your local The Things Network community and coordinate the migration of gateways, so you do not loose the LoRaWAN network coverage. See how to [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}). {{</ note >}}
122+
123+
{{< /tabs/tab >}}
124+
125+
{{< tabs/tab "ABP" >}}
126+
127+
## Next Step - Migrate Gateways
128+
129+
This section implies that you are keeping the **DevAddr** and **RX1 Delay** values from {{% ttnv2 %}}, which means Packet Broker will be able to route the traffic properly only if you are migrating from **The Things Industries {{% ttnv2 %}}** to **{{% tts %}} Cloud**. This can be only achieved on a customer request, so if this is the case please contact [The Things Industries support](mailto:[email protected]) for more information.
130+
131+
If you are not migrating from **The Things Industries {{% ttnv2 %}}** to **{{% tts %}} Cloud**, please follow the guide to [migrate your gateway]({{< ref "/getting-started/migrating/gateway-migration" >}}) to {{% tts %}}.
132+
133+
{{< note >}} Keep in mind that we advise to keep your gateways on {{% ttnv2 %}} until you get in touch with your local The Things Network community and coordinate the migration of gateways, so you do not loose the LoRaWAN network coverage. {{</ note >}}

‎doc/content/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Starting from {{% tts %}} version `3.12.0`, it is possible to migrate end device
1111

1212
{{< warning >}} Active device sessions can be migrated via Packet Broker only from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud**, and this is achievable only on a customer request. Contact [The Things Industries support](mailto:[email protected]) for more information.
1313

14-
Migrating active sessions from **The Things Network V2** (public community network) to {{% tts %}} deployments is achievable only if you [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}) too. However, we strongly recommend The Things Network community members to keep their gateways registered on The Things Network V2 for as long as possible, or to agree on performing coordinated migration to {{% tts %}}, as this will ensure the community does not loose their LoRaWAN coverage. {{</ warning >}}
14+
For all other scenarios, migrating active session is achievable only if you [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}) too. However, we strongly recommend The Things Network community members to keep their gateways registered on The Things Network V2 for as long as possible, or to agree on performing coordinated migration to {{% tts %}}, as this will ensure the community does not loose their LoRaWAN coverage. {{</ warning >}}
1515

1616
{{< info >}} We strongly recommend migrating end devices without persisting active sessions. {{</ info >}}
1717

@@ -25,7 +25,9 @@ In the case of persisting active sessions during migration, OTAA devices do not
2525

2626
{{< tabs/tab "ABP" >}}
2727

28-
The **DevAddr** and some other parameters (like **RX1 Delay**) are hardcoded for ABP devices. If you do not re-program the device to change these values, you are basically migrating it to {{% tts %}} with its active session.
28+
The **DevAddr** and some other parameters (like **RX1 Delay**) are hardcoded for ABP devices. If you do not re-program the device to change these values, you can migrate it to {{% tts %}} with its active session.
29+
30+
Remember that if you are not migrating specifically from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud**, you will have to [migrate your gateway]({{< ref "/getting-started/migrating/gateway-migration" >}}) to successfully migrate your end device with its active session.
2931

3032
{{< /tabs/tab >}}
3133

@@ -93,6 +95,8 @@ Migrating your ABP device from **The Things Industries V2 (SaaS)** to **{{% tts
9395

9496
{{< /tabs/container >}}
9597

96-
If you are migrating an end device with its active session via Packet Broker, you will need to set the **RX1 Delay** of the device to 5 seconds by [configuring MAC settings]({{< ref "/getting-started/migrating/configure-mac-settings" >}}), otherwise the traffic might not reach {{% tts %}} in time via Packet Broker. You can also leave the **RX1 Delay** value as is (1 second from {{% ttnv2 %}}), but then you will need to [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}) too, but if your gateway has a high-latency backhaul, you could still experience latency issues.
98+
If you are migrating an end device with its active session via Packet Broker, you will need to set the **RX1 Delay** of the device to 5 seconds by [configuring MAC settings]({{< ref "/getting-started/migrating/configure-mac-settings" >}}), otherwise the traffic might not reach {{% tts %}} in time via Packet Broker.
99+
100+
You can leave the **RX1 Delay** value as is (1 second from {{% ttnv2 %}}), but then you will need to [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}) too - keep in mind that if your gateway has a high-latency backhaul, you could still experience latency issues.
97101

98-
If you are not specifically migrating from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud**, you will need to either [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}) in order for session migration to work, or [migrate your device without a session]({{< ref "/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session" >}}).
102+
{{< note >}} Even if you manage to get your end device traffic routed to {{% tts %}} via Packet Broker, we recommend you get in touch with your local The Things Network community and agree on coordinating the migration of gateways, so you do not loose the LoRaWAN network coverage. See how to [migrate your gateway to {{% tts %}}]({{< ref "/getting-started/migrating/gateway-migration" >}}). {{</ note >}}

0 commit comments

Comments
 (0)