Register and Activate Your End Device

Create a Device Profile Using a Template

If you bought a device from a manufacturer, the Semtech Network Server should have a device profile template that can be used to generate the device profile. This means you don’t have to figure out all the settings and makes it simple to add a device. If you cannot find your device using this method, or have built your device, instead follow the steps in the Create a Custom Device Profile section below.

1. Log in to the Semtech Network Server website if you haven’t already done so.

2. Click Device profiles in the menu on the left.

3. Click Add device profile.

4. Click the Select device-profile template button. The Select device-profile template popup appears.

   

5. Click the Select a device-profile template dropdown in the Select device-profile template popup.

6. A list of device manufacturers appears. Scroll down to find the manufacturer of your end device and click its name.

7. A list of one or more devices sold by the selected manufacturer appears next to their name. Click on the device you own.

8. A list of one or more firmware versions available for the selected device appears next to the device name. Click on the firmware version for the device you own.

   If you are not sure of the firmware version, check the datasheet that came with the device.

9. A list of one or more supported regions available for the device and firmware version appears next to the firmware version. Click on the region your device supports.

   

10. The template name appears in the Select a device-profile template dropdown. Make sure that this is all correct, and then click the OK button to select the template.

11. The template populates all the fields in the device profile for you.

12. If you would like, update the Device-status request frequency (req/day) field to the number of times per day you would like the network server to send the End Device Status MAC Command (DevStatusReq) to the end device, following receipt of an uplink. This MAC command will cause the end device to respond with its battery level and radio status.

    Note

    Unless the end device sends a Class A uplink the same number of times per day, it will not receive the number of DeviceStatusReq MAC commands set here. This is the maximum number of requests for Device Status the network server will send per day.

13. Select the Codec tab. Here, the device manufacturer should have defined a payload codec that informs the Semtech Network Server how to decode and encode the binary application data payload. Read the ChirpStack documentation Device profiles page to learn how the codecs are constructed.

14. Click Submit to save. The device profile appears in the Device profiles list.

You have now created a device profile. The device profile is used to add each device to the Semtech Network Server in the next section.

Create a Custom Device Profile

Create a custom device profile if you built your device or purchased a device not found in the templates.

1. Log in to the Semtech Network Server website if you haven’t already done so.

2. Click Device profiles in the menu on the left.

3. Click Add device profile.

4. Complete the fields in the open General tab as follows:

   • Name:

     Enter a profile name to represent the device model and firmware version, e.g., My Test Device 1.0. Spaces are allowed.

   • Description:

     Optionally enter a free text description of your device type, e.g., Testing device for learning.

   • Region:

     Select the frequency plan for your device’s region, as listed in the Semtech Network Server website’s Regional Support table.

   • MAC version:

     Set this to the version of the LoRaWAN specification implemented by your end device.

   • Regional parameters revision:

     LoRaWAN has regional specifications that govern channel plans, default data rates, and other physical layer parameters for each LoRaWAN region. These specifications are listed in the LoRaWAN Regional Parameters document. The latest revision of the LoRaWAN Regional Parameters document can be found on the LoRa Alliance® Technical Specifications page.

     There are several revisions of the Regional Parameters document, which were initially associated with a specific LoRaWAN version, and are now published separately as a single document covering all LoRaWAN versions.

     To operate correctly for your device, the network server needs to know which of the Regional Parameters document revisions was implemented by the device manufacturer.

     If you built your device, check the documentation for the LoRaWAN stack implementation you used. Find the revision used by LoRaMAC-Node in the RP Spec column of the table in the Introduction section of the LoRaMac-node GitHub page. Find the revision used by LoRa Basics™ Modem in the LoRaWAN regional parameters section of the LoRa Basics Modem GitHub page.

     If you purchased the device, you need to check the datasheet or ask the device manufacturer which document revision they used.

     When you click the Regional parameters revision dropdown, the letters A and B display as well as several full document revision names, e.g., RP002-1.0.3,. The letters A and B relate to the revisions associated with specific LoRaWAN versions. The full document revision names represent the document revisions that cover all LoRaWAN versions.

     • If your end device implements LoRaWAN specification 1.0.1 with the regional parameters document integrated into the LoRaWAN v1.0.1 specification, choose A.

     • If your end device implements LoRaWAN specification 1.0.2 with LoRaWAN Regional Parameters v1.0.2rB, choose B.

     • If your end device implements LoRaWAN specification 1.0.3 with LoRaWAN Regional Parameters v1.0.3rA, choose A.

     • If your end device implements LoRaWAN specification 1.1 with LoRaWAN Regional Parameters v1.1rA, choose A.

     In all other cases, choose the relevant document revision.

     If you are unable to discover which document revision was used, choose A, and see if the end device joins successfully and sends data. If it does not, work your way through the options until you see a successful join.

   • ADR algorithm:

     The ADR algorithm determines how the network server controls the data rate and transmit power of this device group to use as little airtime and energy as possible.

     If your device does not use Long Range Frequency Hopping Spread Spectrum (LR-FHSS) data rates, choose Default ADR algorithm (LoRa® only).

     If your device only uses LR-FHSS, choose LR-FHSS only ADR algorithm.

     If your device uses both LR-FHSS and LoRa data rates, choose LoRa & LR-FHSS ADR algorithm.

     Learn more about ADR and LR-FHSS.

     Note

     You must use an LR-FHSS compatible gateway to receive transmissions made using LR-FHSS data rates.

   • Flush queue on activate:

     Downlinks can be queued to be sent to a device using the device page. Until messages have been sent, they remain in a queue. If you set Flush queue on activate to on, this queue will be emptied if a device re-joins the network and the messages will never be sent to the device. If you set Flush queue on activate to off, this queue will remain and the messages will be sent to the device. Your use case will determine which setting you choose. If you are not sure which to choose, leave the default setting and modify it later.

   • Expected uplink interval (secs):

     This setting is used so that the network server can decide whether a device is active or inactive on the dashboard. The device will still work if this setting does not match the actual uplink interval. Set this to the number of seconds between each regular message the device sends. This can be found in the documentation for a device from the manufacturer, or in the firmware code for a device you built yourself.

   • Device-status request frequency (req/day):

     Set the number of times per day you would like the network server to send the End Device Status MAC Command (DevStatusReq) to the end device, following receipt of an uplink. This MAC command will cause the end device to respond with its battery level and radio status.

     Note

     Unless the end device sends a Class A uplink the same number of times per day, it will not receive the number of DeviceStatusReq MAC commands set here. This is the maximum number of requests for Device Status the network server will send per day.

5. Click the Join (OTAA/ABP) tab.

6. If your device supports Over-the-Air Activation (OTAA), make sure the switch next to Device supports OTAA is on, and move on to the next step.

   If your device supports Activation-by-Personalization (ABP), click the switch next to Device supports OTAA to turn it off, and complete the form as follows:

   • RX1 delay:

     Enter the delay programmed onto your device between the end of the uplink transmission and the opening of the first receive window (RX1). This is referred to as RECEIVE_DELAY1 in all versions of the LoRaWAN® Specification, and all LoRaWAN Regional Parameters document revisions.

     Note

     If you cannot find the RX1 delay used by your device, try using the value 1, which is the recommended default in all LoRaWAN Regional Parameters document revisions up to and including RP002-1.0.3.

   • RX1 data-rate offset:

     Enter the offset your device uses to calculate the data rate for the first receive window (RX1). This is referred to as RX1DROffset in all versions of the LoRaWAN Specification and all LoRaWAN Regional Parameters document revisions.

     Note

     If you cannot find the RX1 data-rate offset used by your device, use the value 0, which is the recommended default in all LoRaWAN Regional Parameters document revisions up to and including RP002-1.0.3.

   • RX2 data-rate:

     Enter the data rate your device uses in the second receive window (RX2). This is referred to as RX2DataRate in all versions of the LoRaWAN specification and all LoRaWAN Regional Parameters document revisions.

     Note

     If you cannot find the RX2 data rate used by your device, use the default value for your region. This is found in the LoRaWAN Regional Parameters document revision implemented by your device, found on the LoRa Alliance® Technical Specifications page. In RP002-1.0.3 LoRaWAN Regional Parameters, and all other RP002-1.0.x revisions, the default RX2 data rate for each region is found in the ‘Receive Windows’ section for the region your end device operates in.

   • RX2 frequency (Hz):

     Enter the frequency your device uses for the second receive window (RX2). This is referred to as the RX2 Frequency in all versions of the LoRaWAN Specification and all LoRaWAN Regional Parameters document revisions.

     Note

     If you cannot find the RX2 frequency used by your device, use the default value for your region. This is found in the LoRaWAN Regional Parameters document revision implemented by your device, found on the LoRa Alliance® Technical Specifications page. In RP002-1.0.3 LoRaWAN Regional Parameters, and all other RP002-1.0.x revisions, the default RX2 frequency for each region is found in the ‘Receive Windows’ section for the region your end device operates in.

7. If your device can implement Class B operation mode, select the Class-B tab, and click the switch next to Device supports Class-B.

   Enter the Class B timeout used by your device when waiting for confirmed downlink transmissions. This is referred to as the CLASS_B_RESP_TIMEOUT in the TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification and the RP002-1.0.2 and RP002-1.0.3 revisions of the LoRaWAN Regional Parameters document.

   Note

   If you cannot find the Class B timeout used by your device, use the value 8, which is the recommended default in the RP002-1.0.2 and RP002-1.0.3 revisions of the LoRaWAN Regional Parameters document.

8. If your device can implement Class C operation mode, select the Class-C tab, and click the switch next to Device supports Class-C.

   Enter the Class C timeout used by your device when waiting for confirmed downlink transmissions. This is referred to as the CLASS_C_RESP_TIMEOUT in the TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification and the RP002-1.0.2 and RP002-1.0.3 revisions of the LoRaWAN Regional Parameters document.

   Note

   If you cannot find the Class C timeout used by your device, use the value 8, which is the recommended default in the RP002-1.0.2 and RP002-1.0.3 revisions of the LoRaWAN Regional Parameters document.

9. Click the Codec tab if you want to create a payload codec, so that the Semtech Network Server can encode and decode device payloads for you.

   If your device sends application data using the Cayenne Low Power Payload specification, select Cayenne LPP at the Payload codec dropdown.

   Otherwise, select JavaScript functions. The Codec functions field appears. Learn how to write the custom functions on the ChirpStack documentation Device profiles page and paste in your code.

   Note

   Decoded payloads appear in the object field of the Details pane in the Events tab of the devices page. Decoded payloads can also be used to create measurements, which are then rendered in graphs in the Device metrics tab of the device dashboard.

   Encoded payloads allow you to write downlinks using JSON on the Queue tab of the device page.

10. Click Submit to save. The device profile appears in the Device profiles list.

You have now created a device profile. The device profile is used to add each device to the Semtech Network Server in the next section.

Add OTAA Keys for LoRaWAN Specification 1.0.x

Complete these steps if your end device implements OTAA activation and LoRaWAN specification versions 1.0.1, 1.0.2, 1.0.3, or 1.0.4.

1. Make sure the device tab OTAA keys is selected.

2. Paste the APP_KEY for the end device you found in the section Find Your End-Device Activation Keys into the Application Key field.

   Note

   If you copied the key from somewhere that displays the key using the least significant bit (LSB) format, click the MSB button and select LSB in the drop-down before pasting the key.

   If you are using the Arduino LMIC library, the os_getDevKey method uses MSB.

   If you are unsure, keep the MSB option set, and revisit this area if the device does not join.

3. Click Submit to update the application key.

Add OTAA Keys for LoRaWAN Specification 1.1.x

Complete these steps if your end device implements OTAA activation and LoRaWAN specification version 1.1.0.

1. Make sure the device tab OTAA keys is selected.

2. Complete the form as follows:

   • Application key:

     Enter the APP_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   • Network key:

     Enter the NWK_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   Note

   If you copied the APP_KEY or NWK_KEY from somewhere that displays the key using the least significant bit (LSB) format, click the MSB button and select LSB in the drop-down before pasting the key.

   If you are unsure, keep the MSB option set, and revisit this area if the device does not join.

3. Click Submit to update the keys.

Add ABP Keys for LoRaWAN Specification 1.0.x

Complete these steps if your end device implements ABP activation and LoRaWAN specification versions 1.0.1, 1.0.2, 1.0.3, or 1.0.4.

1. Select the Activation tab.

2. Set the keys in the form as follows:

   • Device Address:

     Enter the DEV_ADDR for the end device you found in the Find Your End-Device Activation Keys section.

   • Network session key (LoRaWAN 1.0):

     Enter the NWK_S_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   • Application session key (LoRaWAN 1.0):

     Enter the APP_S_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   Note

   If you copied the DEV_ADDR, NWK_S_KEY, or APP_S_KEY from somewhere that displays the key using the least significant bit (LSB) format, click the MSB button and select LSB in the drop-down before pasting the key.

   If you are unsure, keep the MSB option set, and revisit this area if the device does not join.

