Bixby Home Studio Basics

Bixby Home Studio (BHS), a web-based graphical interface tool, helps developers design the voice interfaces between the Bixby virtual assistant and smart devices registered with SmartThings. In BHS, you create logical action flows using connected nodes and save them in voice metadata files. You can add intelligence to the voice commands by creating voice metadata. You can also test your action flows and submit them for testing, review, and release (available to the user).

Launching and Configuring Bixby Home Studio

Launch BHS in your browser by visiting https://bhs.bixbydevelopers.com.

BHS displays the Settings window. If you're not logged in to your Samsung Account, you'll receive a prompt to sign in.

BHP settings

If BHS doesn't open the Settings window by default, click on the Settings icon towards the bottom of the left-side menu bar.

Settings Icon in BHS

To configure BHS for your device in the Settings window:

  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.

Configuring a SmartThings Device

Connecting a SmartThings device enables you to associate multiple voice capabilities with that device. At the bottom left of the screen, click the Device Details icon. A menu opens up.

Device details window

Select a location to load the list of devices present in that location. Select a device from the list. Your device is now configured. You can create metadata for it, and then the action flows for the voice intents.

You will see the following device details in the window that appears after you click the Device Details icon:

  • Device ID: This is the unique identifying number for the device.
  • Name: This is the name of the metadata file.
  • Label: This is the name that you assigned to the device.
  • Location ID: This is the unique identifying number for the location, such as your home.
  • Room ID: This is the unique identifying number for the specific location of the device, such as your living room at home.
  • Manufacturer: This is the device manufacturer.
  • VID: This is the vendor identifier number assigned to your device.

Creating a New Voice Metadata Project

To create a new project, start by clicking the ⊕ icon in the left menu bar. If you haven't created any projects yet, you can also click the New Project button in the sidebar.

Image to create new voice metadata

Choosing Initial Metadata Creation Option

Select the SmartThings location and device from the drop-down menus. Then choose one of these options:

New Project Info Screen

For more information about which option to choose, see the appropriate section below.

Create Metadata Using SmartThings Capabilities of the Device

Choose this option if your device already supports existing SmartThings capabilities and can therefore use BHS' general purpose graph metadata. Many SmartThings devices (switches, bulbs, thermostats, plugs, etc.) and SmartThings-compatible third party devices support SmartThings capabilities.

If the SmartThings Device you select supports existing SmartThings capabilities, you will be able to select Create metadata using SmartThings capabilities of the device. If the SmartThings Device you select doesn't support existing SmartThings capabilities, this option will be disabled.

To learn more about exising SmartThings capabilities, see the list of standard SmartThings capabilities.

Click NEXT. Now you're prompted to select voice intents from the selected device's existing capabilities. Voice intents are a set of user's intentions that Bixby can understand from natural voice commands. Different capabilities support various voice intents. Select voice intents.

For more information on voice intents, read the voice intents reference page.

Select the Voice Command

Click NEXT. Add the project name and click DONE.

Create new project

Create Metadata From Scratch

Choose this option if you want to create all of your own metadata. If the SmartThings Device you select doesn't support existing SmartThings capabilities and you're not planning to work on an existing metadata file, you should select this option. If your SmartThings Device doesn't support existing SmartThings capabilities, you can create metadata from scratch by using different capabilities, which utilize protocols that are different from those of SmartThings capabilities, to create your BHS graph.

Click NEXT. Now you're prompted to select voice intents supported by a specific Bixby Voice Category. Select a Bixby Voice Category. Then, select voice intents from the list.

Choose Bixby Voice Category and Voice Intents

Click NEXT. Add the project name and click DONE.

Choose Bixby Voice Category and Voice Intents

Update From Existing Metadata

Choose this option if you're working with other people, so you can download an existing metadata file from the server. You can modify the downloaded metadata and publish it to the cloud.

Click NEXT. Now you're prompted to select voice intents from released projects. Select an MNID (the manufacturer ID assigned to developers by SmartThings). Then, select a VID (vendor identifier number assigned to your device) from the list. Click NEXT.

Choose Bixby Voice Category and Voice Intents

Note

To edit the metadata after the project is created, click the BHP Metadata icon BHP Metadata icon at the top left corner of the menu bar in the main editor window.

Displaying Voice Intents

