Migration from V2 to V3 on TheThingsNetwork
About LoRa & LoRaWAN
IoT devices and sensors must be connected to a network for their data to be utilised. An example of such a network is Long Range Wide Area Network (LoRaWAN). Since IoT comes with a wide range of sensors, actuators and smart objects, it is also essential that protocols exist to connect them. Therefore, every IoT development follows a certain criteria to select the type of network to be used alongside the related protocols. Most of the time, the criteria looks at the following:
1. Range — the distance the network to be used can cover.
2. Frequency bands — this looks at the spectrum that can be used to transmit the data. Is it licensed or unlicensed?
3. Power consumption — this is a major consideration for IoT devices which looks at whether the devices are powered through the mains or a battery.
4. Topology — this is the layout of the network to connect multiple objects
5. Constrained devices — This section details the limitations of certain smart objects.
6. Constrained-Node networks — This looks at the challenges often encountered with networks connecting the IoT devices.
While there exists a plethora of network technologies to select from in connecting the IoT devices, our approach for a scalable technology that can cover longer distances with low power requirements under unlicensed spectrum is LoRaWAN which falls under the category of unlicensed Low Power Wide Area Networks (LPWANs). LoRaWAN is in the sub-GHz band for most countries (Kenya and most African countries use 868 MHz just like Europe, Middle East and Russia. Other countries such as the USA use 915 MHz while China provisioned 779–787 MHz for it) — all of these are under the Industrial, Scientific and Medical (ISM) bands.
LoRa is a physical layer technology, originally developed by Cycleo (a French company) and later on acquired by Semtech. It is optimised for long-range, two-way communications and low power consumption. LoRaWAN is a protocol that was established by the LoRa Alliance to broaden the scope of Layer 1’s driven LoRa. Semtech LoRa as a Layer 1 PHY modulation technology is available through chipset vendors. To differentiate between the physical layer modulation — LoRa and LoRaWAN, the LoRa Alliance uses the term LoRaWAN to refer to its architecture and its specifications that described end-to-end LoRaWAN communications and protocols. Fig.1 shows the LoRaWAN layers — Semtech is responsible for the physical layer while the LoRa Alliance takes care of the MAC layer and the frequency bands associated by the various regions. In general, the LoRa Alliance owns and manages the roadmap and technical development of the LoRaWAN architecture and protocol.
Integration to the ThingsNetwork
Understanding LoRa gateways is critical to understanding a LoRaWAN system. A LoRa gateway is deployed as the centre hub of a star network architecture. It uses multiple transceivers and channels and can demodulate multiple channels at once or even demodulate multiple signals on the same channel simultaneously. The gateways serve as a point of convergence between the LoRa devices or nodes and the devices communicate through the wireless radio interface to the gateways. The data rate in LoRaWAN varies based on frequency bands and the adaptive data rate (ADR). ADR is an algorithm that manages the data rate and radio signal for each node. The algorithm ensures that packets are delivered at the best data rate possible for optimal network performance. Closer nodes tend to use lower power than the distant nodes and are guaranteed of a higher data rate of transmission at a shorter time. An important feature of LoRa is its ability to handle various data rates via the spreading factor (SF). Devices with a low SF achieve less distance in their communication and transmit at faster speeds, resulting in less airtime. On the other hand, devices with a higher SF provides slower transmission rates but achieves higher reliability at longer distances.
In comes TheThingsNetwork (TTN). The TTN is a global, open network that has been built through IoT collaborations led by the teams in Europe. TTN is a major contributor to the LoRa Alliance, which as introduced in the foregoing section, is a non-profit association of more than 500 member companies, committed to enabling large-scale deployment of Low Power Wide Area Networks (LPWAN) IoT through the development and promotion of the LoRaWAN open standard. While the nodes make use of the LoRaWAN radio interface to connect to the Gateway, the Gateways use high bandwidth networks like WiFi, Ethernet or Cellular to connect to TTN, if one adopts it as a network server. This architecture is shown in Fig 2.
In the Things Conference of 2021, TheThingsNetwork announced that it will be upgrading to the The Things Stack V3 from the current TTN V2. TTN has hence called the upgrade — V3 cluster. While the upgrade is not as straightforward to enable the maker community and TNN-using companies to migrate, the details of the need for migration are comprehensively provided by the Tech Lead of the TheThingsNetwork — Johan Stokking here. In this article, we share how one can easily migrate to the V3 cluster. At Tungana, we have already migrated to the new cluster and our gateways are available for use in different communities.
The Things Stack V2 is the earlier TTN console accessible through this link while The Things Stack V3 is the latest console accessible through this link. Please note that, as opposed to V2, to log onto V3, one uses TheThings ID, which has to be created.
Migrating the Gateway
Set up the gateway on the console of the TTN V3. Necessary details are — Gateway ID, Gateway EUI, Frequency Plan and the Location. Similar to V2, these details are just typed in. For the frequency plan, it is great to check the information provided on this link. The same should be referenced when migrating the devices. Once you have entered the necessary information for the gateway (ID, EUI and Frequency Plan are the most important at this stage).
After filling in the above information, enter the location information for your gateway (latitude, longitude and altitude). For the iC880a gateway connected to the raspberry pi, download the global_conf.json from the V3 console. You will replace your existing global_conf.json file with this one. Also, ensure you change the server information of your EUI.json from router.eu.thethings.network to eu1.cloud.thethings.network. Then reboot your gateway. The status of the gateway on theV3 console should change from Disconnected to Connected.
Migrating the Device
Download the binary for your operating system from this link and install on your computer (Windows, MAC, Linux and even ARM-based Oss should work). In our case, we are migrating a thingsuno which has already been set up on The Things Stack V2. Our environment of migration is Linux 64-bit therefore we use the Linux 64-bit binary (with the latest release 0.4.0) and set everything up through the terminal.
Clone the code provided on this link to setup your migration folder. Configure the environment variable from the TTN V2 console to export your device details. This information is provided on the link shared but we copy paste our configuration details here:
Next, migrate the exported information by creating a devices.json file that is later uploaded on the V3 platform. The –dry-run flag exports the device without deleting the device keys from The Things Stack V2. More information on this is provided here.
Next, head to the ttn console on The Things Stack V3 and click on “Add application”
Then enter the information about the application and create the application.
The resulting screen shows the application ID created and at the bottom right has two options -“import end device” and “Add end device”. In the case of migration, select the first option: “import end device.”
Selecting the “import end device” leads you to the below screen where we are able to upload the device.json file created during migration. Here, select the Format “The Things Stack JSON” and under the File section->Select a file, upload the devices.json file stored on the PC. Please note that you have to remove the “session” section of the devices.json object as you might encounter an error of “invalid field mask” under the current binary releases. The Things Network Team has posted that it will improve in the future version.
Viewing the Data
After migration of both the gateway and the device, you can navigate to the live preview interface of the gateway and see the logs transmitted by the device.
You can also view this on the application interface.