connecting to the semtech website - laird...

A

Embedded Wireless Solutions Support Center:

http://ews-support.lairdtech.com

www.lairdtech.com/ramp

1

© Copyright 2016 Laird. All Rights Reserved

Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0610

Connecting to the Semtech Website RM1xx Series

Application Note v1.2

INTRODUCTION

Laird’s RM1xx series of LoRaMAC modules are a combination of a Nordic Semiconductor based Laird BL600/BL620 BLE Central or Peripheral device and the Semtech SX1272 860MHz to 1020MHz LoRa transceiver.

The RM1xx can interface with a sensor either directly over UART, SPI, and I2C serial communication buses or remotely via Bluetooth Low Energy (BLE) connections. Data can also be entered directly from digital or analog GPIO pins. This resultant data can then be transmitted to a remote gateway several miles away using the LoRaMAC protocol. The gateway then sends the data to a website or database which can act on that data as required.

In order to aid development and testing of LoRa devices, Semtech has created a web site which is available to any company or individual who wishes to test a LoRa device.

The purpose of this document is to explain how to interface with this website from an RM1xx using a Multitech gateway as a packet forwarder. It is possible to use any gateway for this purpose, however, whereas the details on how to set up that gateway are different, those on configuring the RM1xx and the website remain the same.

WEBSITE DETAILS

There are two different websites available from Semtech. One supports the North America (US) gateways and the other supports the European gateways.

European Website Address and Ports

For gateways connecting to RM186, use the European version of the website. The address of the European website is iot.semtech.com.

The uplink and downlink paths both use port 1680.

North America (US) Website Address and Ports

For gateways connecting to RM191, use the North America version of the website. The address of the North America website is us01-iot.semtech.com.

The uplink and downlink paths both use port 1780.

These settings must be configured in the global_conf.json file on a gateway. Do not manually edit this file. You must make any changes through the web application supplied by Multitech. More details of how to do this are provided in the Configuring the Multitech Gateway section.

http://ews-support.lairdtech.com/

http://iot.semtech.com/

http://us-01.iot.semtech.com/

Connecting with Semtech Website Application Note

Embedded Wireless Solutions Support Center: http://ews-support.lairdtech.com www.lairdtech.com/ramp

2


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

The relevant section of the file is shown in Figure 1 and can be viewed using any appropriate terminal application. The location of the file can vary depending on which version of the Multitech gateway firmware you are currently using.

Figure 1: Global_conf.json

CONFIGURING THE RM1XX Before communications between an RM1xx and a server can begin, both sides of the link must be configured with the network and application session keys, NwkSKey and AppSkey, which are used to encrypt and decrypt the data. These keys can either be generated automatically using the Over-the-Air Activation (OTAA) process by entering the AppEUi, DevEui, and AppKey, or configured manually in the RM1xx and server during the Activation-by-Personalisation (ABP) process.

Each method requires three values to be entered into the RM1xx. These values are shown in Table 1.

Note: It is very important to understand what the following values do and where and when they are used. Regardless of which method is used to join the network, both the module and the server must be configured with exactly the same ID or key values. Later, the values entered in this section must also be entered in the Configuring the Website section. If this is not done correctly it will be impossible to transmit data between the RM1xx and gateway/server.

Table 1: LoRaMac IDs and keys

Value Description Config Id Process

AppEUI Application ID that uniquely identifies the end device provider 1010 OTAA

DevEUI Device ID that uniquely identifies the end device. 1011

AppKey Application Key used in the calculation of the NwkSKey and AppSKey 1012

NwkSKey Network Session Key 1013

ABP AppSKey Application Session Key 1014

DevAddr Device Address which identifes the end device within the network 1015

These values can be loaded into the RM1xx using the at+cfgex smartBASIC command. For the OTAA example below we use the AppEui, DevEui, and AppKey values that are also entered in the Over-the-Air section below.




3


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Note: Prior to firmware versions 17/18.4.1.0, the configuration IDs in Table 1 were in the range of 1000 – 1005 instead of the new range of 1010-1015.

You only need to load the configuration values that you are planning to use. For example, if you're only using OTAA then you don't need to load the values for ABP and vice versa.

Figure 2: OTAA configuration example

The RM1xx already has a DevEUI value stored in memory during production. This default value is superseded by setting this new value. The default value is not overwritten as this new value is stored in a different memory location. The example in Figure 2 shows the setting of the DevEUI value (at+cfgex1011). You do not need to carry out this step if you decide to use the default value. You only have to configure the AppEui and the AppKey.

If you choose to use the default value, you must enter that as the DevEUI value into the gateway in the Over-the-Air section below instead of the value shown in Figure 2. You can retrieve the default value using the ATI 25 command.

If you choose to use ABP, enter the values as shown in Figure 3.




