Migrate without Persisting Active Sessions

This section explains how to export one or more of your end devices from V2 to a JSON file, without persisting their session.

Info:
We strongly recommend migrating end devices without persisting active sessions.

When migrating OTAA devices without persisting active sessions, a new join needs to be performed on The Things Stack to establish a new session.

By establishing the new session with The Things Stack, 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 The Things Stack.

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 The Things Stack without its security keys, network parameters, etc. which basically means you are migrating it without its active session.

Note:

If you want your end device traffic to be routed via Packet Broker to The Things Stack, 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 The Things Stack Cloud, and even that is being achieved only on customer request by contacting The Things Industries support.

If you are not migrating from The Things Industries V2 (SaaS) to The Things Stack Cloud, Packet Broker will not be able to route your ABP device’s traffic properly, so you will have to migrate your gateway to The Things Stack 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.

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.

Note:
Use the --ttnv2.resets-to-frequency-plan flag to configure the factory preset frequencies of the device, so that it can keep working with The Things Stack. The list of uplink frequencies is inferred from the Frequency Plan.

If you re-program the device, you will have to follow the Migrate using the 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 V2, so you will not be able to export the current device description using the ttn-lw-migrate tool.

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.

Export a Single End Device

To export a single end device from V2:

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

Export a Batch of End Devices

First, create a text file device_ids.txt. This file needs to contain a V2 Device ID for every end device you want to export from V2.

The format of this file is one Device ID per one line, i.e.:

dev1
dev2
dev3

To export a batch of end devices from V2:

$ ttn-lw-migrate device --source ttnv2 --ttnv2.with-session=false < device_ids.txt > devices.json

Export All End Devices Associated With V2 Application

To export all devices contained in V2 application:

$ ttn-lw-migrate application --source ttnv2 "ttn-v2-application-ID" --ttnv2.with-session=false > devices.json

Prevent the End Device from Joining V2 Network

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

To prevent OTAA device from re-joining the V2 network, the recommended practice is to change the AppKey in the V2. By changing the AppKey, the existing session on V2 will not be terminated yet, but the end device will not be able to re-join because the V2 cluster will reject its new Join Requests.
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.

Import End Devices in The Things Stack Application

Now that you have exported one or more of your devices to a devices.json file, you can continue by importing this file in The Things Stack via Console or via CLI.

See Import End Devices in The Things Stack for detailed instructions on how to do this.

Let the OTAA End Device Join The Things Stack Network

Next, your OTAA end device needs to join The Things Stack network. Since you have not migrated your device with its active session, it will need to perform a new join.

Some OTAA devices ocasionally perform new joins - with these end devices, you can only wait for them to do this on their own.

You could also send a downlink message from the V2 Console to trigger a new join if your device supports this - contact your device maker for detailed instructions.

Some devices are also triggered when power cycled, or when deleted from V2.

Next Step - Migrate Gateways

Since we assume that you have not migrated your gateway from V2 yet, new Join Requests sent by your OTAA device are still being received by the V2 network. However, if you have prevented your device from joining V2 network (as recommended above), these Join Requests are not going to be accepted by the V2 Network Server.

Instead, these Join Requests are going to be routed to The Things Stack via Packet Broker and The Things Stack will accept them. Your OTAA device will negotiate with The Things Stack 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 The Things Stack thanks to the newly assigned DevAddr and RX1 Delay of 5 seconds, which fulfills the Packet Broker requirements.

Next Step - Migrate Gateways

This section implies that you are keeping the DevAddr and RX1 Delay values from V2, which means Packet Broker will be able to route the traffic properly only if you are migrating from The Things Industries V2 to The Things Stack Cloud. This can be only achieved on a customer request, so if this is the case please contact The Things Industries support for more information.

If you are not migrating from The Things Industries V2 to The Things Stack Cloud, please follow the guide to migrate your gateway to The Things Stack.

Note:
Starting from The Things Stack v3.13.0 release, The Things Network community members can freely migrate their gateways from The Things Network V2 to The Things Stack Community Edition, while still providing uplink and downlink coverage to The Things Network V2. Even if you manage to get your end device traffic routed to The Things Stack by Packet Broker, we recommend to migrate your gateways as soon as possible.
← Migrate using the Migration Tool Migrate Active Sessions →