Migrate Without Persisting Active Session

This section explains how to migrate end devices from The Things Stack Sandbox to The Things Stack Cloud without persisting sessions that were established between those devices and The Things Stack Sandbox. This is the way to go if you cannot migrate your gateway from The Things Stack Sandbox to The Things Stack Cloud.

Note:

Migrating devices without persisting active sessions is the preferred migration method.

Note on temporarily preserving uplink traffic on The Things Stack Sandbox

In this section, we consider migrating your devices in cases when you don’t want to migrate your gateway from The Things Stack Sandbox to The Things Stack Cloud, or when your gateway is inaccessible for this migration. In those cases, devices are migrated from The Things Stack Sandbox to The Things Stack Cloud without persisting their active session, i.e. devices need to establish a new session with The Things Stack Cloud in order for a gateway (that wasn’t migrated from The Things Stack Sandbox) to be able to route traffic from those devices to The Things Stack Cloud. More information about this is available in subsections below.

For a new session to be established between device (that’s currently connected to The Things Stack Sandbox) and The Things Stack Cloud, device has to perform a join procedure to register on The Things Stack Cloud. In order not to lose any uplink traffic during this join procedure, we suggest to disable scheduling downlink messages on The Things Stack Sandbox Network Server using the following CLI command:

ttn-lw-cli dev set --application-id <app-id> --device-id <device-id> \
    --mac-settings.schedule-downlinks=false

When the end device gets triggered to perform a new join on The Things Stack Cloud, the uplink traffic will still reach The Things Stack Sandbox until device is actually registered on Cloud. Using the command above, we make sure that we disable The Things Stack Sandbox Network Server to send Join Accept messages, data downlinks or MAC commands to device, i.e. we make sure that device doesn’t get re-registered on The Things Stack Sandbox, but registered on The Things Stack Cloud.

Note:

The migration tool does this automatically when migrating devices so you don’t need to worry about disabling the downlinks of exported devices.

Now, you can proceed with migrating your device. Read the instructions below to migrate your OTAA or ABP devices.

When your device is finally migrated, it will be assigned with a DevAddr issued by The Things Stack Cloud, so the old session between device and The Things Stack Sandbox will no longer exist, i.e. uplinks will no longer reach The Things Stack Sandbox, just The Things Stack Cloud.

Migrate OTAA Devices

Migrating an OTAA device without persisting its active session means the device will establish a new session with The Things Stack Cloud, i.e. it will have to perform a new join on The Things Stack Cloud network after migration. The device will negotiate about network parameters with The Things Stack Cloud Network Server, and during that negotiation, the device will be assigned with a new DevAddr from The Things Stack Cloud DevAddr block.

Since The Things Stack Sandbox and The Things Stack Cloud are both connected to Packet Broker, Packet Broker will be able to route your device’s traffic to The Things Stack Cloud even if your gateway stays connected to The Things Stack Sandbox, i.e. you don’t have to migrate your gateway to The Things Stack Cloud, only your device. However, if you want to migrate your gateway to The Things Stack Cloud too, see Migrating Gateways for instructions.

To migrate your OTAA device from The Things Stack Sandbox to The Things Stack Cloud without an active session, choose your preferred method and follow the steps described below.

Migration tool
Console
CLI

For detailed instructions on how to configure the migration tool before exporting your device and how to adjust the following command for migrating multiple devices or whole applications, head over to Export Devices from The Things Stack.

To export device using the migration tool without persisting active session, use the --tts.no-session flag:

ttn-lw-migrate device --source tts 'my-device' --tts.no-session > devices.json

Next, you need to import the devices.json file in your The Things Stack Cloud application. See instructions on how to add end devices in bulk in The Things Stack. Keep in mind that if you are using the CLI to import devices, you have to configure it to connect to The Things Stack Cloud. See Configuring the CLI guide for instructions.

The process of migrating OTAA devices using the migration tool ends here and you can ignore the info below the line.

Using the Console is convenient only when you have a few devices to migrate. For larger groups of devices, we highly recommend using the migration tool or CLI.

First step is to recreate your device on The Things Stack Cloud through the Console. See Adding Devices for instructions on creating a device. You can reuse the DevEUI, AppEUI/JoinEUI and AppKey values from The Things Stack Sandbox. You can also generate new values for these parameters on The Things Stack Cloud, but then you will need to re-program your OTAA device using those values.

First, configure your CLI to connect to The Things Stack Sandbox. See Configuring the CLI guide for instructions. Make sure you also perform a Login with the CLI to The Things Stack Sandbox.

Note:

We recommend to use the latest version of the CLI. Instructions for upgrading the CLI if you already have it installed are available in the Installing the CLI guide.

Now, use the CLI to export your device’s description from The Things Stack Sandbox:

ttn-lw-cli end-devices get --application-id <app-id> --device-id <device-id> \
    --name \
    --description \
    --lorawan-version \
    --lorawan-phy-version \
    --frequency-plan-id \
    --supports-join \
    --root-keys \
    --mac-settings > device-description.json

The command above will export your device’s description to the device-description.json file in the current folder. Open the file with a text editor and remove the following fields: join_server_address, network_server_address and application_server_address.

Next, you need to import the device-description.json file in your The Things Stack Cloud application. See instructions on how to add end devices in bulk in The Things Stack. Keep in mind that if you are using the CLI to import devices, you first have to re-configure it to connect to The Things Stack Cloud. Again, see Configuring the CLI guide for instructions.

When your device is registered in The Things Stack Cloud, you need to prevent it from re-joining The Things Stack Sandbox network. To do so, you can change your OTAA device’s AppKey on The Things Stack Sandbox (under device’s General settings → Join Settings → AppKey) or completely delete your device from The Things Stack Sandbox.

Finally, your device needs to perform a new join on The Things Stack Cloud network. Some OTAA devices will perform an automatic re-join after they are deleted from The Things Stack Sandbox, but some devices need to be triggered, e.g. by sending a downlink to it, by power cycling it, etc. You should see a Join Request from your device coming in The Things Stack Cloud.

After joining The Things Stack Cloud network, you will see uplinks arriving from your device.

Migrate ABP Devices

Migrating an ABP device without persisting its active session means its session and MAC state parameters will be reset, or the device will be completely re-programmed with new session parameters.

Note:

For ABP devices, we advise to re-program the device using session parameters that are newly generated on The Things Stack Cloud, if possible. For devices that can be re-programmed, it is also recommended to change their activation method from ABP to OTAA.

Let’s first assume that you are able to re-program your ABP device with new DevAddr, NwkSKey and AppSKey issued by The Things Stack Cloud.

Since The Things Stack Sandbox and The Things Stack Cloud are both connected to Packet Broker, and your ABP device will be re-programmed with a new DevAddr from The Things Stack Cloud DevAddr block, Packet Broker will be able to route your device’s traffic to The Things Stack Cloud even if your gateway stays connected to The Things Stack Sandbox, i.e. you don’t have to migrate your gateway to The Things Stack Cloud, only your device. However, if you want to migrate your gateway to The Things Stack Cloud too, see Migrating Gateways for instructions.

The process of migrating your ABP device from The Things Stack Sandbox to The Things Stack Cloud without its active session by re-programming it is the most straightforward if you use the The Things Stack Console.

First create a new ABP device on The Things Stack Cloud. See Adding Devices for instructions on creating a device. Generate new DevAddr, AppSKey and NwkSKey values while creating the device.

Now re-program your ABP device with newly created DevAddr, AppSKey and NwkSKey values from The Things Stack Cloud. You should immediately see uplinks arriving from your device to The Things Stack Cloud.

However, if you don’t want to re-program your device, i.e. you want to keep the DevAddr, AppSKey and NwkSKey from The Things Stack Sandbox, read the instructions below.

Now let’s assume that you want to migrate your ABP device to The Things Stack Cloud in such manner that it keeps its DevAddr, NwkSKey and AppSKey it was programmed with upon its registration on The Things Stack Sandbox network.

Note that The Things Stack Sandbox and The Things Stack Cloud use different DevAddr blocks. Since Packet Broker routes traffic according to the DevAddr blocks, in this case it won’t be able to route your device’s traffic properly, because of the The Things Stack Sandbox-related DevAddr. To successfully migrate your ABP device while keeping these parameters, you also need to migrate your gateway to The Things Stack Cloud. See instructions for Migrating Gateways. The ideal scenario would be to migrate your gateway and your device simultaneously.

To migrate your ABP device with preserving its DevAddr, NwkSKey and AppSKey, from The Things Stack Sandbox to The Things Stack Cloud, follow the steps described below. Keep in mind that the existing session will be violated because you will need to reset frame counters for your device, hence we refer to this as migrating without an active session.

Migration tool
Console
CLI

For detailed instructions on how to configure the migration tool before exporting your device and how to adjust the following commands for migrating multiple devices or whole applications, head over to Export Devices from The Things Stack.

To export devices using the migration tool without persisting active session, use the --tts.no-session flag:

ttn-lw-migrate device --source tts 'my-device' \
    --tts.no-session > devices.json

Next, you need to import the devices.json file in your The Things Stack Cloud application. See instructions on how to add end devices in bulk in The Things Stack. Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to The Things Stack Cloud. See Configuring the CLI guide for instructions.

You will also need to reset your ABP device.

When your device is finally registered in The Things Stack Cloud, you need to completely delete it from The Things Stack Sandbox network to prevent conflicts. You can do this by running the following command with --tts.delete-source-device flag:

ttn-lw-migrate device --source tts 'my-device' \
    --tts.delete-source-device

Using the Console is covenient only when you have a few devices to migrate. For larger groups of devices, we highly recommend using the migration tool or the CLI.

First, recreate your device on The Things Stack Cloud. See Adding Devices for instructions on creating a device. Reuse the DevEUI, DevAddr, AppSKey and NwkSKey values from The Things Stack Sandbox.

Navigate to General settings → Network Layer → Advanced MAC settings and enable the Resets frame counters option.

When your device is registered in The Things Stack Cloud, you need to completely delete it from The Things Stack Sandbox network to prevent conflicts. You will also need to reset your ABP device.

First, configure your CLI to connect to The Things Stack Sandbox. See Configuring the CLI guide for instructions. Make sure you also perform a Login with the CLI to The Things Stack Sandbox.

Note:

We recommend to use the latest version of the CLI. Instructions for upgrading the CLI if you already have it installed are available in the Installing the CLI guide.

Now, use the CLI to export your device’s description from The Things Stack Sandbox:

ttn-lw-cli end-devices get --application-id <app-id> --device-id <device-id> \
    --name
    --description
    --lorawan-version \
    --lorawan-phy-version \
    --frequency-plan-id \
    --supports-join \
    --root-keys \
    --mac-settings \
    --session.dev-addr \
    --session.keys > device-description.json

The command above will export your device’s description to the device-description.json file in the current folder. Open the file with a text editor and remove the following fields: join_server_address, network_server_address and application_server_address. Also, set the mac-settings.resets-f-cnt field value to true.

Next, you need to import the device-description.json file in your The Things Stack Cloud application. See instructions on how to add end devices in bulk in The Things Stack. Keep in mind that if you are using the CLI to import devices, you first have to re-configure it to connect to The Things Stack Cloud. Again, see Configuring the CLI guide for instructions.

When your device is registered in The Things Stack Cloud, you need to completely delete it from The Things Stack Sandbox network to prevent conflicts. You will also need to reset your ABP device.

If you also migrated your gateway, you will immediately see uplinks arriving from your device.

← Migrating End Devices between The Things Stack distributions Migrate Active Device Session →