This document provides step-by-step instructions for create a simple demonstration dashboard for the TEKTELIC LoRa IoT Smart Room Sensors. This guide assumes that the user has received a basic LoRa IoT Demo Kit consisting of:

• 1x TEKTELIC Micro or Micro-Lite Gateway
  
• 4x TEKTELIC Kona Smart Room Base Sensors
  
• 1x TEKTELIC Kona Smart Room PIR Sensors
  
• 1x Handheld Magnet
  
• Tektelic Network Server Account
  
• Tektelic Thingsboard Server Account
  

At the end of this guide, the user will have:

• Registered their gateway and sensors to the Tektelic Network Server.
  
• Connected their Tektelic Network Server application to the Tektelic ThingsBoard Application Platform.
  
• Created a basic dashboard displaying all on-board transducers of the Tektelic Smart Room Sensors.
  
• Configured the Tektelic Smart Room Sensors over-the-air to report the different on-board transducer values. NOTE: The example configuration commands are written for Gen 2 Home Sensors (T00048xx) and will not work for Gen3 Smart Room Sensors (T00061xx).
  

1. Login to the Tektelic Network Server
   

Tektelic maintains two different network servers, one for North America and one for Europe. The Tektelic gateway will come preconfigured to automatically connect to one of these servers.

Tektelic North American Network Server - URL: https://lorawan-ns-na.tektelic.com/

Tektelic European Network Server – URL: https://lorawan-ns-eu.tektelic.com/

Connect to the appropriate server using a web browser and enter your login credentials:

Figure 1: Network Server Login Screen

Once you have successfully logged in you will be taken to your accounts ‘Home’ Screen.

Figure 2: Network Server Home Screen

The Home screen is the central location for navigating the Network Server. It can be returned to at any time by selecting the ‘Home’ button on the sidebar.

2. Adding your Gateway to the Network Server
   

The first step in setting up your new LoRaWAN network is to register your gateway to your network server account. 

To begin select the ‘Gateway Groups’ icon. This will take you to the Gateway Groups page.

Figure 3: Gateway Groups

a) Creating a new Gateway Group

All new network server accounts begin with no gateway groups created. To add your first gateway group click on the ‘+’ in the top right corner of your screen.

Figure 4: Adding a Gateway Group

This will open up a dialog box where you can enter a name and description for your new gateway group. Try to use meaningful names for your gateway groups as this will allow you to find gateways quicker later, especially if you are rolling out a larger number. 

Figure 5: Gateway Group Dialog Box

Once you have entered the gateway group name and any description, click the ‘add’ button to finish the creation of your new gateway group.

b) Adding your first Gateway

Now that you have added your first Gateway Group, you are ready to register your gateway to the network server. Click anywhere on your new gateway group to open up the Gateway Group Tab.

Figure 6: Gateway Group Tab

From this tab, you can click the ‘manage gateways’ button to go to the gateway list for this gateway group.

Similar to the previous Gateway Group page, you will see that the list is empty. To add your gateway, click on the ‘+’ button in the top right corner.

Figure 7: Gateway list

Again, this will open up a dialog box where you can enter your gateways information.

Figure 8: Gateway Registration Dialog

The ‘Gateway ID’ and ‘Gateway model’ can be found on the sticker on the back of your Tektelic Gateway.

Figure 9: Tektelic Gateway Label

The Gateway ID must be entered exactly as show to properly register your gateway on the account. 

When selecting the ‘Gateway model’ you must select the appropriate region for your Gateway as well. 

Figure 10: Gateway Model Mapping

Once you have filled in the required fields, click the ‘add’ button to finish registering your gateway on the network server.

c) Configure MQTT Bridge

d) Verifying gateway registration

Click anywhere on your new gateway to open up its details tab.

Figure 11: Gateway Details Tab

After a few minutes the gateway status should switch from the red ‘Offline’ to the green ‘Online’

Note: If your gateway never switches to the ‘Online’ state STOP. Verify that you entered the GW ID correctly and ensure that your network connection is working. You are unable to proceeding past this point with an ‘Offline’ gateway.

3. Adding Devices to the Network Server
   

Now that the Gateway is registered to account and displaying online, you are ready to add your first devices to the network server. 

On Tektelic Network Server, Devices are grouped together into ‘Applications’. To being, select the ‘Applications’ icon. This will take you to the Applications page.

Figure 12: Applications

a) Creating a new Application

Similar to Gateway Groups, all new network server accounts begin with no applications created. To create your first application click on the ‘+’ in the top right corner of your screen.

Figure 13: Application Creation

This will open up a dialog box where you can enter a name and description for your new application. Again, try to use meaningful names to allow yourself a quick reference when finding a collection of devices later.  

Figure 14: Application Dialog Box

Once you have entered the application name and any description, click the ‘add’ button to finish the creation of your new application.

b) Configuring your Application

• Now that your application is created, it should be configured first to simply your device setup. Click anywhere on your new application to open up the Application Details sidebar.The sensor is shipped with the battery wire unplugged. Remove 4 screws holding the cover, to gain access to the Sensor battery connector. Be careful not to misplace the silicone cover gasket.
  
• Once the sensor is configured on the Network Server and input cable is installed, plug the battery into the sensor circuit board. See Section 4.3 for the LED behaviour.
  
• Once the Sensor is powered, replace the cover and gasket. Make sure that the gasket is properly seated in the cover before placing on the Sensor housing. Tighten the 4 cover screws to 2.5 lbf-in (30 N-cm).
  
• To reset or turn off the device the battery must be unplugged from the circuit board. The unit must remain un-powered for 1 minute to completely reset.
  

Figure 15: Application Details

Select the Advanced Network Settings Tab, and click on the red pencil icon to edit the network settings for this application.

Figure 16: Application Network Settings

These settings will be applied to all device within this application that select to use the application settings. This provides a quick and easy way to set a configuration that will apply to all sensors only once.

Figure 17: US915 Advanced Network Settings

For the North American region two fields need to be modified from the default. ADR needs to be enabled, and the default channel mask needs to be changed to 8-channels. This will restrict the device to operate to the default 8-channels used by Tektelic Gateways.

Note: If you are using a custom channel plan you will need to select the ‘Custom’ option under the default channel mask. Refer to the LoRaWAN Regional Parameters document.

Figure 18: EU868 Advanced Network Settings

For the European region two fields need to be modified from the default. ADR needs to be enabled, and the CF List needs to be updated to reflect the Gateway channel plan. This will instruct the network server to push down the additional 5 channels used by Tektelic Gateways.

These are (in MHz):

• 867.1
  
• 867.3
  
• 867.5
  
• 867.7
  
• 867.9
  

Note: If you are using a custom channel plan you will need to enter the appropriate channel frequencies instead of the default Tektelic channels.

c) Save Application Settings

Once you have finished setting the desired network settings you can save them by clicking the red checkmark in the top right.

Figure 19: Save Application Network Settings

d) Registering your device

Now that you have created an application and configured it, you are ready to register your first device. Start by selecting your application, and clicking the ‘Manage Devices’ button from the side panel.

This will open up a familiar screen showing all devices registered under this application. Click the ‘+’ button in the top right corner to open the ‘Add Device’ dialog box.

Enter a name for your device so you can identify it later, and select your device model from the drop down list.

Note: This guide assumes you are using Home Sensors.

Figure 20: Device Registration Dialog

You will now need to fill in your device specific information. The DevEUI, AppEUI and AppKey are provided for each device you receive from Tektelic. Make sure you also select to ‘Use application settings’ to allow this device to use the configuration settings you setup in the previous step.

Figure 21: Device Registration Completion

Once you have finished entering your details, and selected to use application settings click the ‘Add’ button to complete the process.

You can now pull the battery tab from your device and it should join the network within 1-2 minutes. You are waiting for the LED on the device to stop blinking and for its status on the network server to change to ‘Online’.

Figure 22: Successful Device Join

You can now repeat the procedure for the rest of your devices. Once all of them are online you can proceed to the next step.

Figure 23: All Devices Online

Integrating Tektelic Network Server and ThingsBoard Application Platform

At this point you have registered your gateway and devices and have started to receive uplink packets from your sensors. Currently, all this data is confined to the network server so now you can start the process of getting the data to an application platform like ThingsBoard.

Starting back on the home screen, select the Applications tile to take you to your Applications list.

Select your application to open up its side panel, and click on the ‘Manage Integrations’ button.

Similar to the other lists when first starting you will see an empty list. Click on the ‘+’ icon in the top right corner to open the integration dialog box.

Name your integration, and enter/select the following items:

• Type: ThingsBoard
  
• Data converter: Tektelic Home Sensor
  
• Application address: 
  

• North America: tek-tb-us.thingsboard.io
  
• Europe: tek-tb-eu.thingsboard.io
  

• Port: 9883
  

Figure 24: Integration Setup

You will notice that the token field is empty, but required for completing the process. To complete this, you must perform some initial setup on your Thingsboard account first.

b) ThingsBoard Integration Setup

In another tab/browser window open up the ThingsBoard website. You will be greeted with a login screen. 

Enter your credentials to get taken to the home page.

Similar to Tektelic Network Server, the ThingsBoard Application platform uses a similar tile based navigation menu. Start by going to the ‘Devices’ tile.

This will open up the ‘Device Groups’ page. Select the ‘All’ tile to go to the list of all devices currently on the platform.

Currently, this list will be empty but you will add the first device by selecting the ‘+’ in the top right corner opening the ‘Add Device’ dialog box.

Enter the following information for your first device:

• Name: Tek-NS
  
• Device Type: integration
  
• Check ‘Is gateway’
  

Figure 25: Thingsboard Device Gateway Parameters

Finally, go back to the device list and select this new device to open its side panel.

Figure 26: Copy Access Token

Select the ‘Copy Access Token’ button to copy the Token you will need to provide to the network server to your computers clipboard.

Finally, go back to your near completed dialog box on the network server, and enter your access token in the ‘Token’ field.

Figure 27: Completed Integration Dialog

Click the ‘Add’ button to complete the process. 

Go back to your device list on ThingsBoard Application Platform. You should see the integration device that you created there.

The next time one of your home sensors uplinks data to the network server you can refresh your device list on ThingsBoard and all the devices in your Network Server application should appear.

Dashboard Setup

At this point, data from your devices is getting sent up through the LoRaWAN network and is being pushed to your ThingsBoard account. You now want to create your first dashboard to visualize this data. We will start with a pre-made dashboard that is included as part of this document.

a) Importing the Quick Start Dashboard

From the Dashboard screen select the red ‘+’ in the bottom right. 

This will open up a short list of options. Select the ‘Import dashboard’ options from the list.

Follow the on-screen instructions and upload the ‘quick_start_dashboard.json’ file.  

Click on the ‘Import’ button to complete the process.

You will now be prompted to configure the aliases used by the Quick Start dashboard. Select the pencil icon next to the first aliases.

Select ‘Single entity’ for the Filter type and ‘Device’ for the Type.

For the device select the dialog box and a list of available DevEUIs will show up. These will match the devices you added into the network server. For each alias select one device, and record which DevEUI was assigned to each alias. Apart from the PIR sensor there is no preferred order as you will configure the devices in the next step.

Note: Motion-Sensor MUST be assigned to your PIR sensor.

Once you have assigned one device to each alias, click the ‘Save’ button to commit your changes.

The Quick Start Dashboard should now be shown on your Dashboards screen. Click its tile to open it.

The Dashboard will open up, showing widgets for Motion, Light, etc.

Device Configuration

To enable some of the extra features that are on the Home Sensor you will need to configure the device over the air. To start go back to the Dashboard list.

a) Importing the Configuration Dashboard

Like before, in the Dashboards Menu select the red ‘+’ in the button right hand corner and select ‘Import dashboard’ from the list.

This time, select the ‘quick_start_configuration.json’ to upload and import.

You will need to setup the alias list again for this dashboard, so begin by selecting the pencil icon from the ‘configure alias’ dialog box.

This time you will select ‘Entity list’ as the filter type and ‘Device’ as the type. 

For the list select the three devices you assigned to Light-Sensor, Impact-Sensor and Moisture-Sensor. Also ensure that the ‘Resolve as multiple entities’ slider is off.

Save the configuration, and open the new ‘Quick Start Configuration’ dashboard.

b) Using the Configuration Dashboard

This dashboard provides access to the debug terminal that will be used for device configuration. In the top right of the screen you will see a device name listed. Clicking on it will give you a drop down menu that will allows you to cycle through your three devices.

Open up the ‘Downlink-Command-List.txt’ file (attached to this article) for a list of the commands you will need to send down to configure your devices. NOTE: The example configuration commands are written for Gen 2 Home Sensors (T00048xx) and will not work for Gen3 Smart Room Sensors (T00061xx). For encoding the Gen3 sensors, please refer to the most recent TRM document in the Home Sensors tab on the Knowledge Base.

Start by selecting the DevEUI corresponding to your Impact-Sensor from the drop down list and type the following into the Sensor Configuration Terminal:

setValue "{\"port\": 100, \"data\": \"sQnEsgK0grUG8CAA\"}"

Press enter to send the command to the sensors downlink queue. The network server will send the downlink the next time that sensor sends an uplink message.

Note: It is normal for the Sensor Configuration Terminal to response with ‘Device is offline’. The message will still be queued in the network server. If after receiving an uplink from the sensor, the new behavior is not working try sending the configuration message again. Sometimes messages will get dropped in the network. This is especially true in Europe where your gateway may be duty-cycled.

Once you have finished configuring the Impact-Sensor, select the DevEUI corresponding to the Moisture-Sensor from the list and send the following: 

setValue "{\"port\": 100, \"data\": \"3AHwIAA=\"}"

Finally, select the DevEUI corresponding to the light sensor and send the following command:

setValue "{\"port\": 100, \"data\": \"xwAAADzICvAgAA==\"}"

Once you have confirmed that the downlink messages have been sent by the network server, and your devices have been reconfigured you are done. 

Conclusion

Having followed the above guide, you have successfully registered your new gateway and devices on the network server. Following this, you connected your Network Server and Thingsboard account and created a simple dashboard for displaying the various sensor data.

Finally, you used the over the air configuration capabilities of the sensor to change the devices behavior and enable some of the extra features. You should now have a simple demo that will allow you to experiment with the different sensor features and a secondary dashboard that will allow you to create your own configuration commands to experiment with your own ideas.