In Kio Cloud Device Management, you can import third-party devices into your device inventory. You can assign third-party gateway devices, such as Access Points, to their installation location in Kio Cloud Smart Location. For third-party BLE devices, Kio Cloud processes data from Bluetooth Low Energy devices that use one of the supported Kontakt.io BLE formats.
You add third-party devices by importing a CSV file. Once you add them, the devices appear in Device Management and are also available through the Device Management API.
Before you begin
To import external devices, you must be assigned the Device Management Administrator or Inventory Manager role.
How to import external devices
To import third-party devices into your Kio Cloud Device Management inventory, follow these steps.
Note: You cannot import the same external device twice through this process — a device whose Unique ID or MAC address already exists in your company is rejected as a duplicate and the import returns an error. To update external devices you've already imported, edit each device from its profile, or use the export and import options. To update multiple devices at once, see Update multiple devices with a CSV file (bulk edit).
Step 1: Download CSV template
Download CSV template. The template has every column in the table below, in the same order, and one example row with the values from the Example column. The CSV header row is required. Don't change the column names in the template.
This table describes the third-party device data you need to import devices into Device Management. A valid mac, product (Product Name), category, and deployment.status are required. Leave an optional column empty if you don't need it.
| CSV header row | Device Management value | Description | Required | Example |
|---|---|---|---|---|
| uniqueId | Unique ID | Identifies the device: 4–32 letters or numbers, or a MAC address. If not provided, a value is generated automatically. | No | A12dBB |
| mac | MAC address | MAC address that identifies the device in Kio Cloud. It must be unique within your company. For an Access Point, use the MAC address that the AP sends to Kio Cloud as its identifier. See Which MAC address to use for an Access Point. Required format: XX:XX:XX:XX:XX:XX. On import, the MAC address is converted to uppercase. |
Yes | 08:00:04:02:00:00 |
| macs.bleMac | BLE MAC address | MAC address of the device's BLE radio. For an Access Point, put the BLE radio MAC address here, not in mac. If you leave this column empty, Device Management uses the mac value. Required format: XX:XX:XX:XX:XX:XX. |
No | 08:00:04:02:00:01 |
| macs.wifiMac | Wi-Fi MAC address | Wi-Fi MAC address of the device. Required format: XX:XX:XX:XX:XX:XX. |
No | 08:00:04:02:00:02 |
| macs.eddystoneMac | Eddystone MAC address | MAC address that the device uses when it sends Eddystone packets. Required format: XX:XX:XX:XX:XX:XX. |
No | 08:00:04:02:00:03 |
| macs.ibeaconMac | iBeacon MAC address | MAC address that the device uses when it sends iBeacon packets. Required format: XX:XX:XX:XX:XX:XX. |
No | 08:00:04:02:00:04 |
| alias | Notes | User-defined device details and information. | No | White Bulb |
| tags | Tags | Labels used to group or categorize devices. Letters and numbers only, no spaces, up to 32 characters each; separate multiple tags with a comma (up to 20 tags). |
No | external,bulb,white |
| deployment.status | Deployment Status | The device's current lifecycle status. Allowed values: TO_BE_DEPLOYED, DEPLOYED, END_OF_LIFE To assign gateway infrastructure devices (such as Access Points) to their install location in Smart Location, set the status to TO_BE_DEPLOYED — only devices set to TO_BE_DEPLOYED can be assigned to a location. |
Yes | TO_BE_DEPLOYED |
| product | Product Name | Human-readable name of the product. | Yes | External device |
| productCode | Product code | Code that identifies the product type. | No | external_device |
| category | Device category | Where the device appears in Device Management, either the Tags or Infrastructure Inventory menu. Allowed values: TAG, INFRASTRUCTURE Tags are BLE devices that are moving or wearable. Infrastructure devices are stationary, in a fixed position — for example, BLE-enabled Access Points. |
Yes | INFRASTRUCTURE |
Which MAC address to use for an Access Point
An Access Point (AP) has more than one MAC address. It has a LAN (Ethernet) MAC address, and a BLE radio MAC address for its built-in BLE radio. When the AP sends BLE data to Kio Cloud, it uses one of these MAC addresses as its identifier. Kio Cloud uses the mac column to match that identifier to the device that you import.
mac: put the MAC address that the AP sends as its identifier.
macs.bleMac: put the AP's BLE radio MAC address, if you know it. If it's the same as the mac value, leave this column empty.
Step 2: Add external devices to CSV file
Keep the template's column names exactly as provided. The header row is required. You can leave the optional columns empty. If you leave uniqueId blank, Device Management generates a value automatically. Complete the required columns — mac, product, category, and deployment.status — for each device.
Note: Before you edit the file, review the guidelines for using third-party apps to update the CSV file so it's formatted correctly.
Open the CSV file template in an editor such as Notes, Microsoft Excel, or Google Sheets.
-
Replace the example row with one row for each device.
Do not delete the header row or the required columns.
Save the file as a CSV file and continue to the next step.
Step 3: Import the CSV file
Sign in to Kio Cloud and select Device Management from the Launchpad.
-
From the Add Devices menu, select Import External > Select CSV file > upload the CSV file with the external device data.
From the Success notification, select the option to view the CSV file.
-
From the file, review the two import columns (import_status, import_errors) appended to the file to verify the import.
-
For Access Points, make sure that each mac value is the MAC address that the AP sends as its identifier. See Which MAC address to use for an Access Point.
The import checks only the MAC address format and duplicates. It cannot detect that you used the wrong MAC address of an AP.
Step 4: Assign third-party gateways to their install location
This step is optional. It places your third-party gateways, such as Access Points, on a floor plan so you can see them by location. You'll need the gateway's MAC address or Unique ID, and its Deployment Status must be set to To Be Deployed.
Third-party gateways are assigned on the Gateways tab. (BLE-only Kontakt.io Infrastructure devices are assigned separately, on the Infrastructure tab.)
Sign in to Kio Cloud and select Smart Location from the Launchpad.
Navigate to the Campus, Building, and Floor where the gateway is installed.
From the floor, select Edit > select the Gateways tab.
Select Assign new gateway and follow the in-app instructions.
Search and locate external devices
Once you've imported your external devices, use the search and filter options on the Device Management Tags and Infrastructure menus to find them.
This example searches for an external Tag device by its MAC address.
This example uses the filter Criteria option to view external Tag devices, setting the Criteria to Product and selecting the model Example Beacon.
Important guidelines when using third-party apps to update the CSV file
Common third-party apps try to detect the data type in each column and format the numbers for you. This can backfire: the app may convert a large number to scientific notation, which then fails to import into Device Management.
To avoid this, follow these guidelines when you update the CSV file.
CSV file with Excel guidelines
In Excel, create a new blank workbook. From the toolbar, select the Data tab. In the Get External Data section, select From Text/CSV, locate and select the exported CSV file, then select Import.
For all columns, verify they are set to the Text type; do not select General or any other format. Setting the columns to a text format preserves the original data.
CSV file with Google Sheets guidelines
Create a new spreadsheet. Go to File > Import, select the CSV file, clear the Convert text to numbers, dates, and formulas checkbox, then select Import data.
CSV file with LibreOffice guidelines
During the import, from Other Options, (1) select the checkbox next to Format quotes field as text, (2) select all data, (3) Select Column Type, and (4) select Text.