On-board edge devices using MK.IO API

This page explains how to prepare an edge device, connect it to MK.IO, and register it to a project using the MK.IO API instead of the MK.IO UI. The device must still be connected to the internet.

Prerequisites

• You can access the device’s local web UI at http://<Control-IP-Address>, where <Control-IP-Address> is the IP address of the Control interface of the edge device.
• Or, you can access the device’s terminal with a keyboard and monitor or via SSH.

Add the device to MK.IO

The on-boarding process has two parts:

1. From the device’s local web UI, obtain a short code or device ID. From the device’s terminal, obtain a device ID.
2. Use the code to register the device via the MK.IO API.

Once registered, the device is available for monitoring and control through MK.IO.

Remote on-boarding

The two steps above do not need to be completed by the same person. In a remote on-boarding scenario — where the engineer installing the device does not have access to MK.IO — they can pass the short code verbally (for example, by phone) to the MK.IO user who has permission to register it.

Configure an HTTP proxy (optional)

A proxy only needs to be configured when internet connectivity for MK.IO is only possible via a proxy. You can also set a proxy from the terminal using the control-wizard command.

1. Open the device’s local web UI: http://<Control-IP-Address>.
2. Go to Appliance > Fleet.
3. Click next to the Connected field.
4. Enter the Proxy IP Address, Port, Username, and Password.
5. Click Apply.

Connect the device to MK.IO from the device UI

1. Open the device’s local web UI: http://<Control-IP-Address>.
2. Go to Appliance > Fleet. After a few seconds, additional information appears.
3. Confirm the Connected field shows Yes. This confirms the device can reach MK.IO. Click to run diagnostics if needed.
4. Note that the Registered field shows No until you complete registration.
5. Copy the short code (eight random letters and numbers) from this page.

The short code rotates periodically. Keep the device UI open until you complete registration — the UI updates automatically when the code changes. Alternatively, copy the device ID from the UI or the terminal.

Add the device using the MK.IO API

Register the device using the short code in the spec.shortCode field. Alternatively, use the longer-lived device ID shown in the device web UI or terminal in the spec.locationId field:

PUT https://app.mk.io/api/v1/projects/project_name/fleet/devices/device1

{
  "metadata": {
    "displayName": "Device 1"
  },
  "spec": {
    "siteName": "world",
    "locationId": "a7dafdba-4923-4317-aad1-dc76284b85b5"
  }
}

Verify on-boarding

Once the device is registered, go back to Appliance > Fleet in the device’s local web UI. The Registered field shows Yes and displays the device’s name.

You can now view device information and access the remote UI.

Update device software

Once the device is registered, before commissioning, update the device software to the latest version.