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.
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?
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.
First, you will need to fill some basic metadata about your device,
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
Similarly, the ID of NASA Daily is
and the ID of Google Drive is
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:
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.
All devices published on Thingpedia must include device manifest written in ThingTalk,
It defines the device class you want to create.
Check Writing Device Class for the instructions on
how to write a device class.
In addition to the device manifest, developers are also required to provide example
natural language utterances corresponding to the functions supported by the device
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.
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
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.
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.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!).
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: