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 basics on the state registration and retrieval. See the related topics in the development guides for Android, iOS, JavaScript, Thing, REST API, and the developer portal for more details on the spec and implementation.

Overall Flow

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

1. Register State

The thing can upload its state to Thing Interaction Framework.

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 via the gateway, the converter can upload the state at any time.

2. Save 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.

3. Get 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 Manaing 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 the air conditioner is registering the current room temperature and humidity as its state:

{
  "currentTemperature": 28,
  "currentHumidity": 70
}

You can freely define the data format of the state, but the data format needs to be defined as the thing schema. See Schema for more information.

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 upon the thing onboarding. 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.

Grouping Interval Sampling Density Maximum time difference
1 minute 1 state in every 1 second 3 hours
15 minutes 1 state in every 30 seconds 6 hours
30 minutes 1 state in every 1 minute 12 hours
1 hour 1 state in every 1 minute 1 day
12 hours 1 state in every 30 minutes 2 days

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 distinguishment. 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 in 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 distinguishment. 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 the 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.