Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Quick Start Guide

Ready to create your own capsule? Follow this quick start guide to get started.

This guide shows you the basics of the Bixby platform. You'll learn how to:

  • Add the building blocks for your capsule through concepts and actions. Concepts create the building blocks of your capsule, while actions define what actually gets done.
  • Implement JavaScript for your action, which performs the computation for your capsule.
  • Add dialog and views. Dialog determines how Bixby interacts with the user, while views are design elements that determine how information is presented.
  • Finally, teach Bixby about user statements and questions through training.

Let's get started and build something! We'll create a capsule that lets the user roll dice. With this, you can choose how many dice to roll and how many sides are on each dice. So, for example, if you were to ask "roll 2 6-sided dice", Bixby would respond with a sum of the dice rolls as well as the number on each dice.

Download and Install Bixby Developer Studio

  1. Download and install Bixby Developer Studio. (For more information about Bixby Developer Studio, read Using Bixby Developer Studio.)

  2. Start Bixby Developer Studio.

  3. Enter the server URL in the lower-left corner of the login page and select the Log In button. Bixby Developer Studio then shows the Samsung authentication page.

  4. Log in using your Samsung account credentials. If successful, the authentication page then shows Login successful.

  5. Select the launch button in the authentication page. Bixby Developer Studio launches, connects, and sets up your workspace. When Bixby Developer Studio shows Ready in the lower-left corner, you're ready to start.

Create Your Capsule

Once you've installed Bixby Developer Studio, you are ready to create your capsule. Bixby uses concepts and actions to help determine user intent and decide on a goal. It then creates a plan to reach that goal, essentially writing a new program in the process. Bixby runs this program to decide what to do next: show results, interact with the user, or build and run another plan.

The first step is to create a new capsule!

  1. Open File > New Capsule.

  2. Use Choose Folder to choose a location on your computer.

  3. Provide a Capsule ID. In this case, let's just use example.dice.

  4. Click Create. Bixby automatically creates a code and resources folder. You'll need those later in this guide. It also creates a capsule.bxb file, which handles the metadata required by Bixby to ensure capsules are configured properly.

Add Concepts and Actions

You've created the basic structure of a capsule, but now we have to add some important pieces to it. You normally would create these yourself, but since we're just getting started, we've gone ahead and created these files for you.

Access and copy these files from our Github repo into the folder you just created.

Let's start with what we call concepts and actions. Concepts and actions are the building blocks of a capsule. Concepts explain what Bixby knows, while actions determine what Bixby can do. For the dice roller, we have the following concepts and actions, which are located in dice/models/:

  • NumDice.model.bxb: A primitive concept representing the number of dice in a roll. Primitives represent simple types like integers, booleans, decimals, and text.
  • NumSides.model.bxb: A primitive concept representing the number of sides on each dice.
  • Roll.model.bxb: A primitive concept representing the result of each roll.
  • Sum.model.bxb: A primitive concept representing the sum of a multiple dice rolls.
  • RollResult.model.bxb: A structure concept, which is used to track key-value objects, representing the results of a roll or rolls. It contains properties for the sum and roll. The roll property can take more than one value if there are multiple rolls.
  • RollDice.model.bxb: An action that takes the two inputs (NumDice and Numsides) and produces an output of type RollResult. Actions allow you to define an operation that Bixby can do on behalf of the user.

Of these concepts, NumDice and NumSides are the two key pieces required for the dice roller to work.

Let's take a closer look at the NumDice.model.bxb concept:

integer (NumDice) {
description (The number of dice to throw.)
}

You see that numDice is set as an integer with an optional description. If you open many of the other files in the concepts folder, you'll see code that is very similar.

The exception is RollResult.model.bxb, which is a structure concept used to track the sum and roll. The first property is for the total sum of all the dice rolled. The second property holds the list of each dice roll. Because we want each property to be available after a RollDice call, they are both required (min(Required)). There will only be a single sum value (max(One)), but the roll property can hold many values, one for each roll of a dice, so we'll use max(Many).

structure (RollResult) {
description (The result object produced by the RollDice action)
property (sum) {
type (Sum)
min (Required)
max (One)
}
property (roll) {
description (The list of results for each dice roll.)
type (Roll)
min (Required)
max (Many)
}
}

Test the Capsule

Now that you've added the capsule files, test it out.

  1. Open the Simulator (View > Open Simulator).

  2. Click Confirm to run the NL model compilation, which allows you to test utterances in the Simulator. You'll learn more about this when you add training.

  3. Enter the following intent, which is a structured representation of the user's request, into the Input panel.

       // Give two values (number of dice and number of sides) with the
    // goal of rolling dice
    intent {
    goal: example.dice.RollResult
    value: example.dice.NumSides (6)
    value: example.dice.NumDice (2)
    }
  4. Select the Run Intent button.

You'll see a result like the following:

results of intent execution

Congratulations! You just tested your first capsule on Bixby! In the example above, you see that each roll was 5 and 2 respectively.

Now let's step back and see what you did. The intent you executed is Bixby's way of understanding what the user wants. At a minimum, it must have a goal. Normally, it also has values, which are constraints or clues provided by the user.

Open the Debug Console by pressing the Debug Console button (Debug Console button) in the Simulator. Notice that after you execute the intent, Bixby creates an execution graph in the Debug Console that shows the inputs (NumDice and NumSides) that lead to the action RollDice, and finally the goal RollResult.

results of intent execution

In this case, Bixby only needs to perform one action, but in other cases, like buying airline tickets, there will be multiple inputs and actions.

Let's take a look at the other parts of the capsule that you need.

JavaScript (*.js)

While concepts and actions form the skeleton of your capsule, JavaScript functions are the muscle. In your dice roller, we've already included a JavaScript file, RollDice.js, that does some basic computation. It takes the two inputs, generates a random number, then computes both the sum and the result of each dice roll.

To be able to access that JavaScript, we've also included an endpoints declaration (endpoints.bxb), which allows you to access local and remote JavaScript functions as an endpoint.

Views (*.view.bxb)

After you roll the dice, Bixby uses views to know how to present the results. By default, Bixby produces a generic table that is useful for debugging, but you wouldn't want users to see. In the view file (RollResult.view.bxb), you will customize how the users will see the dice roller results.

Dialog (*.dialog.bxb)

As users talk to Bixby, dialog files allow you to customize how Bixby talks back. They tell the user about what is happening. As with views, Bixby produces generic dialog, so you need to customize it through dialog files (NumDice.dialog.bxb, NumSides.dialog.bxb, and RollResult.dialog.bxb) that allow the dice roller to be more expressive.

Training

At the beginning of this guide, you use an intent to execute the query. In real life, however, users communicate using natural language like "roll 2 4-sided dice" or even "roll some dice". Therefore, you'll need to add some training examples to ensure Bixby can handle natural utterances in the dice roller.

Add a View

First, let's add a view so that you can customize and format your results in a more pleasing way.

  1. Open RollResult.view.bxb from the file navigator in the resources/en folder.

  2. Add the following code:

     result-view {
    match {
    RollResult (rollResult)
    }

    render {
    layout {
    section {
    content {
    single-line {
    text {
    style (Detail_M)
    value ("Sum: #{value(rollResult.sum)}")
    }
    }
    single-line {
    text {
    style (Detail_M)
    value ("Rolls: #{value(rollResult.roll)}")
    }
    }
    }
    }
    }
    }
    }

    There are different ways in which you can set the user interface. In this example, we're using result-view, since we're displaying results.

    The way in which this view is selected among others when presenting RollResult is through a match pattern. You can learn more about match patterns in the Developer Guide.

  3. After adding a view, execute the intent once more in the Simulator:

     // Give two values (number of dice and number of sides) with the
    // goal of rolling dice
    intent {
    goal: example.dice.RollResult
    value: example.dice.NumSides (6)
    value: example.dice.NumDice (2)
    }
Note

If you've been away from the Simulator for too long, your session might have timed out. Click on the main Simulator window to start a new conversation.

You should now see the updated view appear in the results:

results of new layout

Add Dialog

Next, add some dialog to improve the way Bixby refers to various concepts within the dice roller. While layouts help you customize how Bixby presents information, dialog helps you customize the text itself.

  1. Open NumSides.dialog.bxb from the file navigator.

  2. Add the following code:

     dialog (Concept) {
    match {
    // Look for this type
    NumSides
    }
    // Use the following template text with this type
    template("number of sides")
    }

    As with the view file, this dialog uses a match pattern to look for a NumSides type and replaces the default dialog for that concept with the template text. Now add another set of dialog to change how Bixby returns results.

  3. Open NumDice.dialog.bxb from the file navigator.

  4. Add the following code:

     dialog (Concept) {
    match {
    // Look for this type
    NumDice
    }
    // Use this template text with this type
    template("number of dice")
    }
  5. Open RollResult.dialog.bxb from the file navigator.

  6. Add the following code, which adds random dialog:

     dialog (Result) {
    // bind the variable "rollResult" to the result and "rollOutput" to
    // the action of which it was output
    match {
    RollResult (rollResult) {
    from-output: RollDice (rollOutput)
    }
    }
    // define a condition that changes the dialog depending on whether there
    // is one or more dice
    if (rollOutput.numDice == 1) {
    template ("You've got a ${value(rollResult.roll)}!!!")
    }
    if (rollOutput.numDice > 1) {
    choose (Random) {
    template ("The sum is ${value(rollResult.sum)}")
    template ("You rolled ${list(rollResult.roll, 'value')}")
    }
    }
    }

    Notice that we're using conditional if rules here to ensure that the dialog is accurate based on whether the user indicates one or more dice.

  7. After adding dialog, execute the intent once more in the Simulator.

     // Give two values (number of dice and number of sides) with the goal of
    // rolling dice
    intent {
    goal: example.dice.RollResult
    value: example.dice.NumSides (6)
    value: example.dice.NumDice (2)
    }

You should now see the updated dialog appear in the results:

results of intent execution

Add Default Values

The dice roller currently works only if you specify two inputs: the number of dice and the number of sides to a dice. But what if a user doesn't provide those numbers?

Try running this intent, which does not provide values, in the Bixby Simulator:

intent {
goal: example.dice.RollResult
}

Notice that Bixby now prompts the user because it expects a minimum amount of input to fulfill the goal. To address this, add default values using default-init in your capsule so that Bixby can automatically provide values when the user provides none.

  1. Open RollDice.model.bxb from the file navigator.

  2. Replace the current code with the following:

     action (RollDice) {
    // specify this action as a calculation
    type (Calculation)
    // add a required input for the number of dice that defaults to 1.
    collect {
    input (numDice) {
    type (NumDice)
    min (Required)
    max (One)
    // add a default value of two dice
    default-init {
    intent {
    goal {NumDice}
    value {
    NumDice (2)
    }
    }
    }
    }
    // add a required input for the number of sides that defaults to 6.
    input (numSides) {
    type (NumSides)
    min (Required)
    max (One)
    // add a default value of six sides per dice
    default-init {
    intent {
    goal {NumSides}
    value {
    NumSides (6)
    }
    }
    }
    }
    }
    // set the output of this action to "RollResult"
    output (RollResult)
    }
  3. Now execute the same intent again:

     intent {
    goal: example.dice.RollResult
    }

Bixby no longer prompts because you added default values that were filled in when none were provided by the user:

results of intent execution

Add Input Validation

Finally, let's ensure that values the user provides to the dice roller are valid. For example, you wouldn't want users to say they want zero dice with only one side.

  1. Open RollDice.model.bxb, if it is not already open.

  2. Replace the current code with the following:

     action (RollDice) {
    type (Calculation)
    collect {
    input (numDice) {
    type (NumDice)
    min (Required)
    max (One)
    default-init {
    intent {
    goal { NumDice }
    value {
    NumDice (2)
    }
    }
    }
    // add a validation dialog prompt when the user indicates less
    // than 1 dice.
    validate {
    if (numDice < 1) {
    prompt {
    dialog {
    template ("You must have at least one dice.")
    }
    }
    }
    }
    }
    input (numSides) {
    type (NumSides)
    min (Required)
    max (One)

    default-init {
    intent{
    goal { NumSides }
    value {
    NumSides (6)
    }
    }
    }
    // add a validation dialog prompt when the user indicates less
    // than 2 sides.
    validate {
    if (numSides < 2) {
    prompt {
    dialog {
    template ("A dice must have at least 2 sides.")
    }
    }
    }
    }
    }
    }
    output (RollResult)
    }

    Notice that this code includes validate, which includes an if statement to check for specific numbers.

  3. To test out your latest additions, use the following intent with an invalid number for sides and dice:

     intent {
    goal: example.dice.RollResult
    value: example.dice.NumSides (1)
    value: example.dice.NumDice (0)
    }

The result now produces a more informative prompt:

invalid intent execution

Add Training Examples

Finally, add some natural language training examples so that Bixby is ready for different kinds of user input.

  1. Open the resources folder within your capsule, then the en subfolder, and select training.

  2. At the top of the training tool where it says Adding New Training, add the following utterance and click Add:

     roll 2 6-sided dice
    

    add training

  3. Add the following text as the Goal:

     RollResult
    
  4. Click 2, enter NumDice in the Node field, and click Done.

  5. Click 6, enter NumSides in the Node field, and click Done.

    add training

  6. Click Save.

Test Training

Now that you have added training, you need to compile the natural language (NL) model so Bixby will learn the utterance for which you added training. Click the Compile NL Model button and wait for the model to compile.

Go back to Simulator, add the following utterance, and click Run NL:

roll 2 6-sided dice

The utterance will now run in the Simulator. Try typing other variations in the simulator's input box, such as "roll 4 8-sided dice".

Your training doesn't take advantage of the default values for the number of dice and number of sides, because the only utterance you've added training for so far includes both of them. Try adding new training examples on your own to handle these cases.

Related Topics

You've now created your first capsule complete with concepts, actions, JavaScript, dialog, layout, default values, validation, and training. This guide covers just the basics of each of these components.

If you enjoying playing with code, you can look through our Sample Capsules to understand the Bixby platform further.

If you enjoy reading more, you can learn a lot more in the different sections of the Developer Guide. Here are some specific topics that delve deeper into the Bixby platform: