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?
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:
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:
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,
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.
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.
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.
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.
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!).
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: