Tutorial 4: Write Your Own Device

In this tutorial, we will use The Cat API again as a running example. But unlike Tutorial 2, we will explain more details about each step. We encourage you to create a device you are interested in to work through this tutorial. To avoid getting into the details of the OAuth authentication or configuration for IoTs too early, we recommend to try a public web service which requires no authentication or only needs an API key. You can find a collective list of public APIs from toddmotto/public-apis.

Get started

A developer account is required to make contributions to Thingpedia. You can request a developer account from here. Once you are approved by the Thingpedia administrators (you can check your status from your profile page), you will be able to upload your own devices to Thingpedia and enable users to use it through Almond.

The device creation page lives here. It can be reached from the "Upload a new device" button at the bottom of Thingpedia Portal or Thingpedia Developer Portal. It looks like this:

screenshot


Fill in basic information

First, you will need to fill some basic metadata about your device, including ID, Name, Description, Category, and Icon. The information will be used to present your device to the users in Thingpedia and Almond clients.

ID is a string that uniquely identifies the device class. A reverse domain name notation is required. E.g., ID of The Cat API is com.thecatapi because it is service provided by https://thecatapi.com. Similarly, the ID of NASA Daily is gov.nasa and the ID of Google Drive is com.google.drive.

Name and Description on the other hand will be used in the Thingpedia catalog, so that user can know what your device does at a glance. E.g., "The Cat API" looks like this in Thingpedia catalog:

screenshot

Category helps us organize the devices on Thingpedia and makes it easier for users to search for your device. It could be one of the following seven domains:

  • Media: e.g., news, comics, and The Cat API.
  • Social Network: e.g., Facebook, Twitter.
  • Home: smart home devices such as security camera, smart TV.
  • Communication: e.g., messaging services, email, sms.
  • Health & Fitness: e.g., fitness tracker, health-related IoTs.
  • Data Management: e.g., cloud storage services, Github.
  • Others: everything else, such as weather, calendar.

Icon is required to be a .PNG file and a 512x512 picture is recommended.

JS Device Package is an optional package depending on the type of your device specified in the manifest. It contains the JS code describing the details of the configuration and function behavior. This will be introduced in detail later in the tutorial.


Define the device class

All devices published on Thingpedia must include device manifest written in ThingTalk, i.e., manifest.tt. It defines the device class you want to create. Check Writing Device Class for the instructions on how to write a device class.


Supply natural language data

In addition to the device manifest, developers are also required to provide example natural language utterances corresponding to the functions supported by the device in dataset.tt.

The examples provide both documentation for the user (they will be provided by help <name>) and training data for the system. The accuracy of the parser heavily relies on the quality and quantity of examples. Thus, developers are recommended to write as many example commands as possible to cover all possible usage of your device. Check Writing Example Commands for Your Device for detailed instruction on how to write the examples.


Write the JS device package

Depending on the type of your device, you might need to provide a device package containing the Javascript code to describe more details about how the device is configured and how each function behaves. This package will need to be uploaded at the metadata page before you submit. Check Writing JS Device Packages for its tutorial.


Publish and test on Thingpedia

Once you are ready to let other people try your device, you can publish it on Thingpedia. You can submit your device by clicking the Create button at the top of the creation page.

Once submitted, the device is not automatically available to all users. Instead, it is only available to you with your developer key, which you can retrieve from your user profile if you have already been approved to be a developer. You should be able to test your device right away using the Web Almond interface. While if you want to test on Android Almond, you need one more step: go to settings and enable cloud sync.

When you upload your device the first time, you will get some limited natural language support after around 5 minutes. If you think your device is ready and want to get the full natural language support, click on the Start training button at the bottom of the details page of your device to start a new training job. This takes up to 15 hours. You can see the status of the training at the top of the details page for your device. The training is complete when the blue banner disappears. When you edit it later, your device will be usable but the language might not reflect your latest changes. Before the training is ready, you can test by typing ThingTalk directly; this is accomplished using the \t prefix in Web Almond. For example, to test the get command for The Cat API, you can write: \t now => @com.thecatapi.get(count=3) => notify;. Please refer to ThingTalk by Examples for more details about how to write a command in ThingTalk.

The device will become available to other users after being reviewed and approved by a Thingpedia administrator.

Access logs

If you click on Almond Status and Logs on the sidebar, you will access the status of your Almond. In particular, you get access to the full execution log. You can use console.log and console.error from your code to print in these logs.

Or maybe we made a mistake in writing Almond, in which case, when you report a bug we will appreciate seeing the full debug log (don't forget to redact your personal info away!).

Need more examples?

You can go to our Github repository to see more device packages we developed, and observe these concepts we introduced in action.

We recommend to look at the following devices as examples: