Tutorial 4: Write Your Own Device

In this tutorial, we will use The Cat API again as a running example. But unlike Tutorial 3, 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.

We also recommend that you visit our community forum, as you will find important information discovered by other developers like you, and you'll be able to connect with other developers working on similar devices; or who knows, maybe someone already has built what you need?

Get started

A developer account is required to make contributions to Thingpedia. You can request a developer account from here. Once you have done that, 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 the Thingpedia Portal or the Almond Developer Console. 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. For more details about testing, see the Testing Guide.

The device will become available to other users after being reviewed and approved by a Thingpedia administrator. You can ask for a review from the device details page; please do so only after your device is complete and thoroughly tested.

NOTE: tutorial submission will not be reviewed. If you would like feedback or have questions, you can ask on the Community Forum instead.

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: