Migrate Active Sessions

Starting from The Things Stack version 3.12.0, it is possible to migrate end devices together with their active sessions using the ttn-lw-migrate tool. This section explains how to export one or more of your end devices from V2 to a JSON file, with persisting their active sessions.

Active device sessions can be migrated via Packet Broker only from The Things Industries V2 (SaaS) to The Things Stack Cloud, and this is achievable only on a customer request. Contact The Things Industries support for more information.

For all other scenarios, migrating active session is achievable only if you migrate your gateway to The Things Stack too.

Note:
We strongly recommend migrating end devices without persisting active sessions.
In the case of persisting active sessions during migration, OTAA devices do not need to perform a new join on The Things Stack network, but their existing session will be transferred from V2.
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 with its active session.

Remember that if you are not migrating specifically from The Things Industries V2 (SaaS) to The Things Stack Cloud, you will have to migrate your gateway to successfully migrate your end device with its active session.

Warning:
Exporting end devices with their active sessions will clear their root and session keys from V2, so these devices will automatically no longer work on V2.

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.

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.

Export a Single End Device

To export a single end device from V2 and clear its security keys:

ttn-lw-migrate device --source ttnv2 "v2-end-device-ID" > 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 and clear their security keys:

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

Export All End Devices Associated With V2 Application

To export all devices contained in V2 application and clear their security keys:

ttn-lw-migrate application --source ttnv2 "ttn-v2-application-ID" > devices.json

Add end devices in bulk 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 add end devices in bulk in The Things Stack for detailed instructions on how to do this.

Next Step - Migrate Gateways

Migrating your OTAA device from The Things Industries V2 (SaaS) to The Things Stack Cloud with its active session means it will keep its DevAddr, channel settings and MAC parameters from V2. It will not send new Join Requests, but the uplink traffic from your device should automatically show up in The Things Stack, because it will be routed via Packet Broker thanks to preserving your device’s existing session.
Migrating your ABP device from V2 to The Things Stack with its active session means it will keep its DevAddr, channel settings and MAC parameters from V2, i.e. the existing session will be preserved.

If you are migrating an end device with its active session via Packet Broker (from The Things Industries V2 to The Things Stack Cloud), you might need to set the RX1 Delay of the device to 5 seconds by configuring MAC settings, otherwise the traffic might not reach The Things Stack in time via Packet Broker.

In case you want to leave the RX1 Delay value as is (1 second from V2), you will need to migrate your gateway to The Things Stack too.

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.

Note:
If you have migrated your device from V2 to The Things Stack with an active session but cannot see any uplinks from the device on The Things Stack, see Troubleshooting Devices.
← Migrate without Persisting Active Sessions