Overview

LoRaWAN uses an AES 128 CCM security model with the End Devices and the Join Server both provisioned with the End Device’s root key(s). The Join Server is used to authorize the Device and distribute session keys to the Network Server and Application Server while the End Device generates these same session keys locally. Typically, the manufacturer of Devices supporting Over-The-Air Activation (OTAA) will supply the Application Provider a manifest containing the Device EUI (DevEUI), Join Server EUI, (JoinEUI sometimes called the AppEUI) and Root Key(s) (LoRa v1.0 AppKey, LoRa v1.1 NwkKey and AppKey). Note, as a best practice, the JoinEUI should be specific to the Application Provider. Registration is the process of loading the DevEUI/RootKey(s) and associated meta data for each End Device on to the Join Server. The Activation process informs the network server that the Device is allowed on the network.

To activate a Device on the network it must be assigned to a Contract. This Device to Contract association establishes a billing relationship and the communications entitlement for a pool of Devices. When contracts are established, Contract IDs are assigned by SenRa and made available to associate in the Registration and Activation processes. When a Device is Activated it transitions to a billable state.

State Description Billing State
Registered Device identity is uploaded to the Network Server. Not Billable
Activated Device identity is assigned to a Contract and authorized to join the network. Billable
Active Authorized Device joined the network and is communicating. Billable
Deactivated and Heard Deauthorized Device still communicating on the Network. Device is excluded from re-joining the network. Billable
Deactivated and Silent Deauthorized Device no longer communicates and is not heard by the Network Server for a complete billing period. Not Billable

Registration and Activation may be accomplished using the UI in the Application Provider Portal or via API with JSON. It is important to note that once a Device has been Joined to the network the Contract assigned to the Device cannot be changed. In the event a Contract was incorrectly assigned, Support can assist with changing the contract associated with Devices.


States & Transitions

screenshot

Device Fields

The table below details the purpose, expected data type and format of a Device's data fields. The table also identifies when the fields can be set in relation to the Device State Transitions described above.

Field Field Name Description Allowed Values Example Settable During
devEui Device EUI The IEEE EUI-64 identifier for the Device. Hexadecimal String FFFFFFFFFFFFFFFF Registration
appKey App Key The Device's AES-128 root key used to derive session keys (Application Key). Hexadecimal String FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF Registration
contractId Contract ID The Contract Id assigned to the Devices. Integer 100 Registration Activation Deactivation
profId Device Profile The Device Profile Id assigned to the Devices. Integer 100 Registration Activation Deactivation Update
lat Latitude The Device's latitude in decimal degrees. Float -32.221 Registration Activation** Deactivation Update
lng Longitude The Device's longitude in decimal degrees. Float 72.3233 Registration Activation** Deactivation Update
tags Tags Informational tag(s) for the Device. Comma separated list of Strings Tag1,tag2 Registration Activation** Deactivation Update
metadata Metadata Custom information for the Device. String deviceID=100; deviceNumber=10 Registration Activation** Deactivation Update
devType Device Type The type of the Device. String Senet NA Mote Registration Activation** Deactivation Update
devClass Device Class The classification of the Device, either Class A, B, or C. CLASS_A or CLASS_B or CLASS_C CLASS_A Update*
fwVer Firmware Version The firmware version of the Device. String 10.1.2 Update*

* Only Devices which have Joined the Network.

** Only Devices which have not Joined the Network.

Token Management (MFA)

Registration requires multi-factor authentication: an authentication token must be requested and then submitted. A token may be requested either during the registration process (see below) or directly from the Device Management table. In response to a token request, an email with a token (six-digit code) is emailed to the requesting user account. By default, the token has a one-hour lifetime and a single use count. Please contact support@senraco.com to modify the token lifetime or use count.

After the token is consumed (use count runs out) or expired, a new token must be requested. A new token will overwrite the previous one, even if it has not expired or been completely used.

Note

Device Activation and Device Deactivation do not require multi-factor authentication.

To get started, navigate to the Device Management table.

From the Device Management table, select the upload screenshot button to start the registration process.

Register Devices

A registered Device must be Activated before it can join the network.

A Device must be registered before it can be Activated.

To Register Devices, select the Register action, and click the ellipsis to upload a CSV file.

screenshot

Entering an Authentication Token

When the Upload File button is clicked, the following dialog allows the user to request and submit a token.

screenshot

Note

A single token is generated per application. When multiple users manage the same application, token management must be coordinated as new requests immediately overwrite the current token.

After a file is selected and token supplied, a confirmation dialog appears.

During Registration, the user can choose to assign a contract, or can select the Do Not Set operation if the contract association is unknown.  Once the deployment destination is known, a contract can be assigned during the Device Activation process.  A Device profile can also be applied to all Devices being registered.

Optionally, informational tags may be applied to this group of Devices.

Select Yes to upload the selected file.

Note

Device profiles and contracts are set when a device joins the network. Prior to joining, these values can be preselected. If "Do Not Set" is selected during registration, a value can be assigned during activation. If no contract or profile is selected during both operations, the default value configured for the application will be used at join time.

screenshot

Once the upload data is validated an upload summary is displayed.

If the upload fails or the data is invalid, error feedback is provided.

screenshot

Example Registration CSV Format

####################################################
# Required Fields: devEui, appKey, 
# Optional Fields: lat, lng, tags, metadata, devType
####################################################
devEui, appKey, lat, lng, tags, metadata, devType
AA11111F00000001,0B76FAB3C1A189403C145BF1FCB08647, 42.356959,-71.053271,tag1;tag2,metadata1,WATER_SENSOR
AA11111F00000002,E4FFBA476D97E00D7E38EFD6BF883A32, 42.356779,-71.065271,tag1,metadata2,WATER_SENSOR

Activate Devices

An Activated Device may join the network and start uplinking. Devices in this state are not considered "Active" until they have joined the network. Once a Device has joined the network, it appears in the Devices table.

Required column names in the CSV header: devEui

Populate the devEui column with previously registered or Deactivated Device EUIs.

Select Activate in the action, and click the ellipsis to upload a CSV file of previously registered Devices.

screenshot

After a file is selected a confirmation dialog appears.

This dialog requires the user to choose a contract and Device profile for the Devices in the csv file.

Optionally, informational tags may be updated or applied to this group of Devices.

Select Yes to upload the selected file.

Note

Device profiles and contracts are set when a device joins the network. Prior to joining, these values can be preselected. The value selected during activation will override the value selected during registration. If "Current or Default" is selected, the value assigned during registration will be used. If a device was not assigned a contract or profile during registration, the default value configured for the application will be used. After a device joins, the contract can be updated through deactivation.

screenshot

The results of the activation are shown after the file is processed.

screenshot

Example Activation CSV Format

####################################################
# Required Fields: devEui
# Optional Fields: lat, lng, tags, metadata, devType
####################################################
devEui, lat, lng, tags, metadata, devType
AA11111F00000001,42.356959,-71.053271,tag1;tag2,metadata1,WATER_SENSOR
AA11111F00000002,42.356779,-71.065271,tag1,metadata2,WATER_SENSOR

Deactivate Device

A Deactivated Device can continue uplinking if it previously joined the network. Deactivated Devices cannot join or rejoin the network.

A Device must be registered before it can be Deactivated.

A Device that is administratively Deactivated but continues to communicate on the network is in an active billing state. To avoid billing for Deactivated Devices, they must not be heard by the network for the entire billing cycle.

Required column names in the CSV header: devEui

Populate the devEui column with previously Activated or registered Device EUIs.

Select Deactivate in the action, and click the ellipsis to upload a CSV file of previously registered or Activated Devices.

screenshot

After a file is selected a confirmation dialog appears. This dialog requires the user to choose a contract for the Devices in the csv file. The Device's current contract can be used by selecting Current.

Note

The contract can be updated if the devices are Activated from the Deactivated state.

screenshot

The results of the deactivation are shown after the file is processed.

screenshot

Example Deactivation CSV Format

####################################################
# Required Fields: devEui
####################################################
devEui
AA11111F00000001
AA11111F00000002

Device Update

Upload a CSV file to update Device fields for all Registered and Activated Devices. The Devices' latitude, longitude and tags fields can be edited. From the Devices table, select the upload screenshot button to display the window below.

screenshot


When the screenshot button is clicked, a file upload window will be displayed. After a file is selected, click on the Upload File to proceed.

screenshot

Tags in the update can append, replace or delete existing tags based on the selected operation. The tags can be specified for individual Devices using a tags column in the csv file or for the full set of Devices using the tags input. The uploaded latitude and longitude will always replace the existing Device data. Select Yes to upload the previously selected file.

If the upload succeeds and the data is valid, an upload summary and any messages from the server will be displayed. If the upload fails or the data is invalid, an error message will be displayed. Devices included in the CSV will only be skipped if they do not exist.

Example Update CSV Format

####################################################
# Required Fields: devEui
# Optional Fields: lat, lng, tags, metadata, 
#                  devType, devClass, fwVer
####################################################
devEui, lat, lng, tags, metadata, devType, devClass, fwVer
AA11111F00000001,42.356959,-71.053271,tag1;tag2,metadata1,WATER_SENSOR,CLASS_A,1.0.20
AA11111F00000002,42.356779,-71.065271,tag1,metadata2,WATER_SENSOR,CLASS_B,2.1.2

FUOTA

To implement FUOTA, a device must support:

Device vendors must work with their radio-module manufacturers to determine support for the FUOTA protocol layers and whether the radio module itself can be updated by either the host processor or the application stack running on the module. There may be simpler requirements if updates only involve a configuration file rather than an entire (or partial) firmware image. Lastly, LoRaWAN and Regulatory (FCC, ETSI, etc) certification may be impacted by a firmware update.

FUOTA Responsibilities

Since the Network Server does not have specific knowledge of the End Device firmware version, the Application Provider is responsible for detecting devices that did not upgrade properly to the new version and rescheduling failed devices.

FUOTA UI

  1. From the application view in the portal select the devices to upgrade and click the firmware upload button:

    screenshot

  2. Fill in the dialog to transfer the image:

    screenshot

    Contract: List of the Customer’s contracts with Senet.  The selected contract determines how the Customer is billed for the download.

    Start Time: The time scheduled to initialize the download.  A minimum of 3 downlinks are required to setup the multicast group.  This time must accommodate the largest uplink interval among the targeted devices and additionally consider packet loss. 

    Note

    The progression of multicast setup downlinks [McGroupSetup --> McGroupCSess --> FragSessSetup]will not proceed until all corresponding answer uplinks are received.

          Nwk  -- McGroupSetupReq  --> Dev
          Nwk <-- McGroupSetupAns  --  Dev 
          Nwk  -- McGroupCSessReq  --> Dev
          Nwk <-- McGroupCSessAns  --  Dev 
          Nwk  -- FragSessSetupReq --> Dev
          Nwk <-- FragSessSetupAns --  Dev
    

    Fragmentation: List of the currently supported methods used to fragment the file. ○ Forward Error Correction: As defined by the FUOTA specification. ○ Retransmit: The entire file is transmitted multiple times.

    Redundancy: Per the Fragmentation method selected. ○ Forward Error Correction: Redundancy is the percent of additional frames transmitted based on the frame count required to transmit the file once.  For example, a redundancy of 30% for 100 frames would generate a total packet count of 130. ○ Retransmits: Redundancy is the total number of times the file will be sent. For example, a redundancy of 1 for a 100 frames would generate a total packet count of 200.

    Tx Channel: The channel to be used for the multicast transmit.  This should only be modified in response to local interference on the default channel.

    Tx Data Rate: The Data Rate to be used for the multicast transmit.  May be modified adjust time on air or increase the probability of success.

    Packet Delay (ms): The minimum delay allowed between transmission of the data fragment packets.  Any modifications required due to regional duty-cycle restrictions will be handled by the Network.

    Descriptor: The 4 byte descriptor value provided to the targeted devices in the FragSessSetupReq that identifies what will be sent to them.

    File: The binary file to be sent via multicast to the targeted devices using the parameters selected above.

  3. While the devices sessions are initializing, a queued message is presented, indicating when the transfer will start:

    screenshot

    Application commands are pushed to the Devices to setup the multicast and fragmentation sessions:

    screenshot

    screenshot

  4. The firmware update status panel updates the progress as multicast packets are sent out:

    screenshot

  5. Until the full set of multicast packets are distributed:

    screenshot