Skip to main content

Bulk Device Commissioning

Overview​

Add many devices to one application in TEKTELIC KONA Core Network Server from a CSV file. Device bulk commissioning reads the file, creates one device for each row and reports which rows failed. At the end, the devices are in the application and join the LoRaWAN® network with OTAA when they're turned on.

All devices from one file get the same device model and the same settings. To add a single device, see Onboard a TEKTELIC Device.

Before you start​

Prepare the file​

The file is a CSV file with a header row and one row per device. KONA Core reads it as follows:

  • Separator: a comma. Quotes aren't supported, so no value may contain a comma.
  • Header row: the first row holds the column names. KONA Core finds each column by its exact name.
  • Rows: every row has as many cells as the header row. Empty rows are skipped.
  • Values: hexadecimal, without spaces or separators such as - or :.
ColumnUseValue
DEVEUISets the Device EUIThe DevEUI, 16 hexadecimal characters
APPEUISets the Application EUIThe JoinEUI (AppEUI), 16 hexadecimal characters
APPKEYSets the Application KeyThe AppKey, 32 hexadecimal characters
Any other column, for example NAMECan build the device name, and is added to the DescriptionAny text without commas

The file has no columns for an ABP device address or session keys. Use the file for OTAA devices, and add ABP devices one by one: see Onboard a Third-Party Device.

For a TEKTELIC device whose APPEUI starts with 647FDA, APPKEY can be empty when the device is registered in the Join Server. The prefix alone isn't sufficient. Otherwise, provide the device's AppKey.

The dialog's File example button downloads a sample file, Device_Bulk_Commissioning_sample.csv. Its first rows look like this. The values are placeholders, not real devices:

NAME,DEVEUI,APPKEY,APPEUI
DEVICE 1,647FDA0000000000,647FDA0000000000647FDA0000000000,647FDA0000000000
DEVICE 2,647FDA0000000001,647FDA0000000001647FDA0000000001,647FDA0000000001
DEVICE 3,647FDA0000000002,647FDA0000000002647FDA0000000002,647FDA0000000002

The file holds AppKeys, which are secrets. Delete it once the devices are added. See Security & Keys.

Steps​

  1. In the side menu, select Applications.

  2. In your application's row, select the Manage devices icon. The application's devices page opens.

  3. Select Device bulk commissioning (the file icon next to Add Device). The Device bulk commissioning dialog opens.

    Device bulk commissioning icon on the devices page of an application

  4. Optional: select File example to download the sample file.

  5. Select Select a file, and choose your CSV file. The dialog shows which columns it uses: DEVEUI for the device EUI, APPEUI for the Application EUI and APPKEY for the Application Key. Until you select a file, it shows No file for commissioning selected, and the other fields are unavailable.

    Device bulk commissioning dialog before a file is selected

  6. Select the Device model for all devices in the file.

  7. Build the device name under Add the column names and delimiters (press 'Enter' key after column name or delimiter typed). Type a column name, for example NAME, and press Enter. Each entry that matches a column name is replaced by that row's value. Any other entry is used as literal text, for example - between two columns. The entries are joined without spaces. At least one entry is required.

  8. Optional: enter an Inactivity Timeout (sec) for all devices. See Device Activity & Status.

  9. Select Use application settings, so the devices use the network settings of the application. We recommend it. See Network Settings.

  10. Leave ABP activation cleared, so the devices join with OTAA.

  11. Leave Add all the other column values to description selected. KONA Core then writes each column that isn't used for the name or the keys into the device's Description, one line per column, as <column> - <value>. To pick the columns yourself, clear the option and enter the column names.

  12. Select Start commissioning. It's available once a file, a device model and at least one name entry are set. KONA Core creates the devices one row at a time.

  13. Read the result text in the dialog. It ends with the number of created devices, for example 8 Devices has been created. Above it, the dialog lists an error message for each row that failed.

    Device bulk commissioning result reporting that 6 devices have been created

  14. Close the dialog with the X icon. The devices list reloads with the new devices.

To add devices from your own system instead, use Save device once per device. The dialog sends the same request for each row.

Check the result​

  1. Compare the number in the result text with the number of rows in your file.
  2. On the application's devices page, check that the new devices are listed with the right Name, Device model and Device EUI. New devices show the status Offline until they join.
  3. Open one device and check its Device details tab: Application EUI, Description, and Use application settings.
  4. Turn on a device, and check that it joins and sends its first uplink. See Onboard a TEKTELIC Device.

Troubleshooting​

SymptomLikely causeWhat to do
The result shows File isn't formed properly. Row <n> has <x> cells, but table heading has <y> cells.A row has more or fewer cells than the header row, for example because a value contains a comma. KONA Core skips that row.Fix the row in the file. Then create a file with only the skipped rows, and run the commissioning again.
The result shows Device with DevEUI '647FDA0000000007' already present in database! for a row.The DevEUI already exists.Check the existing device. Retry only rows that still need to be created.
The result shows Maximum allowed customer devices limit reached! for a row.Adding the device would exceed the Customer's device limit.Free subscription capacity or request a larger plan, then retry the failed rows.
The result lists another error for a row.KONA Core rejected an invalid value. confirm the exact error message for an invalid key.Correct the value and retry only the failed rows.
Start commissioning stays unavailable.No device model is selected, or no name entry is set.Select the Device model, type a column name or text for the name, and press Enter.

If the devices are created but don't join, see the troubleshooting in Onboard a TEKTELIC Device.

If all rows fail, the result ends with 0 Devices has been created. Each duplicate row has its own error above that summary.

Still stuck? A Sub-Customer contacts their Customer, a Customer contacts their Provider, and a Provider contacts TEKTELIC Support. Send the result text, the time in UTC, the header row and one failing row with the AppKey removed, and a screenshot. Never send the whole file with keys.