Kii Cloud SDK for Thing Overview

This page explains the basic concept for handling things with the Kii Cloud SDK.

Thing and owner

To handle a thing in the Kii Cloud, you need to define the thing on the server and associate its owner.

The procedures and purposes of assigning a thing owner are the same as those of the onboarding in the Thing Interaction Framework.

The following three steps are required for initializting a thing. The corresponding APIs are different depending on the SDK you are using.

  • Using the features of both the Thing-IF SDK and Kii Cloud SDK for Thing

    First, register a user or group who will become a thing owner using the User management or Group management features of the Kii Cloud SDK (:num1:).

    Next, execute the onboarding API of the Thing-IF SDK to onboard the thing. Inside the API, the thing will be registered (:num2:) and the specified user or group will be assigned as the thing owner (:num3:).

    If you want to use the features provided by the Kii Cloud SDK for Thing after onboarding the thing, use the Thing-IF SDK's API to acquire the thing's ID and access token. Then, use them when executing the API of the Kii Cloud SDK for Thing.

  • Using only the features of the Kii Cloud SDK for Thing

    First, register a user or group who will become a thing owner using the User management feature or Group management feature of the Kii Cloud SDK (:num1:).

    Next, register the thing with the API of the Kii Cloud SDK for Thing (:num2:). You will get the thingID of the thing. Read Thing Management in this section for the details.

    Finally, execute the API of Kii Cloud SDK for Thing to register an owner (:num3:). In this example, we are specifying a user and thing to link them. Read Ownership Management in this section for the details.

    Note the onboarding process of the Thing-IF SDK also initializes some buckets for the internal processing. If you initialize a thing with this method, therefore, you will not be able to execute the API of the Thing-IF SDK.

Thing identifier

When handling things in Kii Cloud, we identify each thing by two kinds of IDs: vendorThingID and thingID. These are the same concepts that are explained in the Thing-IF SDK Thing Identifier.

When using two SDKs together, register a thing with the Thing-IF SDK and refer the thing with the thing's ID in the Kii Cloud SDK for Thing.

Note that the format of thingID is different in the Thing-IF SDK and Kii Cloud SDK for Thing. As illustrated in the following figure, you will specify a string without the type information in the Kii Cloud SDK for Thing.

Unlike the other Kii Cloud entities, such as users, groups, and KiiObjects, there is no URI for a thing. For more information, see "Object ID and URI" (Android, iOS, JavaScript).

Thing scope

Kii Cloud creates a dedicated thing scope for a registered thing. You can create buckets, KiiObjects, and topics in this scope. The Thing scope behaves similarly to other scopes. See Scopes and Access Privileges and Push to User Notification for the details on other scopes.

The following figure illustrates the relationship between thing scope and other scopes.

As shown in the figure, one application can have multiple things. Each thing will have its independent scope.

At the time when a thing is created but its owner is not yet registered, the thing scope is closed to the thing. This means that only the thing (and the administrators) can access buckets and KiiObjects in the scope. This allows Kii Cloud to store data generated by the thing while protecting the data from being accessed by other users and things.

Things and ownership

In some cases, however, you may want to share data generated by a thing with other users or groups. You can achieve this by inviting them to become owners. This grants them the ability to control a thing and access the buckets and KiiObjects in its scope.

You can add a user or a group as a new thing owner. When you add a group, all group members become owners. One thing can have multiple owners. In the previous figure, for example, the centermost thing has granted ownership to the centermost group while the rightmost thing has granted ownership to both the rightmost group and user.

Inviting a new owner can be performed using a simple, or more complex and secure flow. Which you should use depends on your thing capability and service requirements. See Ownership Management for more information.

Once a user becomes a thing owner they will have privileges to perform the following actions on the thing.

  • Fully accessing the thing scope

    The thing owner can create and delete buckets in the things scope. They can also create, update, delete, and query KiiObjects in these buckets. See Data Management for more information

    In addition, the thing owner can subscribe to the thing scope topic and send messages to the topic. See Push Notification for the details.

  • Managing the thing

    The thing owner can manage the thing. For example, they can update thing information and enable/disable it. See Thing Management for more information.

Access model

All data generated by a thing are stored in its (thing) scope. By default, the thing cannot access data in its owner's scope.

In some applications, you may want to allow things to access user scopes. For example, suppose we are implementing an application with a weight scale. If the weight scale is shared among family members, they may not want other family members to access their data. In such a situation, it is handy if the weight scale can directly write the data in the user scope bucket for each member. You can achieve this by modifying the ACL so as to grant the write permission to the weight scale.