BHS now displays its main editor screen with the voice intents you added or that were included in the existing metadata you selected, displayed in the Voice Intents section of the left sidebar.

BHS main editor screen

Confirm or Edit Device Configuration Information

To view or update device configuration information, click Metadata profile in the left sidebar. A new tab opens, which contains the following information:

  • Name (of the voice metadata file)
  • Version (of the voice metadata file)
  • MNID (the manufacturer ID assigned to developers by SmartThings)
  • VID (the vendor identifier number assigned to your device)

voice metadata info

Bixby Home Studio Tour

BHS follows design patterns you'll likely be famililar with if you've used other graphical user interfaces for Internet of Things (IoT) devices: a sidebar on the left and a larger tabbed editor window to the right.

The BHS interface has five main areas:

  1. Editor: the main area of the window
  2. Activity Bar: vertical, along the leftmost edge of the Metadata Sidebar
  3. Metadata Sidebar: left sidebar, right next to Activity Bar
  4. Action Flow Nodes: in a hidden sidebar to the right of Metadata Sidebar, opens when you click the Graph icon under a voice intent in Metadata Sidebar
  5. Status Bar: horizontal, along the the bottom of the window

Editor

In the editor, you can create action flows, execution graphs that start with a user's spoken command and lead to the appropriate commands to send to the smart device. To create logical action flows to export to your device, you simply drag and drop nodes in the editor. It has a grid background to help you organize your flows. Also, you can easily move nodes around and connect them to each other. You can also select a group of nodes by dragging a highlight box around them, in order to move, delete, or copy them.

Bixby Home Studio's main screen

At the top right of the editor, you also have options to do the following:

Activity Bar

BHS’ left margin displays five icons, three at the top and two at the bottom. These Activity Bar icons switch between various tasks used in action flow development:

BHS Activity Bar

Action Flow Nodes

You can drag these nodes into the home editor window to create the action flow graph. Each node performs a specific action. An action flow contains different types of nodes connected by execution and data paths. By associating a voice intent with an action flow, you specify the behavior the device should exhibit for that voice intent.

Nodes are the functions that developers can use in BHS. A node consists of the following components:

  • Configuration: This describes how the node is set up.
  • Data input/output ports: These ports transfer information into and out of the node. For more information, see the Data Types reference page.
  • Triggering ports: These are where the node receives or sends the execution flow.

Action Flow Nodes

The action flow nodes are grouped by category:

  • Function: These include nodes that start or end an action flow.
  • SmartThings: These nodes can get information about the SmartThings device's specified capability attribute or execute a specified capability command of the device.
  • Value: These nodes allow you to operate on values like store, read, define constants, map values, etc.
  • Utterance: These nodes can perform various functions related to user utterances.
  • Comparison: These nodes compare numerical and string values for various objectives.
  • JSON: These nodes allow you to perform various actions related to JSON data.
  • Common response: These nodes send the user default dialogue for various situations.
  • Duration utility: These nodes can convert numbers and strings to amounts of time or convert time values to formatted strings.
  • Flow control: These nodes perform logical operations on boolean values, control triggers according to boolean values, and route triggers based on input values.
  • String utility: These nodes allow you to perform various actions related to strings, such as converting input values to strings and getting substrings.
  • Utility: These nodes can perform actions such as returning a UTC timestamp, generating random strings, concatenating values, and counting elements in a collection.
  • Math: These nodes enable mathematical actions, such as computing sums, calculating remainders, and rounding to the nearest integers.

To learn more about the various types of nodes, see the Nodes reference page.

Creating an Action Flow

By associating a voice intent with an action flow consisting of nodes, you specify what action the device should perform for that voice intent.

Graph for turning on a device

To learn more about action flow nodes and graphs, read the Sending a Device Command guide.

Align Graphs

To streamline your graph, click Align at the top right of the editor.

Align Graph Button

Metadata Sidebar

The Metadata Sidebar displays the list of voice intents you selected when creating your new metadata project. Buttons at the top of the sidebar allow you to create, add, export, and manage metadata.

Voice Intents

Voice intents are a set of user's intentions that Bixby can understand from natural voice commands. Voice intents determine what voice commands (utterances) can be used to control a device.

For every voice intent, there's an option to either create a new action flow or provide the payload directly in JSON format. You can also import existing metadata for a device to use instead. Different capabilities support various voice intents.

If you want to create and use an action flow for a voice intent, navigate to the relevant Voice Intent menu in the left sidebar, and click Graph.

voice intent

To learn more, visit the Voice Intents reference page.

Add a Voice Intent

To add additional voice intents from the main editor screen:

  1. In the left sidebar, under Metadata profile, click the "+" symbol to the right of "Voice Intents." This opens the "Add Voice Intent" window.

    If you can't see the left sidebar, click on the "BHP Metadata" icon in the top left corner of the menu bar to open it.

    Adding new voice intent from sidebar

  2. Select a Category from the drop-down.

    PowerSwitch capability in drop down of the Add Voice Capability

  3. Select a voice intent from the list of potential voice actions and sample utterances for the chosen category.

    Image to select voice action

  4. Click ADD. You can view the voice intent you added in the Voice Intents section.

    added voice intent

Status Bar

The bottom of the window shows your device information and your account email address. It also allows you to do the following:

  • To open and close the console window, click the left corner icon.
  • To view problems logged in the console, click the icon for warnings and errors.
  • To view test device information, click on the device name.
  • To view your BHP settings, click on your email address.

added voice intent

Warnings and Errors

To view the Problems tab in the console, click the icons for warnings and errors in the status bar along the bottom of the editing window. This opens a pane at the bottom that shows current issues with the project.

You can choose which kinds of messages to show by checking or unchecking the boxes for Warnings and Errors.

added voice intent

Submissions

To display the status of your submissions to BHS, click Submissions in the Activity Bar. You can also view the submission history and state transition details.

Metadata submission history

To learn more about submissions, read the Publishing The Bixby Device Graph (BHS Metadata Submission) guide.

Sample Graphs

You can use sample action flow graphs to build your own graphs. To drag and drop a sample graph to the editor, first click Graph under your chosen voice intent in the Metadata Sidebar. Then, in the Activity Bar, click the Sample Graphs icon. Then, drag and drop a graph to the editor.

Load metadata icon

Here are some additional resources on sample graphs:

Metadata Options

Aside from creating new metadata, you can also load, import, export, backup, or restore metadata. This allows you to collaborate with other device developers on your action flows, as well as gives you backups for flows you are working on.

Load Metadata

You can update the existing metadata of the device, to add or edit voice actions for it. To do this, click the Load Metadata icon at the top of the Metadata Sidebar. Then, you can choose metadata to load, by clicking the New or History tabs. The metadata listed under the New tab consists of existing metadata for devices that you have never loaded. The metadata listed under the History tab consists of existing metadata for devices that you have loaded before.

Load metadata icon

Load metadata

Import and Export Voice Metadata

If you want to collaborate and share your voice metadata, you can import and export the voice metadata in a .json file.

Import Metadata

You can load your voice metadata to the editor. To do this, click on the Import button in the menu bar in the menu bar on the top left of the screen.

Import Icon

Click Import to select the metadata .json file.

Importing Voice Metadata file

Click OK to load the metadata file.

Imported Metadata

Export Metadata

You can upload created voice metadata to a server or share it with another developer using the Export feature. To do this, click on the Export button in the menu bar on the top left of the screen.

Export Icon

Enter the filename to save to:

Exporting Voice Metadata file

Click on the Export button and your Voice Metadata will be downloaded as a .json file.

Backup Metadata

To backup your metadata, click the Backup Metadata icon at the top of the Metadata Sidebar. As mentioned earlier, you can set the maximum number of backups by clicking the Settings icon at the bottom right of of the Activity Bar.

Backup Metadata Icon

Restore Metadata

To restore the metadata that you last worked with, click the Restore Metadata icon at the top of the Metadata Sidebar.

Restore Metadata Icon

About

To view the BHS version, you can click the About icon at the bottom of the activity bar.

About Icon

Raw Data

To provide the payload directly in JSON format, click Raw at the top right of the editor.

Raw Graph Button

A window opens where you can add your raw JSON.

Raw Graph Window

Test Action Flows

You can use the Try it out 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.

Trying out the created action flow

You can see the green flowing dashed line over the execution path as shown below. Any obtained values or responses are shown below the corresponding nodes.

Results from testing the action flow

Testing Virtual Devices

If you don't have an actual device to test on, you can use the SmartThings simulator to create a virtual device. For more information, see the FAQ: Creating a virtual Device SmartThings community page.


Video Tutorial: Simulated Devices