This guide assumes familiarity with:
In this guide, you'll learn how to use the following:
Vocab Conversionnode for localization
AttributeNode 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.
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:
Attributenode from the node menu to the flow editor area.
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:
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.
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.
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).
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.
Vocab Conversion node is used to convert a string to a Vocab. Let's add a
Vocab Conversion node.
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'.
symbolIdempty column above to open "Select Vocab" window. Select "on" Vocab.
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.
Why not connect the
Start node to the
Attribute node's trigger-port and have execution paths in a linear fashion as shown below?
This will work for the desired behavior, but this graph behaves differently with respect to when to fetch the value of the attribute:
Attributenode in the execution path: Bixby fetches the value only when the node is triggered by other nodes.
Attributenode not in the execution path: Bixby fetches the value before the execution path is started. If the action flow needs several attribute values,
Attributenodes 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 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.