Sending a Device Command With an Argument

This guide assumes familiarity with:

In this guide, you'll learn how to send a command to the device with an argument. You'll also be introduced to the Utterance Parameter Node.

Take the example "Set the brightness of the Bulb to {value}". The goal is to define the action flow for this voice intent, which will set the brightness of a light bulb to a user-supplied value.

Utterance Parameter Node

For this voice intent, the user must give Bixby an integer value between 0 and 100:

Example: "Set the brightness of the bulb to 50."

This parameter value gets passed down to the Utterance Parameter Node. This node stores the value of the specified parameter, which is captured from a user utterance.

In Bixby Home Studio (BHS), you can configure the Utterance Parameter Node with a default value. Normally, a device would get the input value from a user's utterance. For testing purposes in this guide, you can use a default value, which allows you to test the action flow on a device without an actual user utterance.

Start building your action flow by dragging the Start and Utterance Parameter nodes from the action flow nodes sidebar to the editor area. Then, configure the Utterance Parameter Node:

  1. Click the Utterance Parameter Node. This opens the Node Configuration menu on the right of the editor area.
  2. In the data type drop-down menu, select integer (integer). This sets the node parameter type to integer.
  3. Below your data type selection, enter an integer between 0 and 100 in the defaultValue field.

Configuring the Node defaultValue

Sending a Command

Now, you need to send a command to the device to set the brightness of the bulb to the user's uttered value.

Drag a Command Node to the flow editor area. Then, click the node to open the Node Configuration menu on the right. Click APPEND NEW ITEM.

Opening the Command Node Configuration Menu

Select main in the component drop-down menu. Then, select the switchLevel command in the capability drop-down menu.

Setting the switchLevel Command


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.

A pop-up for switchLevel opens. Select the setLevel command, which will add input ports for level and rate to the Command Node. Then, click SAVE.

Setting Input Ports for setLevel() command

The Command Node should now have input ports for level and rate. Since rate is an optional argument, you can ignore it for now to keep things simple. The level input determines the brightness value for this device.

The Configured Command Node

Now you need to connect a data path from the Utterance Parameter Node's value data port to the Command Node's level data port. You also need to connect the Start Node to the Command Node's input trigger port.

Here's the finished action path:

The Finished Action Flow

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

The value of the Utterance Parameter Node has been set to 50, and this is used as the mock utterance value. That value is then used to set the brightness value for the voice command "Set the brightness of the bulb to 50."

You will also see a warning icon Warning Icon on the Command Node. When you hover over it, a message states that a response was not generated. This is because there is no Response Node in the action flow.

You can also make more complex graphs by using subgraphs.

For an additional example, see the "Set the Volume of the Device to a Value" Sample Graph.