LoRa Basics Modem and LoRa Edge documentation

Scenario - Claiming a Device

Introduction

To use the LoRa Cloud™ Device Join service, a LoRa Edge™ device (any device with an LR111x chip) must be claimed via the LoRa Cloud web portal or API. This claiming process validates the claim via a PIN (an owner verification code) that proves ownership of the device. Once claimed, the device can join a LoRaWAN network via a join request.

In contrast to services where the join server is embedded in (or provided by) a LoRaWAN network server, using the LoRa Cloud Device Join service never exposes the AppKey of the device. Rather, the keys are embedded in a Hardware Secure Module (HSM). Even the Join Server does not see them. While device keys must also be provided to embedded join servers in order to authenticate a device, in the case of the LoRa Cloud Device Join service, as mentioned above, a PIN is provided as the authorization required to claim a device. That device is then associated with the owner’s account.

Compatibility

LoRa Basics Modem

LoRa Basics Modem-E

Prerequisites

Common:

Before a successful claim can be made, the PIN must be extracted from the LoRa Edge/LR111x chip.

To extract personalized data from the LR111x chip:

  1. The LR111x chip owner causes the device application to request the DevEUI/ChipEUI and the PIN.

  2. The device application requests the DevEUI/ChipEUI and the PIN from the LR111x chip.

  3. The LR111x chip returns the DevEUI/ChipEUI and PIN to the device application.

  4. The device application returns the DevEUI/ChipEUI and PIN to the device owner.

Note

The device application may be running on an end device. Alternatively, the application could be part of a test fixture setup for provisioning chips.

To extract personalized data from a QR Code:

Each LR111x chip has a corresponding QR Code printed on the end device that contains the DevEUI/ChipEUI and PIN. Each QR code contains data similar to the following:

Preface

LW

SchemaID

D0

JoinEUI

00-16-C0-01-FF-FE-00-01 (from example below)

DevEUI

00-16-C0-01-F0-00-5B-CF (from example below)

ProfileID

016A-0002 (from example below)

[O]wnerToken

FAC78379: PIN of the LoRa Edge LR111x (from example below)

Mfg [S]erial Number

YYWWNNNNNN (Year, Week, Serial Number, 2040005BCF from example below)

[P]roprietary

US915 (from example below)

[C]heckSum

(CRC-16/MODBUS): HHHH, 4A93 (from example below)

../../_images/QR_image_HDR.jpg

Scan value: LW:D0:00116C001FFFE001:0016C001F0005BCF:016A0002:OFAC78379:S2040005BCF:PUS915:C4A93

Step-by-Step Procedure

To claim a device, the device owner sends DevEUI/ChipEUI information and PIN to the LoRa Cloud Device Join service via the API or the LoRa Cloud web portal.

  1. If the claim is accepted, the owner is notified that the device has been successfully claimed.

  2. If the claim is not accepted, the LoRa Cloud Device Join service returns an error message to the owner.

@startuml device_claimbox Device #LightBlue    participant "End-Device \nApplication" as App #LightBlue    participant "<color #000000 >LR111x</color>" as LoRa  #00ADEF end box box LoRaWAN #AAAAAA    participant "Gateway" as GW #LightGrey    participant "Network Server" as NS  #LightGrayend boxbox LoRa Cloud Services #00ADEF     participant "<color #000000 >LoRa Cloud Device Join</color>" as JS #00ADEFend boxactor Owner as Owner #LightBluelegend left|=             |= Owner || <#00ADEF>    | Semtech || <#ADD8E6>    | Customer || <#D3D3D3>    | Ecosystem |endlegend== Claiming - OK ==Owner -> JS : DevEUI/ChipEUI,PINJS -> Owner : OKdeactivate JS== Claiming - Fail/Previous == Owner -> JS : DevEUI/ChipEUI,PINJS -> Owner : Fail@enduml

Note

Once the device owner successfully claims a chip or end device with a chip inside, it cannot be claimed by someone else. Correspondingly, if the chip or end device has been claimed by some other entity, the claim request will return an error. To allow a claimed device to be claimed by another, you must first unclaim the device.

Used By

Device owner, embedded application on an embedded MCU or test fixture to extract DevEUI/ChipEUI and PIN.

Troubleshooting

If a DevEUI/ChipEUI receives and error message when making a claim request:

  • The ChipEUI may have been previously claimed

  • There could be a typo in the DevEUI/ChipEUI or in the PIN

References