Bixby Developer Center

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.

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

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.

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.

Choosing Initial Metadata Creation Option

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

• Create Metadata Using SmartThings Capabilities of the Device

• Create Metadata From Scratch

• Update From Existing Metadata

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 existing 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.

Click NEXT. Add the project name and click DONE.

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.

Click NEXT. Add the project name and click DONE.

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.

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.

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)

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.

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

• Test an Action Flow
• Align a Graph
• Provide Payload in JSON

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:

• Toggling the Metadata Sidebar
• Submissions
• Sample Graphs
• Settings
• About

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.

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.

Adding Inline Node Comments

You can also add inline comments to nodes. Sample graphs use node comments to help make execution flows easier to understand by explaining the process node by node. You can also use node comments on a single node within a graph to show useful information, such as what a node is supposed to do or what information is supposed to be returned. This graph shows inline node comments that help explain the execution flow:

To add comments, right-click a node and enter a comment in the pop-up window on the Comment line. To make comments visible, click the box next to Show Comment.

In this example, the Attribute Node fetches all the supported fan modes for the air conditioner. This makes it easier to more quickly know what information the node is getting from the device.

The inline comment becomes visible in green, in a green-outlined box above the node.

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.

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.

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.

• New Metadata
• Load Metadata
• Import Metadata from File
• Export Metadata
• Backup Metadata
• Restore Metadata
• Save
• Save as
• Recent files

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.

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.

   

2. Select a Category from the drop-down.

   

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

   

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

   

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.

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.

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.

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.

Here are some additional resources on sample graphs:

• Introduction to Sample Graphs: Describes sample graphs and how to use them.

• Basic Sample Graphs: Highlights basic sample graphs.

Metadata Options

Aside from creating new metadata, you can also load, import, export, backup, restore, or save changes to 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.

Compare Metadata Changes

If you want to compare metadata changes between a file and another version of it, you can do this in two ways.

To compare the original file and your updated one when submitting an updated metadata file for publishing:

1. After you make updates to an existing metadata file and upload your new version, click COMPARE WITH {metadata file version number} in the Metadata Submission Message pop-up.
2. The Metadata Changes tab opens. Click on a listed change under Metadata changes on the left to see comparisons of the two files.
   

To compare any two versions of a metadata file:

1. Click the Submission icon in the activity bar on the left.

2. At the top left, Enter the Vendor Identification Number assigned to your device (VID) in the search bar.

3. Open the menu for the relevant device category, such as SmartThings or Samsung Electronics.

4. A list of files with different metadata versions appears. Choose two files to compare. Drag one on top of the other to compare them.

5. The Metadata Changes tab opens. Click on a listed update under Metadata changes on the left to see comparisons of the two files.

   

When comparing two versions of metadata, you can tell the type of change based on the icon next to the file name:

• Changes with green ADDED icons indicate additions. .
• Changes with red DELETED icons indicate deletions. .
• Changes with yellow MODIFIED icons indicate modifications. .

Filtering Metadata Changes

In both situations, you can show only certain types of changes by using the filter icon to the right of the listed metadata changes. A pop-up appears where you can make your selection by clicking one or more boxes for these listed options:

• ADDED: Sections that have been added in the updated metadata file.
• REMOVED: Sections that have been removed in the updated metadata file.
• MODIFIED: Sections that have been modified in the updated metadata file.
• EQUALS: Sections that remain unchanged.

The original file appears to the left of the updated one. You can see the changes highlighted in green in the updated file.

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 on the top left of the screen.

Click Import to select the metadata .json file.

Click OK to load the metadata file.

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.

Enter the filename to save to:

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 the activity bar.

Restore Metadata

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

Save Changes to A Local File

You can import a local file, make changes in BHS, and overwrite the existing file. Alternatively, you can save the changes in a duplicate file and choose its location.

First, import a local metadata file. Once you do this, the Save and Save as icons in the menu bar on the top left of the screen become fully visible and clickable.

To overwrite the existing imported file using the Save function:

1. In BHS, make changes to the metadata.

2. Click the Save icon to overwrite the existing file. In this example, the name of the imported file is SampleGraph1.json.

3. A pop-up appears and asks if you would like to save changes to SampleGraph1.json. Click Save changes.

   After you click Save changes, a pop-up appears in the middle of the screen that says "Metadata saved to SampleGraph1.json".

To save a duplicate of the updated imported file using the Save as function:

1. In BHS, make changes to the metadata.
2. Click the Save as icon.
3. Enter a file name and choose a location in which to save it. In this example, the file is saved as example-file.json in the JSON files location. After you save the duplicated file, a pop-up appears in the middle of the screen that says "Metadata saved to example-file.json".

Load Recently-Saved File

If you use the Save or Save as function for a metadata file before signing out of BHS, then upon signing into BHS again, a pop-up asks you if you want to restore metadata from the file you most-recently saved.

To restore metadata from this file:

1. Click OK. After you click OK, a pop-up asks if you want to let BHS edit the file.

2. Click Edit file.

   BHS restores the metadata and a pop-up message confirms that your file has been loaded.

List Recent Files

To list up to five of your most-recently-saved files, click the Recent files icon at the top of the metadata sidebar.

You will see a pop-up with a list of up to five of your most recently-saved files.

About

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

Raw Data

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

A window opens where you can add your raw JSON.

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.

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.

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