Designing Commands and State Information

You need to define the data type of commands and state information in advance in order to operate the thing from the mobile app. A defined set of these data types is called a schema in Thing Interaction Framework.

The project members should share a defined schema as the design information even though it is not to be registered to Thing Interaction Framework.

Both commands and state information are represented in JSON format. A schema is a definition of such JSON field names, value types, and meanings.

Definition of Commands

A command is represented as an array of actions. Each action can have custom parameters based on the program specification. You can get the result of each action.

Hello Thing-IF has the following two actions:

  • turnPower action

    This action turns on/off the power. It has the power field and represents the power-on state with true and the power-off state with false.

  • setBrightness action

    This action specifies the brightness level of the LED bulb. It has the brightness field which can hold an integer between 0 and 100 as the brightness level. The power off command does not include this action.

A command is designed as in the below figure. Especially, pay attention to the underlined elements. Decide action names, parameter names, parameter types and the range of values as design information. This tutorial uses simple parameter values but you can use arrays and nested JSON values too as parameter values.

Each action has an action result which is a result of command execution. You can get all the results of the actions included in the executed command by getting the executed command on the mobile app. The format of the action result is defined in Thing Interaction Framework and includes flags of success/failure and error messages for the failure.

This tutorial defines these two actions to control the smart LED light. When you implement an actual solution, define your own parameters in JSON format based on your requirements for remote control and state information. You can send any command as far as it is represented in JSON format.

Definition of State Information

You can define one set of state information per schema. State information is also represented in JSON format and it can have custom information based on the application specification.

Hello Thing-IF defines the structure of state information which includes the content of the last received command and the motion sensor value. As with actions, state information can have arrays and nested JSON values.

As with actions, you can design any state information in an arbitrary format based on the desired service specification.

Definition of a Schema

Lastly, combine the commands and state information as a schema. Assign a name and version to the defined schema for identification.

When you send a command from the mobile app, you specify a schema name and version to identify the format of the command. The thing checks the schema name and version to accept only commands that the thing can support.

What's Next?

Now you have learned the functionalities and design of Hello Thing-IF. Let us build and run the sample programs by going through the subsequent topics.

Go to Building Sample Programs.

If you want to learn more...

  • See Schema for more information about the schema.