State Registration and Retrieval

You can register values that represent a thing's status (State) to Thing Interaction Framework.

The latest state can be referred from a mobile app. This allows the mobile app to get various sensor and configuration data from the thing and use them in various ways.

The states registered in the past are stored as the state history. The state history can be viewed and retrieved via the REST API and on the developer portal.

This page covers the overview of the state. See Updating and Browsing State for the information on how to use the feature when implementing your apps.

Overall Flow

The next figure illustrates the overall flow of state registration and retrieval.

Step 1: Registering state

The thing can upload its state to Thing Interaction Framework. As described in State data format, the state is uploaded in the JSON format.

The thing SDK will upload the state at the following timing:

• Automatically at regular intervals.
• When the thing finishes processing the command sent from the mobile app.

When you are registering the state from an end node of the gateway, the converter can upload the state at any time.

Step 2: Validating state

Thing Interaction Framework validates a state uploaded by the thing. The Framework validates the state on the basis of the corresponding trait definition. See State validation for more details.

The state will not be registered if it is invalid; an error will be returned.

Step 3: Saving state

Thing Interaction Framework saves the state registered by the thing as the latest state. The past states will be managed as a history.

If there exist triggers with the state conditions, these trigger conditions are evaluated at this time to check if Thing Interaction Framework needs to fire the triggers. See Auto Execution with Triggers for more details on the trigger.

Step 4: Getting state

You can get the latest state and history of the past states. You can view the state on the developer portal. You can also retrieve the state on mobile apps.

As shown in State Data Format, a state is handled as a JSON. By using our SDK for mobile apps, you can get the state in a manner suitable for your platform (e.g., embedding with the reflection, referring a Dictionary, and so on). You can then let the mobile apps visualize and leverage the states.

When retrieving the state history, you can, of course, retrieve the past states themselves but also can get their aggregated result. See Managing State History to learn more.

State data format

The state is uploaded in the JSON format.

For example, the following data will be uploaded to Thing Interaction Framework if a sensor-equipped fuel tank is registering the current water level as its state:

{
  "LiquidLevelMeterAlias": {
    "level": 40
  }
}

You can freely define the data format of the state. Make sure to register a trait that defines the data format in advance. Also, make sure that the thing that uploads the state is associated with the trait.

As shown in the example above, the trait alias is to be sent along with the state. The trait alias will be used to identify the corresponding trait definition when Thing Interaction Framework is to validate the state.

State validation

Thing Interaction Framework will validate an uploaded state on the basis of the trait. The validation will be executed on the basis of the content described in the trait's payloadSchema.

The state example above is taken from the sample shown in Trait Alias Registration. Thing Interaction Framework will refer the trait alias LiquidLevelMeterAlias and acknowledge that the version 1 of the trait LiquidLevelMeter is to be applied when validating the state level. The trait specifies a number greater than or equal to 0 as the expected parameter for this state, so Thing Interaction Framework will return an error if the parameter does not match with this condition (i.e., a negative number).

Nested JSON

You can also set a nested JSON data as a state. In this case, the following restrictions apply:

• You can only use the top-level fields of the state when you are setting the filed conditions for aggregating the state history.

• You can only use the top-level fields of the state when you are setting the state conditions of the trigger execution conditions.

Managing state history

All states registered on Thing Interaction Framework will be managed as the state history. The state history is managed in the following manners.

Immutable

Once stored, the state history cannot be modified or deleted.

Timestamp

All states are stored with the timestamp. The timestamp is later used for querying and retrieving the state history.

The timestamp is basically set automatically by Thing Interaction Framework. Things can, therefore, register their states without worrying about timestamping.

You can also set the timestamp on the thing side. This feature is useful in some cases, such as when you are to accumulate multiple states on the thing for a while and later register them at once. When using this method, the difference between the timestamp set on a state and the actual time the state is registered must be within the specific time frame; the time frame is determined by the state history grouping interval (to be explained in the next section). For example, the maximum time difference allowed will be 6 hours if the grouping interval is set to 15 min.

Grouping and sampling

When storing the state history, the states are grouped in the interval that is designated in the trait. Slots will be allocated based on the selected interval, and the states will be sampled based on the slots.

The following table summarizes the grouping interval you can select. For each interval, the table also shows the state sampling density and the maximum time difference allowed between the timestamp set on a state and the actual state registration time.

The following diagram illustrates how the grouping interval and sampling density work when you set the interval to "15 minutes".

• Yellow frames denote groups set in a 15-minute interval. The first group starts at the UNIX Epoch (January 1st, 1970 at UTC), and subsequent groups are created in 15-minute intervals.

• The sampling density is "1 state in every 30 seconds", so each group is divided into 30 slots with 30-second intervals.

• Each slot can hold one state.

If multiple states are registered for a slot, the newest state will be preserved. The next diagram illustrates an example of having more than two state registrations in one slot duration (30 seconds) when the grouping interval is 15 minutes. In this case, only the newest state is preserved while older states are discarded.

Please note that all states are managed together, regardless of their types.

• If a thing registers multiple types of states, they are sampled without any distinction. If there are multiple state registrations for one slot, the newest state will be preserved regardless of their types.

• The Thing-IF SDK for thing registers the state on two occasions: when a command execution is completed and when the time for the auto-execution comes. The states registered in these two occasions are sampled without any distinction. If your use case requires monitoring the thing state history in a regular interval, please consider disabling the state handler that will be executed upon the command execution completion. This treatment will prevent any accidental loss of the state history.

  For more details, see Updating State.

Aggregation per group

You can get the aggregated result of the state history per group. If an air conditioner is registering the room temperature and humidity as a state, for example, you can get the average/maximum/minimum of them per group. Please note that you can only get one type of the aggregation value at this moment (we are planning to support getting multiple aggregation values simultaneously soon).

Thing Interaction Framework will perform the group aggregation, so you do not need to perform any data manipulation on the application.

Let us show some examples. Let us assume that we have the following state history being registered. We will show how you can retrieve and aggregate the state history based on these states.

• Example 1: Retrieve with Time Range Only (with grouping)

  You can get all past states in the specified time range. You can get the state history as a grouped result.

  

• Example 2: Retrieve with Time Range Only (without grouping)

  The same as the previous example, but you can also get the state history without any grouping.

  

• Example 3: Retrieve with Time Range + Field Condition (without aggregation)

  You can get the past states in the specified time range that match with the designated condition (e.g., "states that have the currentTemperature field greater than or equal to 32").

  

• Example 4: Retrieve with Time Range + Field Condition (with COUNT aggregation)

  You can get the number of the past states in the specified time range that match with the designated condition (e.g., "states that have the currentTemperature field greater than or equal to 32"). The number of states is returned per group.

  

• Example 5: Retrieve with Time Range Only (with MIN aggregation)

  You can get the state that has the minimum value in the specified field (e.g., the currentHumidity field) in the specified time range per group.