Introduction

Before a device becomes fully operational as a connected node of the system, two things need to happen first:

MODE supports two different mechanisms for your project to provision devices. You should select the option that best suits your device's capabilities and your system's user experience.

Option 1: Device Pre-Provisioning

This is the default mechanism. In this mechanism, you create device instances in the MODE database (via the MODE Developer Console) ahead of time. As you build your device hardware, you copy/flash the assigned device ID and API key to it.

When an end user wants to take a device into her home, she essentially needs to "claim" the ownership of the device and link it to her home. Here is how it is done:

As a first step, the device must make a POST request to the /deviceRegistration endpoint to turn on its claim mode. In the following example, a device's claim mode will be activated for 300 seconds. (Replace _DEVICE_ID_ and _YOUR_API_KEY_ with the actual device ID and API key.)

$ curl -i -N -H "Authorization: ModeCloud _YOUR_API_KEY_" --data "deviceId=_DEVICE_ID_&claimable=1&duration=300" https://api.tinkermode.com/deviceRegistration

The raw HTTP request is as follows:

POST /deviceRegistration HTTP/1.1
Host: api.tinkermode.com
Authorization: ModeCloud _YOUR_API_KEY_
Content-Type: application/x-www-form-urlencoded

deviceId=_DEVICE_ID_&claimable=1&duration=300

If you succeed, you will see a response similar to the following:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Date: Tue, 25 Aug 2015 21:39:37 GMT

{"claimExpirationTime":"2015-08-25T21:44:37.744323372Z"}

The claim mode will expire at the time specified by the claimExpirationTime property of the returned JSON object. You have to finish the device registration process before claim mode expires.

If you passed the wrong device ID, you would see:

HTTP/1.1 403 Forbidden
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Date: Tue, 25 Aug 2015 21:40:24 GMT

{"reason":"MATCHING_DEVICE_ONLY"}

By the way, this is the same the process described here. In the Device Simulator, the Claim Mode button makes this API call.

Now that the device's claim mode is turned on, you should make a POST request to the /devices endpoint to complete the registration process. This API request is supposed to be called by an app. For testing you can use the App Simulator for this step, as described here. Copy and paste the device claim code into the App Simulator, and the device is now added to a home and ready to send events and receive commands.

Option 2: On-demand Device Provisioning

In this mechanism, there is no need to create device instances in the MODE database ahead of time. Instead, a new device entry is created on demand by end users. For this provisioning method to work, the user client (usually a mobile app) must have the ability to transmit a provisioning token directly to the device hardware.

If you wish to use this mechanism to provision your devices, go to the Settings screen of your project on the Developer Console. In the Advanced Options section, enable the On-demand Device Provisioning option.

To initiate device provisioning, the user client makes a POST request to the /homes/_HOME_ID_/deviceProvisioning endpoint, specifying the Device Class and an optional tag of the device to be added. You can use the App Simulator to test this step.

A provisioning token will be issued to the user client, which in turn must pass it to the actual device hardware, probably via direct WiFI, Bluetooth connection, etc. Once the device hardware gets hold of the provisioning token, it should connect to the MODE API and complete the provisioning process by making a POST request to the /devices endpoint, with a token parameter in the request body.

If the device is successfully provisioned and added to the home, the JSON returned by the request will contain the device ID and API key assigned to the device. The device should store the information in a local persistent storage and include the API key for all future communications with MODE. You may also consider programming your device to trigger an event right after the provisioning is done, so that the user client will know when to reload the list of devices in the home and notify the end user.