Initializing and Onboarding with Gateway

Initialization needs to be done from the mobile app in which the SDKs are incorporated.

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

Initialize the gateway first and then initialize end nodes as they are added. The initialization process creates and associates the gateway and multiple end nodes with the user of the mobile app on Kii Cloud as shown in Things on Application.

The username and password of the gateway need to be shared among the gateway, end nodes, and mobile app in order to initialize things. You can make the credentials available on the mobile app by getting them from the sticker on the gateway and entering them to the mobile app manually or by sending them to the mobile app via a short-range wireless communication such as Bluetooth.

Initializing the gateway

Initialize the gateway by following the steps below in both gateway app and end node app.

1. Initializing the Kii Cloud SDK

2. Getting the ThingIFAPI

3. Getting the GatewayAPI and connecting to the gateway

4. Onboarding

This section describes how to get the ThingIFAPI and GatewayAPI instances for the gateway. These API instances are API classes to operate the gateway itself and described in API Classes in SDKs. Follow the steps explained later for the end node app to get the API class for the end nodes.

See the figure in Onboarding Gateway in the Function Guide while reading the sample code of initialization to understand the entire flow better.

Initializing the Kii Cloud SDK

Add the code below to the application:didFinishLaunchingWithOptions method of the AppDelegate.

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 (See Creating a Kii Application for more information).

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

Getting the ThingIFAPI

Next, get the ThingIFAPI instance to send requests to Thing Interaction Framework to operate the gateway. This code can be executed anywhere in the mobile app as far as the initialization of the Kii Cloud SDK described in the previous section is completed.

// 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 apiGateway = ThingIFAPIBuilder(app: app, owner: owner, tag:"gateway").build()

Specify these items in the source code:

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

  You can specify the server hostname api-jp.kii.com instead of the Site. See the reference for more information.

• owner represents a user who will be the owner of the gateway. See Defining Owner with Gateway to learn how to get it.

  There are many ways to specify the user (owner). The method to select the user 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. Initialize the SDK by executing the build method of the ThingIFAPIBuilder, and you will get a ThingIFAPI instance. Please preserve the ThingIFAPI instance in 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 Initialized Information with Gateway to preserve the instance and restore it.

Set a unique name as a tag in the tag parameter of the ThingIFAPIBuilder method to identify each ThingIFAPI instance. The tag is used to identify the instance when you use the saveInstance and loadFromStoredInstance methods to save and restore it. Set different tag names from "gateway" in the initialization of end nodes. The process will be explained later.

Getting the GatewayAPI and connecting to the gateway

Next, get the GatewayAPI instance. This instance is an object which includes APIs necessary to access the gateway from the mobile app via a local network such as Wi-Fi .

// Instantiate a gateway API object.
let gatewayAddress = NSURL(string: "___GATEWAY_URL___")
let gatewayLocal = GatewayAPIBuilder(app, address:gatewayAddress).build()

// Authenticate a user to the gateway.
gatewayLocal.login("___GATEWAY_USERNAME___", password:"___GATEWAY_PASSWORD___", completionHandler: { (error: ThingIFError?) -> Void in
    // Check for an error.
})

• Specify the gateway URL, username, and password in the ___GATEWAY_URL___, ___GATEWAY_USERNAME___, and ___GATEWAY_PASSWORD___. The gateway URL is an address such as http://192.168.0.10/, which is accessible from the mobile app via Wi-Fi on a local network. The gateway username and password are the credentials for the gateway agent. Share them with the mobile app in some way.

• Specify the KiiApp instance, which was used to initialize the ThingIFAPI instance, in the app parameter of the GatewayAPIBuilder. The KiiApp instance has information such as the AppID and AppKey.

• The login method accesses the gateway and gets the gateway user authenticated when it is called.

Onboarding

To control a thing such as a gateway and an end node from the mobile app, you need to bind the mobile app to the thing. This binding process is called Onboarding.

The onboarding needs to be done for the gateway as below:

