Defining Schema

You need to define the schema to let the mobile application manipulate the thing.

This page assumes that you are familiar with the basic concepts of the schema, actions, action results, and thing state. To learn about these concepts, see Schema.

Schema

When you define a schema on the Android, you will define the following classes and aggregate them as a schema:

  • An array of the Action and ActionResult classes that compose a command.
  • A TargetState class for getting the thing state.

Here, we will define a sample schema for a simple air conditioner. Let us assume that the air conditioner can take the following three actions at the same time:

  • "TurnPower" Action with a boolean value to specify if we are going to turn the power on or off (true to turn the power on).
  • "SetPresetTemperature" Action with an integer (from 15 to 30) that represents the preset temperature setting.
  • "SetFanSpeed" Action with an integer (from 0 to 10) that represents the fan speed setting.

Also, let us assume that the air conditioner allows us to check the "current room temperature" and "humidity" as its state in addition to the above three action settings.

We will present implementation examples of command and state based on the above scenario.

Defining Command

The command is defined as a pair of actions and action results. The actions and action results are defined as Java classes.

  • Action

    Each action is to be defined as a subclass of the Action class. The action parameter to be sent to the thing is to be defined as the public field of the class.

    The SDK internally reads the action class using Java Reflection and compose the parameters to be sent to the thing in JSON format.

  • Action Result

    A class for receiving each action result is to be defined as a subclass of ActionResult class.

    This subclass is always defined as an empty class. The mobile application will get the action result by referring the dedicated method that is implemented in the superclass ActionResult.

For both classes, you need to override the method to return the action name. The action names returned by the methods implemented by the Action and ActionResult classes must match, or you will get an error when you try to register them. The action name is registered on the Thing Interaction Framework and is used by the mobile application and thing to identify the action.

In our air conditioner example, we will define the following six classes.

TurnPower

public class TurnPower extends Action {
  public boolean power;

  @Override
  public String getActionName() {
    return "turnPower";
  }
}

public class TurnPowerResult extends ActionResult {

  @Override
  public String getActionName() {
    return "turnPower";
  }
}

SetPresetTemperature

public class SetPresetTemperature extends Action {
  public int presetTemperature;

  @Override
  public String getActionName() {
    return "setPresetTemperature";
  }
}

public class SetPresetTemperatureResult extends ActionResult {
  @Override
  public String getActionName() {
    return "setPresetTemperature";
  }
}

SetFanSpeed

public class SetFanSpeed extends Action {
  public int fanSpeed;

  @Override
  public String getActionName() {
    return "setFanSpeed";
  }
}

public class SetFanSpeedResult extends ActionResult {
  @Override
  public String getActionName() {
    return "setFanSpeed";
  }
}

Our sample scenario was simple, so all classes only have one field. You can, of course, define multiple fields. A field can take anything that can be represented as a JSON string (e.g., string, array, and nested objects).

Defining State

The state is defined as fields of a subclass of the TargetState class.

In our sample air conditioner scenario, the class will be defined like this:

public class AirConditionerState extends TargetState {
  public boolean power;
  public int presetTemperature;
  public int fanSpeed;
  public int currentTemperature;
  public int currentHumidity;
}

The thing will report its state in JSON format like the following example. As explained in Browsing State, the SDK will map the JSON string reported by the thing into the class you've defined for the state.

{
  "power" : true,
  "presetTemperature" : 25,
  "fanspeed" : 5,
  "currentTemperature" : 28,
  "currentHumidity" : 65
}

Defining Schema

Finally, we combine the command and state as a schema and pass the generated schema to the ThingIFAPIBuilder.addSchema as shown in Initializing and Onboarding.

// Create a schema builder with parameters.
SchemaBuilder sb = SchemaBuilder.newSchemaBuilder("airConditioner",
      "AirConditioner-Demo",
      1, AirConditionerState.class);

// Add action classes to the schema builder.
sb.addActionClass(TurnPower.class, TurnPowerResult.class).
      addActionClass(SetPresetTemperature.class, SetPresetTemperatureResult.class).
      addActionClass(SetFanSpeed.class, SetFanSpeedResult.class);

// Create a schema.
Schema schema = sb.build();

  1. Define the schema using the SchemaBuilder.newSchemaBuilder method and get a SchemaBuilder instance.

    In the above example, we are passing the following arguments:

    • Thing type: You can use up to 100 alphanumeric characters, hyphen, underscore, and period (this parameter is for the future expansion. We are planning to allow you to define the available features per thing type).
    • Schema name: the name for identifying the schema.
    • Schema version: the version of the schema for detecting any updates.
    • The class information of the state class.

    The schema name and version, together with the action names, will be used in the thing's action handler to identify the actions received from Thing Interaction Framework.

  2. Register pairs of the action and action result classes in the SchemaBuilder instance

    In this example, we are registering three pairs of actions.

  3. Execute the build method to get the Schema.