Create a Bixby Response using Device Status

This guide assumes familiarity with:

In this guide, you'll learn how to use the following:

  • Attribute Node
  • Response Node
  • Vocab Conversion node for localization
  • Attribute Node with Trigger

Let's design an action flow for the voice command:

"What is the power status of the bulb?"

You must get the status of the device (whether turned on or off) and give the user this information. The PowerSwitch Status voice intent enables you to do that.

Added Attribute Node

Attribute Node

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 from the device the value of this attribute, use the Attribute node. The Attribute node is used to get the value of any attribute you might need in an action flow.

To add this to your action flow:

  1. Drag the Attribute node from the node menu to the flow editor area.
  2. Select the dragged node if not selected, which will show the Node Configuration menu at the right side of the flow editor area. Adding the Attribute Node
  3. For the goal, select the switch attribute and value property within the configuration menu. Select Switch Attribute

Response

Now you have the value of the power on or off status of the device as a string from the output data port of the Attribute node. (Note that the type is string from the details of the attribute above.) So you need to inform the user about the status of the device with Bixby.

To give a response to the user via Bixby, use the Response node. This response is a dialog spoken by Bixby. In the Response node, select the dialog that Bixby uses to respond:

Add Response Node

Each possible dialog response consists of a template and the values to fill in. The Response node has to be configured for dialog in both hands-free and hands-on scenarios. These scenarios are chosen based on the device Bixby is speaking from.

Configuring Dialogue ResponsesAdded Response Node

Once the node is configured, the node's ports are automatically reflected with parameters according to the dialogue chosen.

In this case, the Capability parameter is automatically filled by the editor as shown in the Node Configuration menu, so there is no corresponding port to the node.

The Information parameter is to be sent as a value to the input port through a data-path.

Configuring Dialogue Responses

Vocab Conversion Node for Localization

Now that you have a node which can make Bixby reply with a dialogue, all that is left is to pass the on/off value to the dialogue.

An initial guess might be to directly feed an "on/off" string to the input port of the Dialog node. But the Response node directly replaces the parameters with the values passed to the node, so you need to ensure that the values are consistent with the user's language. To support multiple languages, Bixby Home Platform uses Vocab (vocabulary).

Note

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

The Vocab Conversion node is used to convert a string to a Vocab. Let's add a Vocab Conversion node.

The Vocab Conversion node essentially maps a key to a particular "Vocab" (predefined vocabulary, to be precise). When a key is passed to this node as input, it returns the corresponding vocabulary as output through it's node value output data-port.

In this case, the possible keys as input are either 'on' or 'off'.

  1. Add a new Vocab Conversion Node. Add Vocab Conversion Node
  2. Add new Vocab - Key mapping for "on". Create new Vocab - key mapping
  3. Click on the symbolId empty column above to open "Select Vocab" window. Select "on" Vocab. Add Vocab
  4. Repeat the above steps for "Off" key. Add Vocab - key pair for "Off" key
  5. Once the node is configured, all that is left is to connect the nodes through execution paths and data paths as shown below.

The Finished Action Flow

If the bulb's power status is 'on', this value goes into the Vocab Converter node as a key and gives the corresponding vocab, which is then passed on to the Response node as a parameter to be replaced in the dialogue at it's placeholder.

This ensures that 'on' is translated appropriately into the user's language and the dialog is coherent.

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 will work for the desired behavior, but this graph behaves differently with respect to when to fetch the value of the attribute:

  • 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 above action flow is valid, it's not as efficient as the first action flow. It's suggested that you use triggers on Attribute nodes only when absolutely needed.