4


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 3: ABP configuration example

In both cases, the module must be rebooted before the values are available for use.

CONFIGURING THE MULTITECH GATEWAY

The Multitech Gateway can be configured as either a server or a packet forwarder. For this application you must configure it as a packet forwarder. In this mode, the gateway forwards every packet it receives to an IP address that is set up in the global_conf.json file. With the present Multitech firmware, this file can be found in the /run/lora/1 directory. Do not manually edit this document. Everything must be handled through the Multitech web application.

You must first configure the gateway’s IP address so that it can connect to external IP addresses through your local network. You can initially connect to the gateway through any console application that can be configured for a serial connection. This is explained in the Connecting to a Multitech Conduit Gateway application note, available in the documentation tab of the RM1xx product page.

Once you have logged onto the Gateway, you can find the default IP address by typing the following command at the command line: ifconfig eth0, as shown in Figure 4.


http://www.lairdtech.com/products/rm1xx-lora-modules



5


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 4: Gateway IP config

In this case, our gateway’s IP address is 192.168.1.14.

If the returned address is not in the IP range of your network, you must update the Gateway as follows:

1. Temporarily reconfigure your PC’s network adapter to the same IP network as the Gateway.

2. Open the gateway’s IP address in your web browser, as shown in Figure 5.

Figure 5: Webpage login page

3. Enter the correct username and password (which by default are admin and admin). 4. Navigate to Setup > Network Interfaces as shown in Figure 6.




6


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 6: Webpage Network Interfaces Configuration

5. Click the pencil link for eth0 to view your current settings as shown in Figure 7.

Figure 7: eth0 configuration




7


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

6. Configure these as required to bring the gateway within your network’s IP range. You may want to consult your network administrators for the correct values.

7. Click Finish. 8. Click Save and Restart to reboot the Gateway.

The Gateway should now be configured on your local network which means you can now reset your PC’s network adapter back to its original IP address.

Once the Gateway has rebooted, complete the following steps:

1. Open the webpage with the IP address you have just set up. 2. Navigate to Setup > Lora Network Server. 3. Select Packet Forwarder from the drop-down menu as shown in Figure 8.

Figure 8: Packet Forwarder page

When you first open this page, the Config section is blank.

4. Enter the applicable global_conf.json into this section. Multitech has supplied example files at the following web address:

http://www.multitech.net/developer/software/lora/aep-lora-packet-forwarder/


http://www.multitech.net/developer/software/lora/aep-lora-packet-forwarder/



8


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

5. Select the applicable link – either US (915MHz) or Europe (868MHz) – and copy and paste the file into the Config section. These example files are already configured for the appropriate Semtech website so you shouldn’t have to do anything here.

Note: Do NOT manually edit the gateway_ID tag. The gateway automatically populates this field in the global_conf.json file when it reboots.

In the case of the RM186, you may also need to check the radio_0 setting. This value should match that of the Additional Channels option in the Network Server page. Note that in the global_conf.json file, the value is written in Hertz and in the Addition Channels box it is entered as a MHz value.

6. Click Submit. 7. Click Save and Reset to reboot the Gateway. Once rebooted, it should be in Packet Forwarder mode.

CONFIGURING THE WEBSITE

Before data can be sent to and viewed on the website, the Semtech website must be configured for both the gateway and the modules that are to be used.

Note: In this section, the term Mote is used on some of the website screenshots. This is another term used for a remote end device of which the RM1xx is just one example.

Adding the Gateway to the Website

The first task is to add your gateway to the Semtech network. To do this, complete the following steps:

1. Register with the website. a. Go to the website and select the Not Registered link.

Figure 9: Login screen

b. Fill in the blank fields.




9


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 10 : Registration details

c. Click Register.

2. Once you receive confirmation that your registration is accepted, you can log in using the two fields shown in Figure 9.

3. Select GO to display the following options (Figure 11).

Figure 11: Website options

4. Select the Gateways option. At the top of the next page you should see the boxes shown in Figure 12.

Note: You must be logged in to see this option as they can only be accessed in the Private section of the website. You cannot see the contents of Figure 12 if you are not logged in.




10


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 12: Configuring a new Gateway

5. Enter the gateway EUI and decide whether you want to make it available to the public or only in the private section of the website by selecting the appropriate button. If you select the private option, only you can see the data pertaining to that gateway once you log onto the server.

The gateway EUI can be found in the global_conf.json file. It is labelled as gateway_ID. See Figure 1 for an example. To retrieve this value, you must open a connection to the gateway and open the global_conf file. You cannot use the webserver to retrieve this value. It will still show the "<WILL-BE-REPLACED-WITH-LORA-EUI>" message.




11


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Adding an Application

This section describes how to add an AppEui to the website.

As discussed previously, an RM1xx contains two IDs: The Application Identifier (AppEui) and the End-device Identifier (DevEui). In this case, the Application refers to the AppEui which uniquely identifies the application provider. The DevEui, on the other hand, uniquely identifies the RM1xx. So the same AppEui is configured on a number of modules, each of which has a unique DevEui.

To add an application, follow these steps:

6. Select the Applications link from sidebar of the Semtech homepage (Figure 13). 7. Enter the name, owner, and AppEUI in the corresponding fields. 8. Click Add.

Figure 13: Adding an AppEui

The new application now appears in the list of applications. At this stage there are no end-devices (motes) associated with the new application.

Figure 14: New application added to list

Adding a Module to the Website

It’s possible to obtain end-devices that are already configured on the server. Because these devices are already configured, it’s possible to reuse their IDs and keys on your own modules.

There are a number of ways to configure an end-device using new values. You must be logged onto the website for either method.




12


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Again, for the RM1xx you only need to configure the IDs and keys that you're planning on using. If you only plan to use Over-the-Air, then only load the Over-the-Air parameters.

First Steps

The Semtech website offers a First Steps option, which allows you to download IDs for four predefined end devices. However, because these IDs are the same for everyone, it is likely that they are already in use; you must create your own values as shown in the Over-the-Air and Personalised sections below. You can use the values shown in the First Steps page as a template for the format of your values.

Over-the-Air

To add a module using the Over-the-Air method, follow these steps:

1. From the server homepage (Figure 11), select Motes. 2. Click More mote options to expand the page. 3. Select Over-the-Air. 4. Enter values into the two boxes. The DevEUI and AppKey can be any unique value provided they meet the

correct format for that parameter. 5. From the Add to Application drop-down menu, select the AppEui to which you want the module to belong. 6. Click Add.

For this section and the Personalised section below, we use the AppEUI we created above in the Adding an Application section.

Figure 15: Adding a module – Over-the-Air

On the Applications page, the new module should now display (Figure 16).

Figure 16: New module added




13


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Click the applicable Configured Motes link to view the details of the newly-added module (Figure 17).

Figure 17: Module details in Over-the-Air Motes section

Personalised

To add a module using the Personalised method, follow these steps:

1. From the server homepage (Figure 11), select Motes. 2. Click More mote options to expand the page. 3. Select Personalised. 4. Enter the applicable values in the four boxes. 5. Select the application to which you want the module to belong. 6. Click Add.

The module should now be added (Figure 18).

Figure 18: Adding a module – Personalised

The Applications page shows that the new module is added to the Configured Motes, but this time the details display under the Personalised Motes heading (Figure 19 and Figure 20).




14


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 19: Second module added

Figure 20: Module details in Personalised Motes section

DATA CONTENT

The Semtech website is designed to receive a 16-byte data packet which contains a GPS coordinate, temperature data, and atmospheric readings. There is no need to connect to an actual GPS receiver. You may use dummy data provided that it fits in with the packet format.

Any data packet that you transmit to the website must match this protocol (Table 2).

Table 2: Data Packet Format

Byte Data Description

0 LED State State of an LED, (i.e. ON or OFF)

1 (pressure >>8) & 0xFF MS Byte of a 16-bit Pressure value

2 pressure & 0xFF LS Byte of a 16-bit pressure value

3 (temperature >>8) & 0xFF MS Byte of a 16-bit temperature value

4 temperature & 0xFF LS Byte of a 16-bit temperature value

5 (altitudeBar >>8) & 0xFF MS Byte of a 16-bit barometric altitude value

6 altitudeBar & 0xFF LS Byte of a 16-bit barometric altitude value

7 batteryLevel Battery level

8 (latitude >>16) & 0xFF MS Byte of 24-bit latitude

9 (latitude >>8) & 0xFF Middle Byte of 24-bit latitude

10 latitude & 0xFF LS Byte of 24-bit latitude

11 (longitude >>16) & 0xFF MS Byte of 24-bit longitude




15


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Byte Data Description

12 (longitude >>8) & 0xFF Middle Byte of 24-bit longitude

13 Longitude & 0xFF LS Byte of 24-bit longitude

14 (altitudeGps >>8) & 0xFF MS Byte of 16-bit GPS altitude value

15 altitudeGps & 0xFF LS Byte of 16-bit GPS altitude value

SENDING DATA TO THE WEBSITE

Once everything is set up, you can start transmitting data to the website. A simple smartBASIC application is provided for download from the following link:

https://github.com/LairdCP/RM1xx-Applications/blob/master/lora.connect.sb

When you run this application, it attempts to join the network using the OTAA option. Once the RM1xx receives notification that the Join Request is successful, it transmits packets of data to the website. If you wish to use the Personalization method, simply change the value of the nJoinType variable in the LORAMACJoin() command.

Once a module is notified that a packet is successfully received by the website, a 25-second timer starts. Once it times out, the next packet is transmitted. The module continues to transmit packets in this fashion until the application is halted. Take into consideration that, with the RM186, there will likely be longer gaps between the data being sent due to duty cycle constraints.

The actual data that is sent is dummy data. The lat and lon are set to 0,0 which is a position just south of the Nigerian coast in the Atlantic Ocean.

To mimic changing data, the lowest bytes of the pressure and temperature settings are incremented by one with each new packet. The single-byte battery value is also incremented by one with each new packet. The data, as shown on the website, resembles three saw tooth patterns on the graph (shown later in Figure 26).

It’s possible to view and modify some of the LoRa parameters in the module using the Lora Get/Set commands. Consult the smartBASIC Extension RM1xx Series guide for more details on this command. This guide is available from the Laird RM1xx product page on the Documentation tab.

Once the application is downloaded to your RM1xx, type in lora to run it. If everything is working correctly, you should see the debug on your console application as shown in Figure 21. You should also see data arriving on the Semtech website.


https://github.com/LairdCP/RM1xx-Applications/blob/master/lora.connect.sb

http://www.lairdtech.com/products/rm1xx-lora-modules



16


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 21: Application running

VIEWING DATA ON THE WEBSITE Once your devices are sending data to the gateway, there are a number of ways to view the data. Depending on whether you want to see data relative to an end-device or a gateway, choose the Mote or Gateway options respectively from the server homepage (Figure 22). Our device (mote) is 016a41860000001.

Figure 22: Choose Motes or Gateways

Gateways Choose Gateways to view data arriving at a specific gateway. This lists the last end-device that has successfully transmitted a packet to the gateway and the time of that packet. Note that all times are relative to GMT.

In Figure 23, the table is set to list the data with respect to the time of the last frame.




17


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 23 : Gateway table

Motes

Click Motes to view similar data but, with this option, the remotes (motes) are the first column rather than the gateway. With this selection, more data is available (Figure 24). This table is also set to list the data with respect to the time of the last frame.

With the Motes view, you can also see the DevAddr of the module and to whom the device application belongs.

Figure 24: Mote table

If you select a specific end-device, you are directed to a page with information on every packet that device has transmitted to a gateway (Figure 25). This page provides a powerful diagnostic tool for keeping track of connection statistics.




18


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

Figure 25: End-device details

The page also provides a graph of parameters in real-time (Figure 26).

Figure 26 : Graph of received data




19


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

The View transmission performance link lists the packet information such as frequency, bandwidth, and data rate.

Figure 27 : Packet parameters

The View data from application Laird link lists the actual payload data. So you can see on a packet-by-packet basis the data that has been transmitted by the end device.

Figure 28 : Packet payload

REFERENCES

The following supporting documents are available from the Laird RM1xx product page:

LoRaMote Demonstration User Guide smartBASIC Extensions RM1xx Series Connecting to a Multitech Conduit Gateway – RM1xx Series Connecting to a Kerlink Gateway – RM1xx series Interfacing with LoRaMAC - RM186 Series Interfacing with LoRaMAC - RM191 series

REVISION HISTORY

Version Date Notes Approver

1.0 20 May 2016 Initial Release Colin Anderson

1.1 28 Oct 2016 Firmware versions 17.4.1.0 and 18.4.1.0 Jonathan Kaye

1.2 02 Feb 2017 Updated for BLE Peripheral Mode Jonathan Kaye


http://www.lairdtech.com/products/rm1xx-series



20


Americas: +1-800-492-2320 Europe: +44-1628-858-940

Hong Kong: +852 2923 0600

© Copyright 2016 Laird. All Rights Reserved. Patent pending. Any information furnished by Laird and its agents is believed to be accurate and reliable. All specifications are subject to change without notice. Responsibility for the use and application of Laird materials or products rests with the end user since Laird and its agents cannot be aware of all potential uses. Laird makes no warranties as to non-infringement nor as to the fitness, merchantability, or sustainability of any Laird materials or products for any specific or general uses. Laird, Laird Technologies, Inc., or any of its affiliates or agents shall not be liable for incidental or consequential damages of any kind. All Laird products are sold pursuant to the Laird Terms and Conditions of Sale in effect from time to time, a copy of which will be furnished upon request. When used as a tradename herein, Laird means Laird PLC or one or more subsidiaries of Laird PLC. Laird™, Laird Technologies™, corresponding logos, and other marks are trademarks or registered trademarks of Laird. Other marks may be the property of third parties. Nothing herein provides a license under any Laird or any third party intellectual property right.


connecting to the semtech website - laird...

Documents