Action and Command Execution

You can control the things by sending commands. The things return the result of the command execution to Thing Interaction Framework. The result can be browsed by other devices (e.g., mobile applications and web applications).

See Action and Command Execution for the overview.

The following operations are available:

On the Mobile App

On the Thing

Sending Command

The following is an example of sending a command.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands" \
  -d '{
    "actions": [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ],
    "issuer": "user:{USER_ID}",
    "schema": "SmartLight",
    "schemaVersion": 1,
    "title": "AirConditioner-Demo",
    "description": "Set the air conditioner to my favorite settings",
    "metadata": {"created_at":"20150901"}
  }'

Please set the access token of the thing owner. Also please replace the placeholder {THING_ID} with the ID of the target thing.

The command is to be defined as follows:

Fields Mandatory? Description
actions Yes An array of actions to be sent in the command. In the above example, three actions (turnPower, setPresetTemperature, and setFanSpeed) are set and send in the command. As you can see, you can set the parameter for each action.
issuer Yes The issuer of the command. The issuer must be the owner of the target thing. This can be either a user ID or group ID. Please use the prefix "user:" when setting a user ID and "group:" when setting a group ID.
schema and schemaVersion Yes The schema name and version. They are useful for detecting the schema version mismatch (See here for more information).
title No The title of the command (max 50 characters).
description No The description of the command (max 200 characters).
metadata No The metadata of the command in a JSONObject format.

If the command is successfully registered in Thing Interaction Framework, the Framework will assign a command ID. This command ID is returned in a 201 response as follows:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "commandID":"{COMMAND_ID}"
}

The command ID is later used when sending and getting the command result.

Sending Command Result

After the thing executes the command, it sends the command result to Thing Interaction Framework. In the command result, the results of the action executions are summarized.

The following is an example of sending a command result.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands/{COMMAND_ID}/action-results" \
  -d '{
    "actionResults": [
      {"turnPower": {"succeeded": true}},
      {"setPresetTemperature": {"succeeded": true}},
      {"setFanSpeed": {"succeeded": false, "errorMessage": "Interuppted by user."}}
    ]
  }'

Please set the access token of the thing. Also please replace the placeholder {THING_ID} and {COMMAND_ID} with the ID of the target thing and command, respectively.

The command result is to be reported as an array in the actionResults field. As you can see in the sample, the result of each action execution is set in the field. If the action execution was a success, set true in the succeeded field. If not, set false in the succeeded field. In this case, you can put an additional message in the errorMessage field.

If the command result is successfully uploaded, Thing Interaction Framework will send a 204 response.

Getting Command and its Result

As illustrated in the overview, the command result (a set of action results) is managed with the command in Thing Interaction Framework.

To get the command result, you will retrieve the command from Thing Interaction Framework by specifying the command ID. The sample code below is an example of getting the command.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands/{COMMAND_ID}"

Please set the access token of the thing owner or thing. Also please replace the placeholder {THING_ID} and {COMMAND_ID} with the ID of the target thing and command, respectively.

You will get the command in a 200 response as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "commandID": "{COMMAND_ID}",
  "commandState": "IMCOMPLETE",
  "schema": "SmartLight",
  "schemaVersion": 1,
  "target": "thing:{THING_ID}",
  "issuer": "user:{USER_ID}",
  "actionResults": [
    {"turnPower": {"succeeded": true}},
    {"setPresetTemperature": {"succeeded": true}},
    {"setFanSpeed": {"succeeded": false, "errorMessage": "Interuppted by user."}}
  ],
  "actions": [
    {"turnPower": {"power": true}},
    {"setPresetTemperature": {"presetTemperature": 25}},
    {"setFanSpeed": {"fanSpeed": 25}}
  ],
  "title": "AirConditioner-Demo",
  "description": "Set the air conditioner to my favorite settings",
  "metadata": {
    "created_at": "20150901"
  },
  "createdAt": 1450147577076,
  "modifiedAt": 1450149727923
}

In the actionResults field, you can find an array of action results.

You can also find the overall command execution result in the commandState field:

  • SENDING: the command is registered in Thing Interaction Framework and sent to the target thing.
  • SEND_FAILED: the command is registered in Thing Interaction Framework but sending it to the target thing failed.
  • DONE: all actions in the command were successfully executed on the thing.
  • INCOMPLETE: at least one of the actions in the command failed to execute on the thing.

Getting All Registered Commands

You can also get a list of all commands registered in Thing Interaction Framework. 

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands"

