Onboarding

To use the Thing-IF SDK, you need to bind a thing with a mobile app (more specifically, with a user of the mobile app). This binding process is called Onboarding. You need to perform the onboarding as a part of the initialization process.

By performing the onboarding, all the necessary initialization on the Thing Interaction Framework will be executed. The onboarding will also clarify the user (owner) who can manipulate the thing to ensure the security.

In this page, we will explain how the onboarding works and show the related Thing Interaction Framework features.

Access token

The Thing-IF SDK handles a numerous number of things and mobile app users, so we need the mechanism to identify them.

Prior to the onboarding, you need to register a user who is going to manipulate the thing (i.e., an owner) as KiiUser and get their access token. The KiiUser is an object that is provided by the User Management feature of the Kii Cloud SDK.

Once the access token is obtained, the SDK will automatically attach it to all requests sent to Thing Interaction Framework. Thing Interaction Framework secures the data by identifying the resources the user can access with the access token. This prevents, for example, a user to access data generated by other users or things that other users own.

You typically create a user with their username and password. In the development guides, we will use an example of creating a new user as a pseudo user (Android, iOS, JavaScript, REST) to simplify the explanation.

Likewise, a thing needs to register itself to Thing Interaction Framework and gets its access token. The SDK will attach the access token to all requests sent to Thing Interaction Framework. Thing Interaction Framework, just like in the case of users, determines the resources that the thing can access using the access token.

See the related topics in the development guides for Android, iOS, and JavaScript to learn how to handle the access token in the implementation.

Thing owner

Thing Interaction Framework binds a user or a group who will manipulate the thing as an owner.

The group (KiiGroup) is an object that is provided by the Group Management feature of the Kii Cloud SDK. By setting a group as a thing owner, you can define multiple users as a group and allow the group members to share the thing.

Once a user or group becomes an owner, they can send commands to the thing and get the thing states.

The relationship between an owner and thing is managed on the cloud side to provide tight security. Users cannot manipulate things that they do not own, even if they try to inject request via REST APIs.

Thing identifier

There are two types of identifiers Thing Interaction Framework uses to identify each thing registered on the Cloud.

  • vendorThingID

    The vendorThingID is an identifier that developers can freely assign. You can use any ID as long as it is unique in Thing Interaction Framework application. You can, for example, use an ID assigned before shipping or a UUID that is generated upon the initial launch.

    If the vendorThingID is a predictable string like a serial number, the risk of attack from a third party is increased. Kii recommends using random strings which are as much unpredictable as possible.

    When registering a thing to Thing Interaction Framework, you will need to present the thing password (shown as "thingPassword" in the figure) with the vendorThingID. You can let the user define this password at the initial launch of the thing while you can assign it like the vendorThingID (i.e., it can be hard-coded before the shipment).

  • thingID

    The thingID is an identifier that Thing Interaction Framework assigns to the thing upon the registration. Developers cannot assign the thingID. It will be unique in the Thing Interaction Framework application.

Sharing IDs

When binding a thing with a mobile app, these IDs need to be shared between the thing and mobile app in some way.

For example, the IDs can be shared in the following ways:

  • Using a Bluetooth or Wi-Fi connection to pass the VendorThingID and thingID. The Thing-IF SDK does not provide these means, so you need to implement it by yourself.
  • Using some manual means, like printing the vendorThingID on paper and let a user enter it on the mobile app or printing the QR code and let a user read it on the mobile app. This method is usable if the vendorThingID is assigned before the shipping and is embedded in the thing's non-volatile memory (you cannot use this method for passing the thingID because it is dynamically assigned by Thing Interaction Framework).

If you are using the gateway, the IDs of the gateway and end nodes will be shared automatically by the SDK. The mobile app needs to be able to identify the target gateway (e.g., by knowing the IP address).

Interoperability with Kii Cloud SDK

You can use the vendorThingID you've specified in Thing Interaction Framework can on Kii Cloud SDK for Thing.

The thingID assigned by Thing Interaction Framework is compatible with Kii Cloud SDK. The thingID is a string with the form like th.0123456789ab-cdef-0123-4567-89abcdef. When using it on Kii Cloud SDK, you can use the thingID as is. When using it on Thing-IF SDK, you will attach the type information saying that the ID is for the thing and specifies the ID as TypedID (this is the same when using user and group ID; you will attach the type information to the Kii Cloud's ID and specify them as TypedID). The SDK provides the class method and property for getting the thingID from the TypedID class.

When you check things on the developer portal, the vendorThingID and thingID will be shown directly without the type information.

Onboarding

The onboarding will initialize Thing Interaction Framework. To bind the thing owner (user or group) with the thing, Thing Interaction Framework will make various preparation, like registering the thing, assigning the owner, allocating the space for storing commands, and configuring the push notification.

There are two ways to perform the onboarding. 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 both cases, you can execute the onboarding multiple times from the SDK. The second and subsequent onboarding will skip the registration and configuration processes that are already done in the first onboarding.

Onboarding from the mobile app

In this method, the mobile app will handle the all onboard processes and get the thing's thingID and access token. The mobile app then transfers this information to the thing via a secure mean (i.e., Bluetooth). The thing uses the information to initialize the SDK.

The onboarding is executed in the following steps. The step number corresponds to the number in the above figure.

  1. As a preparation, the mobile app registers a KiiUser and get their access token.
  2. Prepare the thing's vendorThingID and thingPassword on the mobile app. The thingPassword is used for registering the thing, and it will ensure the security. You can provide the vendorThingID in various ways. For example, assign the vendorThingID to the thing at the factory shipment and have the thing owner enter it from a paper medium or via Bluetooth, or have the mobile app generate it dynamically based on the UUID.
  3. Execute the onboarding from the mobile app. The vendorThingID and thingPassword are required for this request.
  4. The onboarding is processed on Thing Interaction Framework. The thing will be created and bound to a KiiUser or KiiGroup (i.e., owner registration) at the same time. If the thing already exist in Thing Interaction Framework (e.g., when you are binding second and subsequent mobile apps to the thing), the thing creation is omitted.
  5. The SDK receives the thing's thingID and access token as a result of the onboarding.
  6. The mobile app gets the thingID and access token from the SDK. Then, it transfers the information to the thing. This data transfer needs to implement by yourself since the Thing-IF SDK does not provide the feature.
  7. The thing initializes the SDK using the thingID and access token sent from the mobile app.

The thingPassword and access token are confidential information. Anyone who gets them will be able to misuse the thing.

See the related topics in the development guides for Android, iOS, JavaScript, REST API, and Thing to learn how to impelemnt.

Here are the pros and cons of this approach:

Pros

  • The thing can initialize the SDK by presenting the generated thingID. This allows you to make the overall implementation simpler:
    • The mobile app can auto-generate the vendorThingID (e.g., by using the UUID). Generating the UUID is easier on the mobile devices than doing it on the thing. If you generate the vendorThingID on the mobile app, you do not need to assign it to the thing device at the factory shipment.
    • When you replace the thing hardware, you can just resend the thingID to the new thing. The new thing can take over all information stored by the old thing.
  • The onboarding procedure is aggregated on the mobile app side. This will make the thing programming simple.

If you are to use the UUID as the vendorThingID, you need to consider the case when the UUID collides although the probability of collision is very low. If you try to perform the onboarding with the vendorThingID that is already registered, Thing Interaction Framework will assume that this is a re-request from the existing thing. Typically, this onboarding will fail because the password provided does not match with the registered one. The mobile app will be able to detect the UUID collision and can re-generate a new UUID. If the password accidentally matches, then the onboarding request will be accepted and will bind the mobile app to the existing thing.

Cons

  • You need to establish a secure communication channel between the mobile app and thing.

Onboarding from both the thing and the mobile app

In this method, you execute the onboarding from both a thing and mobile app. If you take this approach, you can omit the connection establishment between the thing and mobile app in some cases.

The onboarding is executed in the following steps. The step number corresponds to the number in the above figure. You can actually start onboarding from either thing or mobile app.

Mobile app side

  1. As a preparation, the mobile app registers a KiiUser and get their access token.
  2. Prepare the thing's vendorThingID and thingPassword on the mobile app. The thingPassword is used for registering the thing, and it will ensure the security. As already described in Thing identifier, this step can be omitted in some cases (e.g., when using some paper media to manually provide the vendorThingID to the mobile app). You can, of course, use Bluetooth and such to transfer the information from the thing to the mobile app.
  3. Execute the onboarding from the mobile app. The vendorThingID and thingPassword are required for this request.
  4. The onboarding is processed on Thing Interaction Framework. The thing will be created and bound to a KiiUser or KiiGroup at the same time. If the thing already exist in Thing Interaction Framework (e.g., when you are binding second and subsequent mobile apps to the thing), the thing creation is omitted.
  5. The SDK receives the thing's thingID and access token as a result of the onboarding. You can ignore these values in this method.

See the related topics in the development guides for Android, iOS, JavaScript, and REST API to learn more about the implementation.

Thing side

  1. Start onboarding from the thing. The vendorThingID and thingPassword are required for this request.
  2. The onboarding is processed on Thing Interaction Framework. The thing will be created and bound to a KiiUser or KiiGroup (i.e., owner registration) at the same time. If the thing already exist in Thing Interaction Framework (e.g., when you are binding second and subsequent mobile apps to the thing), the thing creation is omitted.
  3. The SDK receives the thing's thingID and access token as a result of the onboarding. The SDK stores these values.

The thingPassword and access token are confidential information. Anyone who gets them will be able to misuse the thing.

See Onboarding from the mobile app to learn how to implement the process.

Pros

  • If you can provide a mean to share the vendorThingID and thingPassword between the thing and mobile app, you do not need to establish any secure communication channel between them.

Cons

  • The overall onboarding processes become complex because you need to perform the onboarding processes on the thing side too.