3. If your end device has never been connected to a network, leave Uplink frame-counter and Downlink frame-counter set to 0.

   If your end device has already been used on a network server, you need to either reset the frame counters (FCnt and FCntDown) or find out what they are to update the network server.

   Reset the Frame Counters:

   To reset the frame counters, follow the instructions supplied with your device. Alternatively, a factory reset may result in the resetting of the frame counters. You can then leave Uplink frame-counter and Downlink frame-counter set to 0.

   Update the Frame Counters:

   To find out what the frame counters are, inspect the frames on the network server your device is currently connected to. The FCnt is visible when viewing messages sent from the device, and the FCntDown is visible when viewing messages sent from the network server to the device.

   If your device has an FCnt higher than zero, set the Uplink frame-counter to be one higher than your device’s FCnt. For example, if your FCnt is 2, set this to 3.

   If your device has an FCntDown higher than zero, set the Downlink frame-counter to be one higher than your device’s FCntDown. For example, if your FCntDown is 2, set this to 3.

   Note

   If you cannot find the frame counters, try leaving Uplink frame-counter and Downlink frame-counter set to zero. If you then see errors in the devices Events tab, you can disable frame counters by clicking on the Configuration tab and setting the Disable frame-counter validation to on.

4. Click the (Re)activate device button to save the device address, keys, and frame counter settings.

Add ABP Keys for LoRaWAN Specification 1.1.x

Complete these steps if your end device implements ABP activation and LoRaWAN specification version 1.1.0.

1. Select the Activation tab.

2. Set the keys in the form as follows:

   • Device address:

     Enter the DEV_ADDR for the end device you found in the Find Your End-Device Activation Keys section.

   • Network session encryption key:

     Enter the NWK_S_ENC_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   • Serving network session integrity key:

     Enter the S_NWK_S_INT_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   • Forwarding network session integrity key:

     Enter the F_NWK_S_INT_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   • Application session key:

     Enter the APP_S_KEY for the end device you found in the Find Your End-Device Activation Keys section.

   Note

   If you copied the DEV_ADDR, NWK_S_ENC_KEY, S_NWK_S_INT_KEY, F_NWK_S_INT_KEY, or APP_S_KEY from somewhere that displays the key using the least significant bit (LSB) format, click the MSB button and select LSB in the drop-down before pasting the key.

   If you are unsure, keep the MSB option set, and revisit this area if the device does not join.

3. If your end device has never been connected to a network, leave Uplink frame-counter, Downlink frame-counter (network), and Downlink frame-counter (application) set to zero.

   If your end device has already been used on a network server, you need to either reset the frame counters (FCnt, AFCntDown, and NFCntDown) or find out what they are to update the network server.

   Reset the Frame Counters:

   To reset the frame counters, follow the instructions supplied with your device. Alternatively, a factory reset may result in the resetting of the frame counters. You can then leave Uplink frame-counter, Downlink frame-counter (network), and Downlink frame-counter (application) set to 0.

   Update the Frame Counters:

   To find out what the frame counters are, inspect the frames on the network server your device is currently connected to. The FCntUp value is found in the frame counter (FCnt) field when viewing messages sent from the device to the network server. The AFCntDown value is found in the frame counter (FCnt) field when viewing messages sent from the network server to the device that contain application data, where the FPort field is set between 1 and 225.

   When MAC commands are sent from the network server to the device (when the FPort is set to 0, or is not set), the FCnt field contains the NFCntDown value. When application data is sent from the network server to the device (when the FPort is set between 1 and 223), the FCnt field contains the AFCntDown value.

   If your device has an FCntUp higher than zero, set the Uplink frame-counter to be one higher than your device’s FCntUp. For example, if your FCnt is 2, set this to 3.

   If your device has an NFCntDown higher than 0, set the Downlink frame-counter (network) to be one higher than your device’s NFCntDown. For example, if your NFCntDown is 2, set this to 3.

   If your device has an AFCntDown higher than zero, set the Downlink frame-counter (application) to be one higher than your device’s AFCntDown. For example, if your AFCntDown is 2, set this to 3.

   Note

   If you cannot find the frame counters, try leaving Uplink frame-counter, Downlink frame-counter (network), and Downlink frame-counter (application) set to zero. If you then see errors in the devices Events tab, you can disable frame counters by clicking on the Configuration tab and setting the Disable frame-counter validation to on.

4. Click the (Re)activate device button to save the device address, keys, and frame counter settings.