Skills

This page focuses on the core concepts of a skill, how to create skills and update them for a new SDK version.

To follow these instructions, it is assumed that you meet the following criteria:

  • have a running SDK
  • have Java 8 JDK or OpenJDK 8 installed on your system.
  • have a configured microphone.
  • have IntelliJ IDEA installed and running. Community edition is enough.

Creating a skill project

You can choose to create a skill from either the SDK Launcher or the command line. We recommend using the Launcher.

When the Virtual Furhat is running, there is a button in the Launcher labeled "Create skill". Pressing it will allow you to choose from a set of skill templates. Choose Blank skill, and then a name and location for your skill project.

Creating a skill from the command line

If you instead want to create a blank skill from the command line, you can do the following:

  • Make sure Java 8 JDK or OpenJDK 8 is installed on your system.

  • Create a new skill project by running the following command inside the SDK folder: gradlew createSkill --name=SkillName --folder=SkillFolderPath where the folder argument is optional. Example:

Note: if you installed SDK using the SDK launcher, the SDK is located in the user home directory inside .furhat/launcher/<VERSION> folder.

For example, if you want to create a skill named GettingStarted on Windows, you would do:

cd <path-to-your-SDK-directory>
gradlew createSkill --name=GettingStarted --folder=../skills

On Mac/Linux you would have to do:

cd <path-to-your-SDK-directory>
./gradlew createSkill --name=GettingStarted --folder=../skills

Importing the skill into IntelliJ IDE

Open up IntelliJ IDEA and import the newly created skill by going to File->New->Project from Existing Sources if you want to create a brand new IntelliJ project, or File->New->Module from Existing Sources if you want it as a part of an existing project.

Important: Furhat skills use Gradle as a build tool so for your IDE to know that it should fetch the skill's dependencies using gradle you need to import the skill as a Gradle project by selecting the build.gradle file in the root of your new skill in the import dialog.

The main files to care about for your skill are in the src folder (or more specifically src/main/kotlin/furhatos/app/gettingstarted). Navigate there and you will notice a few files has been created for you.

Configuring IntelliJ IDEA and build.gradle

  • Make sure the Kotlin JVM version is used (File > Settings (or Preferences on Mac) > Build, Execution, Deployment > Compiler > Kotlin Compiler and set to 1.8)
  • If multiple versions of Java are installed, they can be removed from IntelliJ. This can be done by going to (File > Project Structure > SDKs) and removing the wrong versions.

Like this

SDK dependencies for skills

Each skill that you create is set up to use a specific version of the Furhat SDK. Currently, the skill uses two components:

  • skill-configuration containing relevant gradle tasks
  • furhat-commons, a library containing most of the features of the SDK.

References to both of these components are listed in the build.gradle file, and each have versions explicitly listed, or a "+" signaling to use the latest version available.

Upgrading of SDK dependency for skill

To build your skill using a new version of the SDK, you go into your build.gradle file in the skill root and increment the furhat-commons version number to the same version as the SDK. For example, if you have the SDK version 2.4.0, then in your skill's build.gradle should list furhat-commons:2.4.0 as a dependency. The skill-configuration can stay untouched.

The contents of the skill project

For a walkthrough of the files in the skill, check the Your First Skill tutorial.

Running and packaging skills

Running a skill from directly from IntelliJ with the virtual Furhat

To test-run the skill, follow this process:

  1. Make sure you have the Furhat SDK server running.
  2. In IntelliJ IDEA, navigate to the main.kt file of the skill and press the green play button next to the main() method to start the skill.

    Important note: If your skill crashes due to "not able to read skill.properties" then ensure that the working directory of your skill is set to the root folder of the skill. Go to Run -> Edit configurations to do this. To fix this for all future skills, go to Edit configurations -> Defaults -> Kotlin and change Working Directory to $MODULE_DIR$ - See Running a skill for more info.

  3. Go to the web interface (using the default port, it will be hosted on http://localhost:8080 if your SDK server is running).

  4. Go to the Dashboard using the left menu.
  5. As you can see, there are two zones around Furhat (shown as grey circles in the situation view). When the user enters the inner zone, it is deemed to enter the interaction, and Furhat will start interacting with the user. To simulate this in the SDK, you can double-click on the situation view somewhere inside Furhat's inner interaction space to add a virtual user. This should trigger the interaction and allow you to test it.

You can also drag the user around to move it. As you can see, Furhat will continue to attend the user. When the user leaves the outer zone, the user will be considered to have left the interaction and Furhat will stop interacting with the user. If you double click on a user, it will disappear. You can also insert more users by double-clicking again somewhere else.

Running a skill on a robot from IntelliJ

  • Follow the instructions above. Then do "Edit Run Configurations" in IntelliJ and copy the created Run configuration. Name the new configuration "Run on Robot" or similar.
  • Add the JVM argument -Dfurhatos.skills.brokeraddress=<IP-ADDRESS-OF-ROBOT> with the IP of your robot. The port does not need to be specified.
  • Now you have two Run Configurations, one for the virtual Furhat and one for the robot.

From within the skill, you can use function isVirtual() to check if the skill is running on the SDK or is deployed on a Robot.

Packaging the skill into a .skill file

Gradle is used to build and package the skill project into a .skill file that can be run on a robot or on the virtual robot.

  1. locate the gradle tab typically located to your right in IntelliJ
  2. Select: <your project> - Tasks - shadow - shadowJar
  3. Run the shadowJar build target

If you prefer to use the command line interface, you can instead call './gradlew shadowJar' from the skill folder

The resulting .skill file will be located in <project folder>/build/libs

The build target can be configured in the build.gradle file in your project.

Running a packaged skill from the SDK Launcher

First make sure the SDK is running, then:

  1. Click the button marked "Start skill"
  2. Select a .skill file from your file system, and click "start skill"
  3. In the console you can now see the output of the skill.
  4. Click the button marked "Stop skill" to stop the skill.

Running a packaged skill from the command line

When a skill is packaged the .skill can be run from a terminal/console by using the following command.

cd directory/of/skill/file
java -jar <name_of_skill_file>.skill

Important note: If your skill crashes due to "Error: Could not find or load main class", try running the following command:

java -cp <name_of_skill_file>.skill furhatos.skills.Skill

Deploying to, and running a skill deployed on, a robot

To deploy a skill to a Furhat robot, you need to package the skill and then upload it through the robot's web-interface:

  • Go to your robot's web-interface (see Furhat docs)
  • Go to the skills page and import the .skill file
  • The skill should then show up in the skills list

To run a deployed skill on Furhat, you can;

  1. Click the play-button on the skill in the skills list in the web interface.
  2. Enter the on-face menu by using the rotary button on the back of the robot and run the skill from there.

You can also run the skill automatically on robot startup by checking the autostart checkbox in the skills list on the web interface.

Alternatively, you can also use the on-face displayed menu to select a skill to run.

Example skills

For inspiration, check out our example skills. We will continuously update and add new example skills here to show of new and improved features. Import the skills similarly to how you would import skills created locally.