Migrate Without Persisting Active Session

This section explains how to migrate end devices from The Things Stack Community Edition to The Things Stack Cloud without persisting sessions that were established between those devices and The Things Stack.

Note on temporarily preserving uplink traffic on The Things Stack Community Edition

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

For a new session to be established between device (that’s connected to The Things Stack Community Edition) 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 Community Edition 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

This way, The Things Stack Community Edition Network Server will not be able to send Join Accept messages, data downlinks or MAC commands anymore. The end device will be triggered to perform a new join on The Things Stack Cloud, but the uplink traffic will still reach The Things Stack Community Edition before device is actually registered on Cloud.

Now, you can proceed with migrating your device. Read the instructions below for your specific device.

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 Community Edition will no longer exist, i.e. uplinks will no longer reach The Things Stack Community Edition, just The Things Stack Cloud.

OTAA

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 Community Edition 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 Community Edition, 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 Community Edition to The Things Stack Cloud without an active session, follow the steps described below.

Console
CLI

Using the Console is covenient only when you have a few devices to migrate. For larger groups of devices, we recommend using the CLI or the migration tool. Migration tool support will be available soon.

Recreate your device on The Things Stack Cloud. See Adding Devices for instructions on creating a device. You can reuse the DevEUI, AppEUI/JoinEUI and AppKey values from The Things Stack Community Edition. 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 Community Edition. See Configuring the CLI guide for instructions. Make sure you also perform a Login with the CLI to The Things Stack Community Edition.

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 Community Edition:

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 Import End Devices 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.

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

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 Community Edition, 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.

ABP

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:

Migrating devices without persisting active sessions is the preferred migration method. For ABP devices, we also advise to re-program the device using session parameters 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 Community Edition 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 Community Edition, 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 Community Edition to The Things Stack Cloud without its active session and by re-programming it is the most straightforward if you use the The Things Stack Console.

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 Community Edition, 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 Community Edition network.

Note that The Things Stack Community Edition 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 Community Edition-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 Community Edition 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.

Console
CLI

Using the Console is covenient only when you have a few devices to migrate. For larger groups of devices, we recommend using the CLI or the migration tool. Migration tool support will be available soon.

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 Community Edition.

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

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

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 Community Edition:

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 Import End Devices 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.

When your device is registered in The Things Stack Cloud, you need to completely delete it from The Things Stack Community Edition 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.

← Migrate Active Device Session