Anyone who wants to send data to ARTIK Cloud, whether it’s from a sensor, device or application, needs to create a Manifest. Since this is always the first step, we want to make it as smooth as possible. Last week, we published a new tool called Simple Manifest that makes connecting new devices as easy as drag-and-drop.
What’s a Manifest, anyway?
We like to say that ARTIK Cloud is data agnostic. This means that it will accept data from any source, but in order to make this usable to other devices and developers, you need a way to describe what’s in each message and how it is structured. We call this the Manifest. The Manifest has been available from the beginning, of course, and it was first defined as a Groovy script.
We are now introducing two options for developers. If you’re comfortable with Groovy and want to take advantage of advanced features, you can continue using it with what we now call Advanced Manifest. Everyone else can define a Simple Manifest directly from our Developer Portal: simply fill a form, drag and drop elements and click the button.
The Simple Manifest has three major advantages over the Advanced Manifest:
- Drag-and-drop UI usable from any modern browser
- Manifests are automatically approved and available
- You don’t need to think about how to format messages before defining the Manifest. Our Developer Portal provides a sample in JSON that you can copy-and-paste.
It’s never really winter in San Francisco, but the days are getting longer and warmer—and with that, I have started going out and running again. Since I am running regularly now, I’d like to track my progress and see if I am losing any weight or building up muscle 😉
For my running sessions, I use Simband. I have a scale to measure my weight and I want to calculate my body mass index (BMI). If you are curious about how to calculate BMI and what it’s used for (and its limitations), you can read more about it on Wikipedia.
I want to create a newARTIK Cloud device type that tracks my weight, my height and my BMI. Then I’ll use the User Portal to plot them asARTIK Cloud gets the data. These are the three steps to create my new device type.
Open the Developer Portal, log in and click “+ New Device Type”. Then click the “Create Manifest” button. The Simple Manifest is automatically selected. Now there is a link in the upper-right corner that lets me switch from the new Simple Manifest to the standard Manifest (that we now call Advanced). Please notice that switching between Simple and Advanced will also discard all changes, so don’t do this if you’ve started working on your Manifest.
All I need to do now is start filling the Simple Manifest form. My preference is to first enter all the fields and then organize them. The “FIELD NAME” is a unique name that you assign to each field. Field names in both Simple and Advanced Manifests can only be alphanumeric, meaning they cannot have any spaces or special characters.
As you start typing, ARTIK Cloud auto-suggests a field name. If you are entering a standard field such as “weight”, my recommendation is that you pick the suggested name. This will make it easier for other developers that want to use your device type (if you publish it) and it will make your work easier, too: using one of ARTIK Cloud’s suggested field names automatically populates the “DATA TYPE” and “UNIT” with standard values. I like it when a computer does the work for me!
As you see in the screenshot below, I have already created two fields, “weight” and “height” (both using the standard data type and unit). Next, I create a field called “BMI” that ARTIK Cloud does not recognize. When I click on “DATA TYPE”, a dropdown opens and I can pick the type I want: in this case, “Double”. The unit in my case will be “NONE”, as this is not a standard unit; but as you can see, ARTIK Cloud has a long list that I can browse if that’s more convenient.
Fields can be listed at the root of the Manifest, or they can be grouped. I like my data to be neat and so I created a “FIELD GROUP” called “BMIParameters”. Once I’m done creating fields, I’ll throw them in and order them.
Now that I’ve entered and ordered all my fields the way I like, I click “Save” and navigate to the “Activate Manifest” tab. After I confirm that this device type will include no Actions, I can click the button to “Activate Manifest”. The Manifest is automatically created and approved!
Whether you use the Simple or Advanced Manifest, when you first create a new device type it will be private. Before you can publish the Manifest, you must add a description, categories and tags to make your device type easier to find. You can access the Device Info section by clicking on the “Private” button or via the navigation menu to the left.
When you are ready, you can click “PUBLISH” to make your Manifest public. More on this below.
Private and published device types
While I was playing with my new device type, I realized something wasn’t clear on my mind. I went over to Dan (our Manifest guy) and we had a brief chat about publishing device types. Here’s the down-low: When you create a new device type, it is designated private by default. You can choose to publish it once it has at least one approved Manifest (remember that Simple Manifests are automatically approved!). While your device type is private, only you (the owner) can see it and access it via SAMI’s APIs. Once you publish your device type, it becomes public and anyone who requests a list of device types can see and use it.
Since a published device type is public and usable by users and developers, ARTIK Cloud will not let you revert it to private. That would break other people’s applications. So be careful before you publish a device type and also note that once it’s published, all its subsequent Manifests will be available to users and developers.
The Simple Manifest makes it easy to design how I want to structure data and it also guides me on how to generate messages from my application. Now that I’ve created my new device type, I can click on “VIEW SAMPLE JSON” (only available for Simple Manifests) in the Manifest section and a little popup will show me a sample. What I’m gonna do now is take this sample and replace the values with variables in my application.
Defining new device types in ARTIK Cloud is now as simple as counting to 3. Most devices just want to send data to ARTIK Cloud. With the Simple Manifest, I can do this in minutes and my new device type is immediately available for testing. The JSON sample makes it even simpler to develop.
Top image: Idaho National Laboratory