// Instantiate the gateway.
gatewayLocal.onboardGateway( { (gateway: Gateway?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Get the thing ID of the gateway.
  let thingID = gateway!.thingID

  // Set the gateway password.
  let thingPassword = "___GATEWAY_PASSWORD___"

  // Onboard the gateway to Thing Interaction Framework.
  apiGateway.onboard(thingID, thingPassword: thingPassword, completionHandler: { (target: Target?, error: ThingIFError?) -> Void in
    if error != nil {
      // Handle the error.
      return
    }
  })
})

The above sample code processes these tasks:

1. The onboardGateway sends an onboarding request to the gateway via Wi-Fi. The Gateway instance is returned when the request is successfully processed. You can get the thingID of the gateway from the Gateway instance.

2. The onboard sends an onboarding request to Thing Interaction Framework. This associates the owner which was specified in onboarding the apiGateway with the gateway which was specified in the thingID.

This is the only supported method to onboard the gateway. For stand-alone things, you can select the method where you onboard things from the mobile app or the method where you onboard things from both the mobile app and things.

The gateway and the mobile app have been associated when the above process is completed. Continue to the subsequent steps with the obtained apiGateway and gatewayLocal.

This completes the necessary initialization on the gateway app. The additional steps required on the end node app are described in the next section.

Initializing end nodes

The end node app initializes end nodes as they are added after the gateway has been initialized.

Initialize end nodes by following the steps below.

1. Getting a list of pending nodes

2. Onboarding

3. Getting the ThingIFAPI

4. Installing a device

5. Notify the gateway

See the figure in Onboarding End Node in the Function Guide while reading the sample code of initialization to understand the entire flow better.

Getting a list of pending nodes

First, by accessing the gateway, get the list of pending end nodes which are yet to be initialized. The gateway maintains the list of end nodes which have been connected to the gateway but not completed onboarding to Thing Interaction Framework. You can get the list through the Gateway API.

Use the gatewayLocal instance of the GatewayAPI to access the gateway. Get the list of pending end nodes and select one of them to initialize.

// Get a list of pending end nodes.
gatewayLocal.listPendingEndNodes( { (nodes: [PendingEndNode]?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  for index in 0..<nodes!.count {
    let endnodeVendorThingID = nodes![index].vendorThingID
    let endnodeThingType = nodes![index].thingType
    let endnodeProperties = nodes![index].thingProperties
    // Select a pending end node to onboard.
  }
})

Call the listPendingEndNodes to get the list of end nodes as the [PendingEndNode]. This list contains end nodes that are yet to be registered to Thing Interaction Framework. The above sample code processes the entries of the list one by one to get detailed information of them.

The mobile app decides one PendingEndNode instance to process. To decide a target, you might let the user select one through the user interface of the mobile app or process all the pending end nodes one by one.

If you let the user select a target end node, the thing type and thing information are available to identify a target end node. You can design these values at your discretion when connecting end nodes to the gateway. For example, you can set a serial number of the product or the product name such as Kii Smart LED E26 [ABC-123] as a field of the endnodeProperties. Let the user decide a PendingEndNode instance to initialize by some way, such as displaying these values on the screen.

Move to the next step once the PendingEndNode instance to initialize is decided.

Onboarding

Next, execute onboarding which associates an end node, the mobile app (the user), and the gateway.

Enter the end node password to the mobile app before onboarding. This task aims to ensure security in handling the end node on Thing Interaction Framework. You can let the user enter it on the user interface or the mobile app generate it internally. Note that the end node password needs to be safely managed because leakage of it could lead to potential unauthorized access and loss of it makes access to the end node impossible.

Onboard the end node by the below API dedicated to end nodes.

// Set the end node password.
let endNodePassword = "___END_NODE_PASSWORD___"

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

// Onboard the end node.
apiGateway.onboardEndnodeWithGateway(pendingEndNode, endnodePassword: endNodePassword, options: options, completionHandler: { (endNode: EndNode?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

The following values are set in the above sample code.

• 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.
• pendingEndNode: The end node which was selected in Get List of Pending Nodes as an initialization target.
• endNodePassword: The password of the end node to be initialized. Enter it to the mobile app in some way.

Once onboarding is completed, you can get the EndNode instance which represents an onboarded end node. This instance will be used in the next step.

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.

Getting the ThingIFAPI

Get the ThingIFAPI instance to send requests to each end node via Thing Interaction Framework.

The obtained instance in the sample code is named as apiEndNode1 while the actual program would generate as many ThingIFAPI instances as the number of end nodes connected to the gateway. Kii recommends that you manage end nodes in the data structure which can handle multiple nodes such as a map and an array.

// Instantiate a Thing-IF API from a ThingIFAPIBuilder instance.
let apiEndNode1 = ThingIFAPIBuilder(app: app, owner: owner, target: endNode, tag: "endnode1").build()

Create a new ThingIFAPI instance by specifying these parameters in the ThingIFAPIBuilder. You can also get a new instance with the copyWithTarget method if you create an instance with the same information as that of the existing apiGateway, except for the target and tag.

• Specify the App instance, which was used to initialize the ThingIFAPI instance, in the app parameter. The App instance has information such as the AppID and AppKey.

• The owner represents the user who is the end node owner. See Defining Owner with Gateway to learn how to get it.

• Use the target parameter to associate the ThingIFAPI to be created with the onboarded EndNode.

• Tag "endnode1" is set in the tag parameter. The tag is used to identify the instance when you use the saveInstance and loadFromStoredInstance methods to save and restore it. Set a unique string which is different from ones for the gateway and other end nodes. See also the code sample in Saving and Restoring Initialized Information with Gateway.

Installing a device

You need to install the device so that the it can receive responses from end nodes when the device sends commands to them. This action associates the owner with the APNs device token on Kii Cloud.

Installing a device

Use the ThingIFAPI instance obtained in the previous step for each end node to install the device as below.

// Register the device token for the thing owner to Kii Cloud.
apiEndNode1.installPush(token, development: false, completionHandler: { (installID: String? error: ThingIFError?) -> void in
  if error != nil {
    // Handle the error.
    return
  }
})

• Set the device token obtained through the initialization of push notification.
• Set true if your environment is for development and false if your environment is for production in the development parameter. 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.

The uninstalled device will not receive push notifications any longer from all of the end nodes after the uninstallation is done against one of the end nodes. Uninstall the device in the situation like you remove the last end node.

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

This code assumes that the device has been installed. Otherwise, the installationID property will return a nil value.

The device will not receive push notifications any longer after successful uninstallation.

Notifying the gateway

Finally, notify the gateway of the completion of onboarding.

// Notify the gateway of the completion of onboarding.
gatewayLocal.notifyOnboardingCompletion(endNode, completionHandler: { (error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

Specify the EndNode instance obtained as a result of onboarding in the endNode.

Executing functions

The above steps complete the initialization of the gateway and each end node. The instances below are available when initialization is done.

• ThingIFAPI instance of the gateway

  This instance is represented as apiGateway in this topic. It is used to access the gateway via Thing Interaction Framework and to manage end nodes and the gateway itself. In the current version of Kii Cloud, this instance is necessary to initialize new end nodes.

• GatewayAPI instance of the gateway

  This instance is represented as gatewayLocal in this topic. It is used to directly access the gateway via Wi-Fi and to manage end nodes and the gateway itself. In the current version of Kii Cloud, this instance is necessary to initialize new end nodes.

• ThingIFAPI instance of end nodes

  This instance is represented as apiEndNode1 in this topic. Multiple instances will be available if multiple end nodes are connected.

  Use this instance to send commands to end nodes and check the states of end nodes. For example, when you want to send a command to the apiEndNode1, Thing Interaction Framework sends the command to the connected gateway, which will relay it to the end node.

  See Executing Commands, Browsing States, and Triggers to learn how to send commands and receive the states. Replace api in each sample code with apiEndNode1, which is the target end node to operate.