Initializing and Onboarding

The SDKs must be initialized from the application.

This topic explains how to initialize the SDKs for stand-alone things. If you connect things using the gateway feature of Thing Interaction Framework, use the initialization method described in Initializing and Onboarding with Gateway.

Follow the steps below to initialize the SDKs.

1. Initialize Kii Cloud SDK

2. Initialize Thing-IF SDK (Including the owner and schema definition)

3. Install Devices

4. Execute Onboarding

Initializing the Kii Cloud SDK

Add the following code in the AppDelegate's application:didFinishLaunchingWithOptions method.

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    // Initialize the Kii Cloud SDK. Call this method before any other Kii SDK API calls.
    Kii.beginWithID("___APPID___", andKey: "___APPKEY___", andSite: KiiSite.JP)

    // Override point for customization after application launch.
    return true
}

Replace the placeholders ___APPID___ and ___APPKEY___ with your application's AppID and an arbitrary value, respectively.

You can safely embed the AppID in your application as long as you apply the correct access control. See Security for more information.

Initializing the Thing-IF SDK

Next, initialize the Thing-IF SDK with the following sample code. You can execute the sample code at any time as long as the Kii Cloud SDK initialization explained in the previous step is done.

// Instantiate your application on Kii Cloud.
let app = App(appID: "___APPID___", appKey: "___APPKEY___", site: Site.JP)

// Instantiate a Thing-IF API from a ThingIFAPIBuilder instance.
let api = ThingIFAPIBuilder(app: app, owner: owner).build()

You will get an ThingIFAPI instance as api.

• Replace the placeholders ___APPID___ and ___APPKEY___ with your application's AppID and an arbitrary value, respectively (See Creating a Kii Application for the details).

• owner represents a user who will be the owner of the thing. See Defining an Owner to learn how to get them.

  There are many ways to specify the user (owner). Which method to select depends on the design of the mobile app. In this guide, we will present a method with a pseudo user that does not require any explicit user registration and login. If you want to implement the explicit user login, you will need to provide a login screen and initialize the Thing-IF SDK after the login processes are done.

When initialization is complete, you can get the instance that implements the API. By executing the build method of the ThingIFAPIBuilder, the SDK is initialized, and you will get an ThingIFAPI instance. Preserve the ThingIFAPI instance somewhere, for example in the class field, so that you can call it in the subsequent processes. You can also use the method explained in Saving and Restoring the Initialized Information to preserve the instance and restore it when the process is relaunched.

You can initialize multiple ThingIFAPI to handle multiple schema and things. In this case, specify a unique tag in the tag parameter of the ThingIFAPIBuilder method. The tag is used to identify each ThingIFAPI instance, and it will be used when you save and restore the instance.

Installing a device

You need to install the device so that it can receive responses from the thing. This action associates the owner with the APNs device token on Kii Cloud.

Installing a device

Use the ThingIFAPI instance you've got in the previous step to install the device. The sample code is as follows:

// Register the device token for the thing owner to Kii Cloud.
api.installPush(deviceToken, development: true, completionHandler: { (installationID: String?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

• In the deviceToken parameter, set the device token that you've obtained as the paremeter of the application:didRegisterForRemoteNotificationsWithDeviceToken method as NSData. See Modification for Thing-IF for the details.

• In the development parameter, set true to select the development environment. For the production environment, set the parameter to false.

• This API is a non-blocking API and will be executed in the background. When the execution is completed, the completionHandler will be called.

When the device is installed, the owner specified upon creating the ThingIFAPI will be associated with the device token and registered to Thing Interaction Framework. The installation process overwrites the previous device token if any and push notifications to the previous owner will not be sent to this device any longer.

Uninstalling a device

Execute the following code to uninstall the device.

// Unregister the device token for the thing owner from Kii Cloud.
api.uninstallPush(nil, completionHandler: { (error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

This code assumes that the device is installed. In the first argument of the uninstallPush method, pass the installationID you've received in the installPush's completionHandler. If you pass nil, the ID stored in the ThingIFAPI (api) will be released.

This API is executed asynchronously. When the execution is completed, the completionHandler will be called.

If the uninstallation is successful, the push notification will be no longer deliver to this device.

Onboarding

To control a thing from a mobile app, you need to bind the application to the thing. This binding process is called Onboarding.

The onboarding can be made in one of the following two ways:

• Onboarding from the mobile app

• Onboarding from both the thing and the mobile app

You will get the same result for both, but their flows are a bit different. Use the method that matches well with how your thing is to be implemented.

For the overview of the onboarding process, see Onboarding in the Function Guide.

You need to execute the onboarding before executing any ThingIFAPI method (other than onboarding). Any attempt to execute a method (e.g., executing a command and getting a thing state) without the onboarding will give you an error.

Onboarding from the mobile app

In this method, the mobile app will handle the most of the binding processes.

As explained in Onboarding in the Function Guide, in this method, only the mobile app will access Thing Interaction Framework to perform the onboarding. This will allow the implementation of the thing simple. You need, however, to establish a secure connection between the mobile app and the thing (e.g., via Bluetooth) to share the result of the onboarding to the thing.

Step 1: Onboarding from the mobile app

First, the mobile app gets the thing's vendorThingID and thingPassword from the thing. This information is required for performing the onboarding.

Pass the information to the mobile app in any desirable way (See Thing identifier for more discussion).

The following sample code shows how you can onboard the thing from the mobile app.

// Set the thing credentials.
let vendorThingID = "nbvadgjhcbn"
let thingPassword = "123456"

// Set onboarding options.
let thingType = "AirConditioner"
let interval = DataGroupingInterval.INTERVAL_15_MINUTES
let options = OnboardWithVendorThingIDOptions(thingType: thingType, thingProperties: nil, interval: interval)

// Onboard the thing.
api.onboardWithVendorThingID(vendorThingID, thingPassword: thingPassword, options: options, completionHandler: { (target: Target?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

We are setting the following values in the onboard method.

• vendorThingID: The ID of the thing that the thing vendor assigned. See here for more information. Any string with alphanumeric, hyphen, underscore and period up to 200 characters is accepted as long as it is unique in the application. This field value cannot be modified later.
• thingPassword: The password of the thing. Basically, a unique password is assigned to each thing to secure the resources allocated for the thing in Thing Interaction Framework. You cannot change the password later.
• thingType: The type of the thing. Any string with alphanumeric, hyphen, underscore and period up to 100 characters is accepted. Specify the same type that you've assigned in the schema.
• thingProperties: The properties of the thing in JSON Object format. These properties are useful when you use the Kii Cloud SDK together with the Thing-IF SDK. In this example, we are setting an empty JSON string (nil).
• interval: The grouping interval for storing state history. The history will not be stored if no grouping interval is specified. The available intervals are INTERVAL_1_MINUTE, INTERVAL_15_MINUTES, INTERVAL_30_MINUTES, INTERVAL_1_HOUR, and INTERVAL_12_HOURS. See this page for the details.

The Target and error information will be notified to the completionHandler. The Target will be stored in the ThingIFAPI (api), so you can safely ignore it at this moment.

Note that once you onboard a thing, the thingType, thingProperties and interval will be fixed on the device. An attempt to modify these values later will be ignored.

Note that the state history is not available until onboarding from the mobile app completes. The thing can upload state information but it is not stored as history data until the first mobile app gets associated with the thing.

Step 2: Initializing the thing

The mobile app needs to pass the result of the onboarding to the thing. More specifically, the mobile app needs to get the thingID and access token of the thing with the following sample code and pass them to the thing.

You can also get the target from an argument of the onboard's completionHandler.

// Instantiate the thing.
let target = api.target

// Get the thing ID.
let thingID = target.typedID.id

// Get the thing access token.
let thingAccessToken = target.accessToken

Once the thing gets this information, it will execute the initialization (the thing will not access Thing Interaction Framework in this initialization). See here for the details.

The access token is the confidential information. Like a password, anyone who gets it will be able to control the thing. Use a secure method, like using the Bluetooth, when you pass it to the thing.

Onboarding from both the thing and the mobile app

In this method, you first execute the onboarding request from a thing. Then, you execute the onboarding request from a mobile app.

You can actually start onboarding from either one of them. Both onboarding requests need to be processed, however, to start sending commands and getting thing state information.

As explained in Onboarding in the Function Guide, both the thing and mobile app will access Thing Interaction Framework while performing the onboarding in this method. The direct connection between the mobile app and thing, however, is not needed in this approach.

Step 1: Onboarding from the thing

Start onboarding from the thing. Once the onboarding is done, the thing will be able to report its state and receive commands.

See here for more details.

Step 2: Onboarding from the mobile app

Next, perform the onboarding from the mobile app. Once the onboarding is done, the mobile app will be able to send commands and get the thing state.

Here is the sample code:

// Set the thing credentials.
let vendorThingID = "nbvadgjhcbn"
let thingPassword = "123456"

// Set the data grouping interval option.
let interval = DataGroupingInterval.INTERVAL_15_MINUTES
let options = OnboardWithVendorThingIDOptions(interval: interval)

// Onboard the thing.
api.onboardWithVendorThingID(vendorThingID, thingPassword: thingPassword, options: options, completionHandler: { (target: Target?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

We are setting the following values in the sample code:

• vendorThingID: The ID of the thing that the thing vendor assigned. See here for more information. Specify the vendorThingID you have set in Step 1.
• thingPassword: The password of the thing. Basically, a unique password is assigned to each thing to secure the resources allocated for the thing in Thing Interaction Framework. Specify the password you have set in Step 1.
• interval: The grouping interval for storing state history. The history will not be stored if no grouping interval is specified. The available intervals are INTERVAL_1_MINUTE, INTERVAL_15_MINUTES, INTERVAL_30_MINUTES, INTERVAL_1_HOUR, and INTERVAL_12_HOURS. See this page for the details.

Alternatively, the above API can use the thingID transferred from the thing (e.g., via Bluetooth) instead of using the vendorThingID.

Note that the state history is not available until onboarding from the mobile app completes. The thing can upload state information but it is not stored as history data until the first mobile app gets associated with the thing.