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
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.
- Device Contracts can only be changed when Transitioning to Deactivated or Activated.
- State Transitions cannot be repeated. Example: an Activated Device cannot be Activated.
| 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.
- Click the
tab - If there are multiple applications; from the EUI column click the application EUI to navigate to the Application Detail View. Otherwise the view will automatically be directed to the Application Detail View.
- From the Application Detail View, Navigate to the Device Management view by clicking on the
button
From the Device Management table, select the upload 
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.
Entering an Authentication Token
When the Upload File button is clicked, the following dialog allows the user to request and submit a token.
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.
Once the upload data is validated an upload summary is displayed.
If the upload fails or the data is invalid, error feedback is provided.
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.
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.
The results of the activation are shown after the file is processed.
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.
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.
The results of the deactivation are shown after the file is processed.
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 button to display the window below.
When the 
button is clicked, a file upload window will be displayed. After a file is selected, click on the Upload File to proceed.
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:
- LoRaWAN FUOTA Ver 1.0.0, a work authored by the FUOTA Working Group of the LoRa-Alliance, including the ability to transition between Class A and Class C operation,(reference implementation provided by Stackforce and Arm Mbed).
- Budget functionality for the additional power requirements associated with large data transport operations
- OS-level primitives and on-board memory to support receiving a relatively large file
- A methodology for replacing some or all of its running image
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
- A file to distribute - patch or full firmware file
- A descriptor value (8 bytes, described in LoRaWAN Fragmented Data Block Transport Specification v1.0.0) of the file being distributed to the target devices
- A list of devices to update
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
-
From the application view in the portal select the devices to upgrade and click the firmware upload button:
-
Fill in the dialog to transfer the image:
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 -- DevFragmentation: 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.
-
While the devices sessions are initializing, a queued message is presented, indicating when the transfer will start:
Application commands are pushed to the Devices to setup the multicast and fragmentation sessions:
-
The firmware update status panel updates the progress as multicast packets are sent out:
-
Until the full set of multicast packets are distributed:
