Create a Bixby Response Using Device Status

This guide assumes familiarity with:

In this guide, you'll learn how to fetch a device's power status, give a response to the user via Bixby, and localize Bixby dialog. You'll also learn how to use the following:

  • Attribute node
  • Response node
  • Vocab Conversion node for localization
  • Constant node

Let's use the example "What is the power status of the bulb?" to design an action flow for this voice command.

You must get the status of the device (whether it's turned on or off) and give the user this information. The powerSwitch - getStatus voice intent enables you to do that.

Attribute Node

For this voice intent, you need to fetch the device's power status in order to determine whether the device is on or off. Whether or not the device is powered on is an attribute of the switch capability. To request the value of this attribute from the device, use the Attribute node. The Attribute node is used to get the value of any attribute you may need in an action flow.

Added Attribute Node

To add and configure this node:

Drag the Attribute node from the Action Flow Nodes sidebar to the editor area. Select the node. This opens the Node Configuration menu on the right of the editor area.

Adding the Attribute Node

Select the switch capability. In most cases, you can leave the component selection as the default option, main. For more information on components, see the note at the bottom of this section.

Select Switch Capability

In the pop-up, select the value property for the switch attribute. Click SAVE.

Select Switch Attribute

The Node Cofiguration window will look like this:

Select Value Property

Note

Most devices have only one operating section or compartment. In this case, the only option for component is main. If a device has many sections or compartments that you can operate independently, there will be multiple component options, such as top, bottom, and middle.

Response Node

Now you have the value of the device power status (on or off) from the output data port of the Attribute node. The value type is string, as seen in the Node Configuration menu earlier. You need to have Bixby tell the user the power status.

To have Bixby give the user a response with the device power status, use the Response node. The response consists of dialog spoken by Bixby. Drag the Response node from the Action Flow Nodes sidebar to the editor area. Then, select the Response node. This opens the Node Configuration menu on the right of the editor area.

Open Response Node Configuration Menu

The Response node has to be configured for dialogs in both hands-free and hands-on scenarios. These scenarios are chosen based on the device Bixby is speaking from. You can create different dialogs for each scenario by clicking use multiple dialogues mode under Node Configuration at the top.

In this case, use a single dialog for both scenarios by clicking SELECT DIALOGUE.

Single Dialog Mode

A pop-up with possible dialogs appears. Each dialog response consists of a template and the values to fill in. If you don't find your desired dialog template on the first page, check the bottom right to see if there are additional pages.

Select Dialogs

Select the dialog that Bixby uses to respond to the user. For this example, select the The #{Capability} is #{Information}. dialog template and click SAVE.

Configuring Dialog Responses

Once the node is configured, the node's ports reflect the necessary parameters according to the chosen dialog.

Added Response Node

The Information and Capability parameters are to be sent as values to their respective input ports on the Response node via data paths.

Configuring Dialog Responses

Vocab Conversion Node for Localization

You've enabled Bixby to respond to users with dialog. Now, you need to to pass the "on" or "off" value to the dialog.

You may initially want to directly feed an "on" or "off" string value from the Attribute node to the input port of the Response node. However, the Response node replaces the parameters with the exact values passed to the node. So, it's important to ensure that the values are presented in the user's language. To support multiple languages, Bixby Home Platform (BHP) uses vocab, predefined vocabulary.

Note

The dialog's language is automatically chosen at runtime according to the user's settings. The parameters of a dialog are replaced directly in the dialog's template in that language, to create a coherent response to the user.

The Vocab Conversion node converts a string to a vocab. This node essentially maps a key to a particular vocab. When a key is passed to the node as input, it returns the corresponding vocabulary as output through it's node value output port. A key type can be number, boolean, or string. In this case, the possible input keys are "on" and "off."

Let's add and configure a Vocab Conversion node:

Drag the Vocab Conversion node from the Action Flow Nodes sidebar to the editor area. Select the node. This opens the Node Configuration menu on the right of the editor area. Click APPEND NEW KEY - VOCAB PAIR.

Configure Vocab Conversion Node

Add a new Key - Vocab Pair for the "on" key by entering "on" under vocabMapping.

Create new Key - Vocab mapping

Click on the empty symbolId field. The Select Vocab pop up appears. Select the "on" vocab and click SAVE.

Add Vocab

Repeat the steps above for the "off" key.

Add Vocab - key pair for "Off" key

If the bulb's power status is "on," this value gets input to the Vocab Converter node as a key, and the node outputs the corresponding vocab. The vocab then gets passed to the Response node's Information input port as a placeholder for the dialog. This ensures that "on" is translated appropriately into the user's language and that the dialog is coherent for them.

Constant Node

Now that the Vocab Conversion node is configured, it's time to add a Constant node. This node stores a specified value. For this example, we'll be storing the Capability parameter of "backlight" in this node, which will become an ouput value that we connect to the Capability input port of the Response node.

Drag a Constant node from the Action Flow Nodes sidebar to the editor area. Select the node. This opens the Node Configuration menu on the right of the editor area.

Open Constant Node Configuration Menu

Select Vocab from the value drop-down menu at the top.

Select Vocab as Constant Node Value Type

Click on the empty symbolId field. The Select Vocab pop up appears. For this example, select the "CP_BACKLIGHT" vocab and click SAVE.

Select CP_BACKLIGHT Vocab

The "backlight" value gets passed to the Capability parameter input port on the Response node.

Adding Execution and Data Paths

You have finished configuring the Constant node. Now, just connect the action flow nodes through execution and data paths as shown below.

The Finished Action Flow

Attribute Node With Trigger

Why not connect the Start node to the Attribute node's trigger port and have execution paths in a linear fashion as shown below?

Action Flow with Attribute node in the execution path

This gives us the same outcome as that of the earlier graph. However, this graph behaves differently in terms of fetching the attribute value:

  • Attribute node in the execution path: Bixby fetches the value only when the node is triggered by other nodes.
  • Attribute node not in the execution path: Bixby fetches the value before the execution path is started. If the action flow needs several attribute values, Attribute nodes not in the path will get the values in parallel. In this case, the latency to get the values does not increase with the number of Attribute nodes.

When the Attribute Node is used with a trigger in the execution path as shown above, the value of the configured attribute is fetched at runtime. Using SmartThings Attributes with triggers potentially adds to the overall execution time of the action flow, increasing the overall latency of the command execution.

When the Attribute Node is used without an execution path at its input trigger port, Bixby's backend prefetches the value of the attribute before the action flow is run.

So, while the action flow above is valid, it's not as efficient as the first one. It's suggested that you use triggers on Attribute nodes only when absolutely needed.

Testing Your Action Flow

To test the action flow, click the Try It button at the top right of the editor window. The flow editor should look like this:

Action Flow Showing Execution Path

In this test run, Bixby responds to the user with "The backlight is off." Any obtained values or responses are shown below the corresponding nodes in yellow.

In the next guide, you'll learn how to incorporate Arithmetic Operations Using the Sum Node.