Quick Start Guide

This Quick Start Guide will help you create a Voice meta file for a SmartThings device, for a single Voice intent. Specifically, you will use the example "Send a command to a SmartThings device", for which you will create an action flow for the Voice command "Switch on the Light".

Launch the Editor

Launch Bixby Home Studio in your browser by visiting https://bhs.bixbydevelopers.com.

Launch Bixby Home Studio

If you're not logged in, you will be prompted to sign into your Samsung Account.

Configure BHS Settings

Bixby Home Studio displays the Settings window.

If this page does not open by default, click on the Settings icon in the sidebar:

Settings Icon in BHS

Here is how you configure BHS for your device:

  1. Select the preferred language for testing purposes under Hints/Dialogue Language.
  2. Select the maximum number of backups for metadata.
  3. Click on Save.

If you are an internal user, you can also select the server that your devices are connected to.

BHP settings

Create a New Project

Since you haven't created a Bixby Home Studio Project yet, you will be prompted to do one of the following:

  • Create a new project
  • Download existing Bixby Home Project metadata for a project
  • Import a JSON metadata file from your local computer

Click the New Project button. In the future, you can use the first three toolbar buttons to create, download, or import new projects.

Create a New Project Button

The next screen will prompt you to fill in the project's device and metadata information.

New Project Info Screen

You'll need to fill in the following information:

  • SmartThings Location: the location of the device you want to control, as configured in SmartThings.
  • SmartThings Device: The device you want to control, as configured in SmartThings.
Note

You can edit the metadata after the project is created by clicking on the BHS Metadata icon in the sidebar to the left of the screen.

You can also choose how to create the initial metadata:

  • Create metadata using SmartThings capabilities of the device. You can choose this option if you know that your device already supports existing SmartThings capabilities.
  • Create metadata from scratch. You can choose this option if you want to create all your own metadata.
  • Update from existing metadata. If you are working with other people, you can choose this option to download an exisitng metadata file.

For the lightbulb example, select the first choice, then click NEXT.

Select a Voice Intent

Now you will be prompted to select voice commands from the selected device's existing capabilities. These voice commands are used to control the project's device.

Select the Voice Command

Note

If you had chosen "Create metadata from scratch", you would have to choose a Bixby Voice Category first. This would pull up all the related SmartThings device commands that are supported. Choosing the "Create metadata using SmartThings capabilities of the device" option helps narrow down the available commands for you to work with.

Select the voice commands you want to add to the project, then click NEXT. You are now shown the project summary screen. You can add the project name here.

Project summary

Bixby Home Studio will now display its main editor screen, with the Voice Intent you added displayed in the Voice Intent section of the sidebar. Expand the voice intent to see the Property and Graph links.

Added voice intents

Note

For more information about the editor screen and how to add more voice intents, read How to Use the Bixby Home Studio Editor.

Create an Action Flow

By associating a voice intent with an action flow, you are specifying what action the device should perform for that voice intent.

Here is how to create an action flow:

  1. If you haven't, click on the Graph link under the chosen voice intent. For example, click on Graph under the powerswitch-turnon voice intent.
  2. Drag and drop the Start node from the Node menu to the flow editor area. The Start node is triggered when the user utters a command. This command is the trigger for any action flow.
  3. Drag and drop the Command node to the flow editor area to send a command to the device.
  4. In order to make the Start node trigger the Command node, connect the output trigger of Start node to the trigger port of the Command node.

Trigger command node

Set the Execution Command

  1. Click on the Command node to select it.

  2. Click on APPEND NEW ITEM to add a command.

    Command node configuration

  3. Select main as the component, if not yet selected.

  4. Select the command capability from the dropdown of the Node Configuration menu. The example uses switch.

    Select switch capability

  5. Select a command for the selected capability and click the SAVE button to save this selection.

    Select Switch on command

You have now created an action flow that sends a Switch on command to the light bulb.

Generate a Response

  1. Drag and drop both the Response: Success and Response: Execution Failed nodes to the flow editor area. This feature lets users know about their device connection statuses. You do this by connecting the output ports from the Commandnode to the respective Response: nodes.
  2. Connect the success output port of the Command to the Response: Success node.
  3. Connect the failure output port to the Response: Execution Failed node.

Action flow with responses

Test in the Editor

You can use the Try it feature of the editor to test if the action flow works as intended on a real device. To test, click on the Try it button in the menu bar.

Try It button

Turn off your device and click on Try It. You will see that your device is switched ON. You can see the green flowing line over the execution path as shown below. Any obtained values, responses etc. are shown below the corresponding nodes.

Execution flow

You have now successfully created and tested an action flow for a voice intent! Similarly, you can add action flows for more voice intents that you want to include in the voice meta information. The action flow created in this tutorial is simple, but you can always add multiple nodes to create a more complex action flow.

Bixby Home Studio has more capabilities than what is covered in this Quick Start Guide. For more details, see the How to Use the Bixby Home Studio Editor guide and all the other Developers' Guides for Bixby Home Studio.