You will get the list of commands as a 200 response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "commands": [
    {
      "commandID": "{COMMAND_ID}",
      "schema": "SmartLight",
      "schemaVersion": 1,
      "target": "thing:{THING_ID}",
      "commandState": "INCOMPLETE",
      "issuer": "user:{USER_ID}",
      "actionResults": [
        {"turnPower": {"succeeded": true}},
        {"setPresetTemperature": {"succeeded": true}},
        {"setFanSpeed": {"errorMessage": "Interuppted by user.", "succeeded": false}}
      ],
      "actions": [
        {"turnPower": {"power": true}},
        {"setPresetTemperature": {"presetTemperature": 25}},
        {"setFanSpeed": {"fanSpeed": 25}}
      ],
      "title": "AirConditioner-Demo",
      "description": "Set the air conditioner to my favorite settings",
      "metadata": {
        "created_at": "20150901"
      },
      "createdAt": 1450147577076,
      "modifiedAt": 1450149727923
    },
    {
      "commandID": "{COMMAND_ID}",

      ... the command detail follows ...
    }
  ]
}

You can find an array of commands in the commands field.

Pagination

If there exist many commands registered, Thing Interaction Framework may not be able to return all commands at once. In such a situation, the Framework will return a portion of the commands with a nextPaginationKey as follows:

First, you will execute the GET command without any "paginationKey".

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands"

If there are many commands and Thing Interaction Framework cannot return all of them at once, it will return a "nextPaginationKey" together with a portion of the commands in the response as follows:

    ... an array of commands ...

    }
  ],
  "nextPaginationKey":"XXXYYY"
}

By specifying this pagination key in the query parameter paginationKey, you can get the next set of commands.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands?paginationKey=XXXYYY?bestEffortLimit=100"

Please set the value of the "nextPaginationKey" as is; the value does not have any special meaning (i.e., you cannot directly specify any page number with the key).

As shown in the above example, you can also specify the bestEffortLimit to limit the number of commands to be returned.

If you get another nextPaginationKey in the response, you can use it to get the next set of commands. If no nextPaginationKey is set in the response, it means that you've received all commands.

Receiving Command

The thing can receive commands from the mobile app through push notification via MQTT. Check the MQTT topic and the payload in the PUBLISH command sent from the server side.

MQTT Topic

The MQTT topic in the received command is the one that you obtained as part of the connection information for the MQTT broker and specified with the SUBSCRIBE command. In other words, it is the MQTT topic which was obtained as "mqttTopic" in the connection information at the connection initiation (See topics for HTTPS and MQTT).

Ensure to check the MQTT topic name on receiving the PUBLISH command from the server because the PUBLISH command is used for various purposes. Also, ignore PUBLISH commands with unknown MQTT topic names for future enhancement.

Payload

The payload of the received PUBLISH command contains a JSON string as below. This is a command used in the example with an air conditioner in the development guides (See topics for Android and iOS).

{
  "actions": [
    {
      "turnPower": {
        "power": true
      }
    },
    {
      "setPresetTemperature": {
        "presetTemperature": 25
      }
    },
    {
      "setFanSpeed": {
        "fanSpeed": 5
      }
    }
  ],
  "commandID": "000b6010-28a1-11e6-8367-22000a84d49d",
  "issuer": "user:0f2968a00022-49eb-6e11-ba32-00f4d2cc",
  "schema": "AirConditioner-Demo",
  "schemaVersion": 1
}

See the table below for the description of each field.

Field Description
actions The detail of actions contained in the command. The content varies depending on the sent command.
commandID The command ID.
issuer The account which issued the command. In this example, it is the user ID of the thing owner who sent the command.
schema The command schema. It is the schema name which was specified when the command was sent from the mobile app.
schemaVersion The version of the command schema. It is the schema version which was specified when the command was sent from the mobile app.

Sending Command Result

After the thing executes the command, it sends the command result to Thing Interaction Framework. In the command result, the results of the action executions are summarized.

The following is an example of sending a command result.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands/{COMMAND_ID}/action-results" \
  -d '{
    "actionResults": [
      {"turnPower": {"succeeded": true}},
      {"setPresetTemperature": {"succeeded": true}},
      {"setFanSpeed": {"succeeded": false, "errorMessage": "Interuppted by user."}}
    ]
  }'

Please set the access token of the thing. Also please replace the placeholder {THING_ID} and {COMMAND_ID} with the ID of the target thing and command, respectively.

The command result is to be reported as an array in the actionResults field. As you can see in the sample, the result of each action execution is set in the field. If the action execution was a success, set true in the succeeded field. If not, set false in the succeeded field. In this case, you can put an additional message in the errorMessage field.

If the command result is successfully uploaded, Thing Interaction Framework will send a 204 response.