documentation

Getting the Kit Online

There are a few steps involved in getting your trackers online for the first time. The process of setting up the devices is illustrative of the overall setup and system configuration. By following the steps outlined below, you should be up-and-running quickly.  Large-scale deployments can be automated by bulk import utilities and APIs.

Creating a LoRa Cloud Portal Account

Before a LoRa Edge Tracker device can be claimed, you first must have an account on the LoRa Cloud portal. To set up your account in a web browser, navigate to https://www.loracloud.com/.

  1. Click Get Started.

Figure 4: Cloud Portal Welcome - Get Started

  1. At the prompt, create an account. Use your email address and create a password.

Figure 5: LoRa Cloud Login

  1. You should receive a confirmation email for the account. Click on the confirmation link in the email. Your browser should open and take you to the login page. After logging into your new account, you will need to accept the Terms & Conditions of Use. Once you accept these, your account activation will be complete.

Creating an Application Owner and Getting Your Free Claim Allowance

Before you can claim your devices, you will need create an Application Owner. (An application owner is used to organize a group of devices.) To create an application owner, login to the LoRa Cloud portal and then

  1. Select the LoRa Cloud Device Join tile.

Figure 6: Selecting the LoRa Cloud Device Join Tile

  1. In the side panel, click Application Owners. Enter a name and then click Create New Owner, as illustrated in Figure 7

Figure 7: Creating a New Application Owner

Every new account has an allowance of 100 devices that can be claimed for free. You can assign one and only one of your application owners this allowance. On the Application Owners page, click the Assign button.  You will be prompted to accept the free claim allowance for the associated Application Owner. Accepting the assignment will allow you to claim up to 100 devices without charge. Press OK to accept.

Figure 8: Assign your Free Allowance of Claims to an Application Owner

Claiming a Device

To claim a device, navigate to the Device Join service in the LoRa Cloud portal at https://www.loracloud.com/portal/join_service. From there, select the Devices link in the left pane.

The Join Server page will display. Under the Devices header, you will be presented with two options: Claim Individual Device and Bulk Upload (CSV). In your kit, you will be provided information regarding the EUI, JoinEUI and PIN for your device. In the web interface, if you select the Claim Individual Device you will be presented with a form that looks like this:

 

Figure 9: Claiming a Device

The LR1110 Tracker EUI, PIN, and JOIN EUI can be extracted via the BLE Application that is described in Setting-up and Operating LoRa Edge Trackers

Note: The CHIP EUI can be left blank or you can enter the Tracker EUI. Leave the EXTRA field blank.

Enter the data and then click Claim Device. If the PIN corresponds to the device credentials, the interface will confirm that the device has been successfully claimed.

On-boarding: Network Server Specific

For the LoRa Cloud Device Join service to handle joining the device to the network, the device must to be associated with the network server that will route the traffic to it and from it. By default, all compatible network servers are enabled for use by your devices. You can skip ahead to the Using the LoRa Cloud Device & Application Services, unless you only want to enable Join Services for a single network.

You may set up devices that will interact with more than one LoRaWAN network server. Figure 10 shows two configuration setup examples. In the top example, a block of devices will be configured for LoRaWAN Network Server 1 (Server 1) the join requests for devices received from that network server for a claimed device will use the application configuration logic for appo-::a in the system. This is set on the Network Servers configuration page of the LoRa Cloud Device Join service, or through the Application Owner API documented here.

The second configuration example shows how the LoRa Cloud Device Join service can support integrations with multiple network servers.

Figure 10: Relationship between LoRaWAN Network Servers and Applications in LoRa Cloud Applications IDs

The purpose of mapping the registered network server to a specific Application Owner is that specific parameters can be set up for handling data when operating with each network server. There are three common settings for each application definition:

  • name
  • wrapkey
  • nslist

The name is an arbitrary string to represent the application. The wrapkey is a specific token used for encrypting the AppSKey, used during the transport of the AppSKey from the join server to the application server by the network server. The nslist is a list of LoRaWAN network servers that will be associated with this Application Owner configuration.

Each LoRaWAN session derives a unique AppSKey which is used for encrypting the LoRaWAN payload data between the device and the application server. The wrapkey can be null, indicating that the AppSKey will be passed from the join server to the application server by the network server unencrypted. For more information on working with the AppSKey, please see the documentation here.

Once the network servers are configured for a particular Application Owner via the LoRa Cloud Device Join service, the device join process can be performed. The LoRaWAN network server that sees the join request from the claimed device will forward this on to the LoRa Cloud Device Join service (which is operating as the Join Server in this system). It will provide the session keys and return them, along with the join response to the network server.

If a wrapkey is defined for the application associated with the network server, the AppSKey is returned encrypted. Otherwise, the AppSKey will be returned in plain text by the join server. The LoRaWAN network server will send the join response to the device. Once a data message is sent (following the join response) to the LoRaWAN network server, the join process will be complete and the device will be configured for operation on that network server.

Figure 11: Join Flow

Selecting ThingPark Enterprise on the LoRa Cloud Device Join Server

Once the Application Owner has been established, you must use the LoRa Cloud Device Join service to select the network server.

  1. Click NETWORK SERVERS link on the left
  2. On the Network Servers page, select ThingPark Community Platform
  3. Click ADD

Note: Currently the “Owner Context” for these devices is not defined.

Figure 12: LoRa Cloud Server Selection Page (no selection enables ALL Network Servers)

Using the LoRa Cloud Device & Application Services

To use the LoRa Cloud Device & Application Services for your LoRa Edge Trackers, you must create an Application Owner and then create a token that will be added to the transmission of the data between the Device & Application Services provided by LoRa Cloud and your application server.

To create an owner that can use these services:

  1. Login to your LoRa Cloud account (https://www.loracloud.com).
  2. Select the LoRa Cloud Device and Application Services.
  3. On the Device Owners page, accessible from the Device and Application Services landing page, create an owner or owners.
  4. Specify the currently-active owner.
  5. On the Active Owner page, define tokens with the properties you need. A token must have at least one, and may have all of the following permissions:
  • Add/Delete Devices
  • Deliver Uplinks
  • Access GNSS Data
  • Issue Device Requests
  • List/Read Device State
  • Add/Delete Tokens
  • List Tokens

When you add a token, you select its permissions. Once set, the permissions of the token cannot be changed. However, a token can be renamed or deleted at any time. You will use a defined token to access the various commands available in the Device & Application Services API to add new devices and list current devices. You can even list and add new tokens if the token you use has sufficient permissions. One of the most important uses of the token will be to transmit and receive data to and from the Device & Application Services. This token will be needed to provision the device on the Tago.IO account interface.

To create a LoRa Cloud™ Device & Applications Services owner (if it does not exist):

  1. Login to your LoRa Cloud account
  2. Select the LoRa Cloud™ Device & Application Services.
  3. Click on Device Owners.
  4. On the Manage Device Owners page (Figure 13), if an no owners are defined, click Create New Owner.

Figure 13: Manage Device Owners—Create New Owner

  1. On the Add a Device Owner page (Figure 14), enter a NAME, select a PLAN and then click SUBMIT.

Note: When selecting a PLAN, choose One Stop Shop unless you know you have some other need.

 

Figure 14: Add A Device Owner

Creating your LoRa Cloud Device & Application Token

To create your Device & Application Services token, follow these steps:

  1. Select the Manage Tokens page from the LoRa Cloud Device & Application Services page:

Figure 15: Select Manage Tokens

  1. From the Manage Tokens page, select ADD NEW TOKEN, as illustrated in Figure 16:

Figure 16: Add New Token to Device & Applications Services

  1. On the Add New Token page, name the token and select its Permissions. (Select ALL permissions):

Figure 17: Add New Token Example

  1. Click ADD NEW TOKEN

Back on the Manage Tokens page, you can view the token value by clicking View. You can also copy the token value to the clipboard by clicking Copy. The copied token can then be included in external applications that interface with the Devices & Applications Services.

Figure 18: View or Copy Token Value

Adding Devices

Devices are managed either through the Device & Application Services API or directly from the LoRa Cloud Device & Application Services web portal. The Manage Devices page is used to add devices for a specific application owner. The only information necessary to add a device to the list of managed devices is the device EUI (DevEUI); you can add the DevEUIs of the two LR1110 Trackers at the same time or one after the other.

To add a device from the Device & Application Services web portal:

  1. Click Manage Devices

Figure 19: Select MANAGE DEVICES

  1. On the Manage Devices page, click ADD DEVICES:

Figure 20: Select ADD DEVICES

  1. Add the device EUI in the box provided, then click ADD DEVICES.

Figure 21: Add a Device via the LoRa Cloud Device & Application Services