Trait Registration
Each thing has its own capability. A mobile app developer needs to understand the thing's capability correctly in order to develop the mobile app that interacts with the thing. For example, the developer needs to know the data the mobile app should send for controlling the thing remotely. The developer also needs to know how the thing will upload the data that represents the current status of the thing.
In Thing Interaction Framework, the thing capability is managed using the feature called "trait."
This page covers the overview of the trait feature. See Registering Thing Capability for the information on how to use the feature when implementing your apps.
Actions and states
In Thing Interaction Framework, the capability of the thing is defined with its "actions" and "states."
- Actions: Operations that the thing can perform.
- States: Data that the thing can handle, such as the current status of the thing.
For example, a typical air conditioner supports the following actions and states.
- Actions such as "Turning power on/off" and "Changing the room temperature setting."
- States such as "The current room temperature" and "The current room humidity."
Trait
A trait is a definition of the state and actions supported by a thing.
It defines the following information:
- A list of actions the thing supports and the expected parameters for each action.
- A list of states the thing supports and the expected value for each state.
- The time interval in which the history of the states is to be kept.
For example, let us assume that we are going to manage a water level sensor that supports two actions ("Reset the sensor" and "Turn the power on/off") and one state ("the current water level").
In this case, we will register the following trait to Thing Interaction Framework.
The trait specifies that the water level sensor supports two actions (resetSensor and turnPower) and one state (level). It also specifies that both actions expect bool values as their parameters and the state expects a number greater than or equal to 0. For the state, the trait says that its history will be kept in an interval of 15 minutes.
When the thing uploads its state, the state value is validated with the expected value specified in the trait. If the state is valid, its history will be stored in the interval specified in the trait. See State Registration and Retrieval for more details.
When a command is sent to the thing, the action parameter in the command is validated with the expected value specified in the trait. See Action and Command Execution for more details.
Trait status
A trait has three statuses: not finalized, finalized, and public.
| Trait status | Can the application administrator update the trait? | Is the trait open to the public? |
|---|---|---|
| Not finalized | Yes | No |
| Finalized | No | No |
| Public | No | Yes |
Status: Not finalized
When the application administrator registers a new trait, the trait is in "not finalized" status.
The application administrator can update the trait in this status. Since the trait is not open to the public, only the application administrator can refer to the trait.
Status: Finalized
Once the application administrator is done with editing the trait, he can set its status to "finalized".
Once finalized, the application administrator can no longer update the trait. Instead, he can register a new version of the same trait (check Trait version for more details).
The finalized trait is still not open to the public. Only the application administrator can refer to the trait.
Status: Public
When the trait is ready to be open to the public, the application administrator can set the trait to "public" status. Only the finalized trait can be set to the public status. The non-finalized trait cannot be set to the public status.
Note that once the trait is public, anyone can refer it with its URI. A device manufacturer, for example, can define the traits for their devices, register them in one Kii app, publish them, and disclose their URIs to the third party developers. The third party developers can use these trait URIs to start developing mobile apps that interact with the devices.
Trait version
As mentioned in Trait status, the trait is no longer updatable once it is finalized. Instead, the application administrator can register a new version of the same trait. This feature is useful, for example, when a newer version of the thing is released and you want to support both the old and new versions at the same time.
Trait version and inheritance
The trait version has some inheritance constraints.
- A new version must contain all actions defined in the previous version. If you want to disable some actions in the new version, you can do so by setting a flag on the actions.
- A new version cannot have different data grouping interval from the previous version. The data grouping interval is fixed once it is set, and you cannot change it later.